From 3172988ef6c6dd2c505b97865e718c9fa58670a0 Mon Sep 17 00:00:00 2001 From: John Collier Date: Thu, 4 Jun 2026 10:48:03 -0400 Subject: [PATCH 1/3] feat: add agent-ready and init-agents-md skills Adds two general-purpose repository readiness skills: - agent-ready: runs the agentready CLI, parses the assessment JSON, and walks through failing findings in tier order. Supports auto mode (apply deterministic fixes, prompt on ambiguous), review mode (yes/skip/defer/quit per finding), and delegates AGENTS.md creation to init-agents-md. Skips ADRs and design intent in auto mode to avoid fabricating rationale. - init-agents-md: bootstraps AGENTS.md and CLAUDE.md from repo inspection. Detects build/test/lint commands from config files and CI, asks three targeted questions, and writes a minimal draft for human review. Assisted-by: Claude Sonnet 4.6 --- README.md | 7 ++ skills/agent-ready/SKILL.md | 155 +++++++++++++++++++++++++++++++++ skills/init-agents-md/SKILL.md | 151 ++++++++++++++++++++++++++++++++ 3 files changed, 313 insertions(+) create mode 100644 skills/agent-ready/SKILL.md create mode 100644 skills/init-agents-md/SKILL.md diff --git a/README.md b/README.md index 6034395..cacc2d6 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,13 @@ Track work across the four RHDH Jira projects. - **[rhdh](./skills/rhdh/SKILL.md)** — Entry point and router. Detects your environment, runs `doctor` checks, maintains a cross-session worklog, and routes to the right skill. Start here if you're not sure what you need. +### Repository Readiness + +Prepare any git repository for effective AI agent use. + +- **[agent-ready](./skills/agent-ready/SKILL.md)** — Assess a repository against agentready criteria, then walk through and address each gap interactively. Runs the [agentready](https://github.com/ambient-code/agentready) CLI, presents failing findings by tier, and delegates AGENTS.md creation to `init-agents-md`. +- **[init-agents-md](./skills/init-agents-md/SKILL.md)** — Bootstrap `AGENTS.md` and `CLAUDE.md` for any repository. Detects build/test commands from config files and CI, asks 3 targeted questions, and writes a minimal draft for human review. + ### Meta - **[skill-maker](./skills/skill-maker/SKILL.md)** — Create new skills or consolidate existing ones following the [Agent Skills open standard](https://agentskills.io/specification). Interviews you about scope and edge cases before drafting. diff --git a/skills/agent-ready/SKILL.md b/skills/agent-ready/SKILL.md new file mode 100644 index 0000000..20530af --- /dev/null +++ b/skills/agent-ready/SKILL.md @@ -0,0 +1,155 @@ +--- +name: agent-ready +description: | + Assesses a git repository's readiness for use by AI coding agents using the agentready CLI, then walks through and addresses each gap. Use when asked to "assess agent readiness", "run agentready", "check how agent-ready this repo is", "make this repo agent-ready", "improve our agent readiness score", "run the agent ready CLI", "assess this repo for AI agents", or "what's our agentready score". +--- + +## Prerequisites + +`uvx` is a hard dependency. Verify it is available before any other step: + +```bash +uvx --version +``` + +If missing, stop: "`uvx` is required. Install via `pip install uv` or see [uv installation](https://docs.astral.sh/uv/getting-started/installation/)." + +## Step 1: Setup + +**Path:** Default to the current working directory. If the user provided a path, use that instead. Validate it is a git repository: + +```bash +git -C . rev-parse --is-inside-work-tree # replace . with the user-provided path if one was given +``` + +If not a git repository, stop and tell the user. + +**Config file:** Only use a config file if the user explicitly provided one. Do not ask. If a path was given, verify it exists before proceeding. + +## Step 2: Run the assessment + +Create a temp directory and run the assessment: + +```bash +REPORT_DIR=$(mktemp -d) # on Windows: use %TEMP% or Python tempfile +uvx --from git+https://github.com/ambient-code/agentready agentready -- assess \ + -o "$REPORT_DIR" \ + . # replace . with the user-provided path if one was given +``` + +Append `-c ` to the command if the user provided a config file. + +Note the value of `$REPORT_DIR` — shell variables do not persist across tool calls and Step 5 will need it. + +Parse `$REPORT_DIR/assessment-latest.json`. Extract: +- `overall_score`, `certification_level` +- `findings` — each with `attribute.id`, `attribute.tier`, `attribute.default_weight`, `attribute.name`, `status`, `score`, `evidence`, `remediation` + +## Step 3: Present summary + +Show a brief summary before diving into findings: + +``` +Score: /100 — +Failing: findings ( Tier 1, Tier 2, ...) +``` + +If there are no failing findings, congratulate the user and stop — do not ask to work through anything. + +Otherwise ask: + +> "Fix applicable findings automatically, or review each one individually? +> **auto** (default) — apply self-contained fixes immediately; prompt only when input is needed +> **review** — prompt yes/skip/defer/quit for every finding" + +Default to **auto** if the user just says yes, presses Enter, or says "fix everything". + +## Step 4: Work through findings + +Work only through findings where `status == "fail"`. Skip `not_applicable` and `pass` findings silently. + +**Sort order:** ascending tier (Tier 1 first), then descending `attribute.default_weight` within each tier. + +### Auto mode + +Apply each fix without prompting **unless** any of the following are true — in which case, pause and prompt: + +- The fix requires project-specific input (CI platform, package ecosystem, project name, language) +- The finding might not apply to this repo type (e.g., `src/` layout for a GitOps YAML repo, lock files for a repo with no package dependencies) — present it and ask whether to apply or skip +- It is the `agent_instructions` finding — always delegate to `init-agents-md` interactively + +**Skip without prompting** findings that require human rationale to be meaningful — ADRs, design intent, and architecture decisions. These cannot be generated without fabricating context the agent doesn't have. + +After processing all findings, list what was applied, what was prompted, and what was skipped, then proceed to Step 5. + +### Review mode + +For each finding, present: + +``` +[Tier ] — /100 +Evidence: + +Remediation: + +Apply this fix? [yes / skip / defer / quit] +``` + +**yes** — apply the fix (see special cases below), then move to the next finding. +**skip** — move on; do not revisit. Use this if the finding doesn't apply to this repo. +**defer** — note it; present again after the re-run. +**quit** — stop immediately. + +**ADR and design intent findings in review mode:** Do not present the JSON remediation. Instead ask: + +> "Do you have any architectural decisions worth capturing here? If so, describe the decision and why it was made — I'll write the ADR. Skip if you'd prefer to add these manually later." + +If the user provides input, write the ADR or design doc using their rationale. If they skip, move on. + +### Special case: `agent_instructions` finding (both modes) + +Do not apply the JSON remediation. Instead, invoke the `init-agents-md` skill: + +> "Invoking the `init-agents-md` skill to create AGENTS.md for this repository." + +Use the Skill tool: `init-agents-md`. After it completes, return to this skill and continue with the next finding. + +### Applying fixes (auto and review modes) + +Use the `remediation.steps`, `remediation.commands`, and `remediation.examples` from the JSON as the implementation guide. Do not invent steps beyond what the JSON provides. + +## Step 5: Re-run and present results + +Re-run the assessment (shell variables from Step 2 do not persist — create a new temp dir): + +```bash +REPORT_DIR=$(mktemp -d) # on Windows: use %TEMP% or Python tempfile +uvx --from git+https://github.com/ambient-code/agentready agentready -- assess \ + -o "$REPORT_DIR" \ + . # or user-provided path +``` + +Include `-c ` if the user provided a config file. + +Show before/after: + +``` +Before: /100 () +After: /100 () + +Remaining failures: findings +``` + +If there are remaining failures (including deferred ones), ask: + +> "Would you like to continue addressing the remaining findings?" + +If yes, repeat Step 4 with the remaining failures. If no, stop. + +## Gotchas + +- The first `uvx` run fetches and builds agentready from GitHub — this can take 30–60 seconds. Subsequent runs use the cache and are much faster. If the fetch fails (network error, build error), tell the user and stop — do not attempt to proceed without a valid report. +- Do not output the report to the repository directory — use the temp dir to avoid polluting the working tree. +- `not_applicable` findings reflect the detected language stack; do not mention them unless the user asks. +- Deferred findings are not lost — they surface again after the re-run. +- Never invent rationale for ADRs, design docs, or architecture decisions — these require human context the agent doesn't have. In auto mode, skip them. In review mode, ask the user for the rationale before writing anything. diff --git a/skills/init-agents-md/SKILL.md b/skills/init-agents-md/SKILL.md new file mode 100644 index 0000000..5704f65 --- /dev/null +++ b/skills/init-agents-md/SKILL.md @@ -0,0 +1,151 @@ +--- +name: init-agents-md +description: >- + Use when asked to bootstrap, create, initialize, or generate an AGENTS.md or + context file for a repository. Also use when asked to "set up AI agent + context", "create repo context file", "add AGENTS.md", "scaffold context + file", "init agents md", "create CLAUDE.md for a repo", "make my repo + AI-friendly", or "help agents understand this codebase". +--- + +## Goal + +Write a minimal `AGENTS.md` and `CLAUDE.md` in the current working directory. +The output is a starting point — the human must review and edit before committing. + +**Research finding (ETH Zurich, Feb 2026):** Auto-generated context files shipped +as-is reduce agent success rates by ~3% and increase costs by 20-23%. This skill +generates a draft. The human edits it aggressively before committing. + +## Step 1: Check for existing files + +If `AGENTS.md` already exists in the CWD, ask: + +> "AGENTS.md already exists. Overwrite it? (yes/no)" + +If no: stop. Tell the user to delete it first and re-run the skill. +If yes: proceed. + +## Step 2: Detect commands + +Scan these files in the CWD: + +| File | What to extract | +|------|-----------------| +| `package.json` | `scripts` entries matching build, test, lint, typecheck, dev/start | +| `Makefile` / `GNUmakefile` | Targets: build, test, lint, check, run | +| `pyproject.toml` | `[tool.pytest]`, `[tool.ruff]`, `[tool.mypy]`, `[project.scripts]` | +| `setup.cfg`, `tox.ini` | test commands | +| `Taskfile.yml` | task definitions | +| `go.mod` | signals Go project — look for `go test`, `go build`, `go vet` in Makefile or CI | +| `Cargo.toml` | signals Rust — look for `cargo test`, `cargo build`, `cargo clippy` | +| `.github/workflows/*.yml` | `run:` steps containing test/lint/build/typecheck keywords | +| `.gitlab-ci.yml` | `script:` entries | +| `Jenkinsfile` | `sh` steps | + +**Cross-reference rule:** If a `package.json` script and a CI `run:` step agree, use +that form. If they differ, prefer the CI form — it's what actually runs in the +pipeline. If a command cannot be found or confidently inferred, omit it. Do not guess. + +Look for these command categories: + +- **Build** — compiles, bundles, or packages the project +- **Test all** — runs the full test suite without external dependencies +- **Test single file/package** — runs tests for one module +- **Lint** — runs the linter across the project +- **Lint single file** — lints one file in isolation +- **Type check** — static type checking +- **Run/dev** — starts the dev server or app locally + +## Step 3: Interactive prompting + +Ask these questions **one at a time**. Wait for each answer before asking the +next. Accept "skip" or a blank answer to omit that section entirely. + +**Question 1 — Key Conventions:** +> "What are 2-3 project conventions an AI agent couldn't discover by reading the +> code? For example: a required wrapper type for API responses, a naming rule for +> files, a directory that must never be imported directly, or where generated +> files live. Skip if none come to mind." + +**Question 2 — Architecture:** +> "Are there any non-obvious places where things live — for example, a feature +> configured in one place but evaluated elsewhere, or a shared internal API that +> shouldn't be called directly? Skip if the directory names make it obvious." + +**Question 3 — PR Conventions:** +> "Any commit message format, required CI checks, or PR conventions agents should +> know? For example: Conventional Commits format, a required sign-off, or a label +> that blocks merge. Skip if standard." + +## Step 4: Write the files + +Infer the project name from `package.json` (`name` field), `go.mod` (module path, +last segment), `pyproject.toml` (`[project] name`), `Cargo.toml` (`[package] name`), +or the CWD directory name as a fallback. + +Write `AGENTS.md` using only the content that was found or provided. Omit any +section — including its header — where you have nothing to say: + +```markdown +# [Project name] + +## Build & Test Commands +- Build: `[command]` +- Test all: `[command]` +- Test single file: `[command]` +- Lint: `[command]` +- Lint single file: `[command]` +- Type check: `[command]` +- Run: `[command]` + +## Key Conventions +- [convention from Q1 answer] + +## Architecture +- [note from Q2 answer] + +## PR Conventions +- Agent-assisted commits should include an `Assisted-by: ` footer +- [convention from Q3 answer] +``` + +Write `CLAUDE.md` with exactly this content: + +```markdown +@AGENTS.md +``` + +## Step 5: Review gate + +After writing the files, say this exactly: + +> **Review before committing.** +> +> `AGENTS.md` and `CLAUDE.md` have been written to this directory. Before committing: +> +> 1. Open `AGENTS.md` in your editor +> 2. Run each listed command to confirm it actually works +> 3. Delete anything an agent could figure out by reading the code +> 4. Apply this test to every line: *"Would removing this cause an agent to make a +> mistake it wouldn't otherwise make?"* If not, delete it. +> +> Target: under 150 lines. Every unnecessary line makes agents slightly worse at +> following the lines that matter. + +Do not offer to commit the files. Do not suggest the files are ready to use. + +## Gotchas + +- If no commands are found at all, still write the file and tell the user which + files you looked in and found nothing useful +- Do not invent commands not present in config or CI — a hallucinated command is + worse than an omitted one +- If a script name is ambiguous (e.g., `npm run check` could be lint or typecheck), + add a brief inline note: `- Lint: \`npm run check\` (appears to run ESLint)` +- Omit the `## Architecture` and `## Key Conventions` sections entirely when the + user skips those questions — don't leave placeholder comment lines +- Always include the `Assisted-by` footer line in `## PR Conventions` even if the + user skips Q3 — it applies to any repo where agents contribute +- If `CLAUDE.md` already exists and contains more than `@AGENTS.md`, ask before + overwriting it From 786c21cbadc6bd8e41501ac32bf01ef4e314575b Mon Sep 17 00:00:00 2001 From: John Collier Date: Mon, 8 Jun 2026 12:49:38 -0400 Subject: [PATCH 2/3] refactor: consolidate into single RHDH-aware agent-ready skill - Remove init-agents-md as a standalone skill; AGENTS.md generation is now inline within agent-ready, using assessment context (detected languages, CI commands, tech stack) rather than re-scanning from scratch - Add RHDH detection: reads rhdh-repos.md from the rhdh skill to match repo remote URLs; pre-fills AGENTS.md and skips inapplicable findings when a match is found; degrades gracefully if rhdh skill is not installed - Add batch mode: when invoked with no path, offers to assess all RHDH repos in a local directory, producing a summary table with scores and offering to drill into any individual repo - Update README to reflect consolidated skill Assisted-by: Claude Sonnet 4.6 --- README.md | 5 +- skills/agent-ready/SKILL.md | 167 +++++++++++++++++++++++---------- skills/init-agents-md/SKILL.md | 151 ----------------------------- 3 files changed, 119 insertions(+), 204 deletions(-) delete mode 100644 skills/init-agents-md/SKILL.md diff --git a/README.md b/README.md index cacc2d6..2b4e33f 100644 --- a/README.md +++ b/README.md @@ -73,10 +73,7 @@ Track work across the four RHDH Jira projects. ### Repository Readiness -Prepare any git repository for effective AI agent use. - -- **[agent-ready](./skills/agent-ready/SKILL.md)** — Assess a repository against agentready criteria, then walk through and address each gap interactively. Runs the [agentready](https://github.com/ambient-code/agentready) CLI, presents failing findings by tier, and delegates AGENTS.md creation to `init-agents-md`. -- **[init-agents-md](./skills/init-agents-md/SKILL.md)** — Bootstrap `AGENTS.md` and `CLAUDE.md` for any repository. Detects build/test commands from config files and CI, asks 3 targeted questions, and writes a minimal draft for human review. +- **[agent-ready](./skills/agent-ready/SKILL.md)** — Assess RHDH repositories against agentready criteria and address each gap. RHDH-aware: detects the repo from its remote URL, uses `rhdh-repos.md` context to pre-fill `AGENTS.md` and skip inapplicable findings. Supports single-repo and batch modes (assess all RHDH repos in one pass). ### Meta diff --git a/skills/agent-ready/SKILL.md b/skills/agent-ready/SKILL.md index 20530af..53a848e 100644 --- a/skills/agent-ready/SKILL.md +++ b/skills/agent-ready/SKILL.md @@ -1,7 +1,7 @@ --- name: agent-ready description: | - Assesses a git repository's readiness for use by AI coding agents using the agentready CLI, then walks through and addresses each gap. Use when asked to "assess agent readiness", "run agentready", "check how agent-ready this repo is", "make this repo agent-ready", "improve our agent readiness score", "run the agent ready CLI", "assess this repo for AI agents", or "what's our agentready score". + Assesses a git repository's readiness for use by AI coding agents using the agentready CLI, then walks through and addresses each gap. RHDH-aware: detects RHDH repositories and uses rhdh-repos.md context to pre-fill AGENTS.md and skip inapplicable findings. Use when asked to "assess agent readiness", "run agentready", "check how agent-ready this repo is", "make this repo agent-ready", "improve agent readiness score", "assess all RHDH repos", "batch agent readiness", or "onboard this repo for agents". --- ## Prerequisites @@ -14,47 +14,60 @@ uvx --version If missing, stop: "`uvx` is required. Install via `pip install uv` or see [uv installation](https://docs.astral.sh/uv/getting-started/installation/)." -## Step 1: Setup +## Step 1: Mode selection -**Path:** Default to the current working directory. If the user provided a path, use that instead. Validate it is a git repository: +If no path was provided, present a structured choice: + +- **Single repo** — assess the current working directory (default) +- **Batch** — assess all RHDH repositories (see Batch mode below) + +If a path was provided, skip this and proceed to Step 2. + +## Step 2: Setup + +**Path:** Use the provided path, or `.` for the current directory. Validate it is a git repository: ```bash -git -C . rev-parse --is-inside-work-tree # replace . with the user-provided path if one was given +git -C . rev-parse --is-inside-work-tree # replace . with path if provided ``` If not a git repository, stop and tell the user. -**Config file:** Only use a config file if the user explicitly provided one. Do not ask. If a path was given, verify it exists before proceeding. +**RHDH detection:** Check the repo's git remote URL: + +```bash +git -C remote get-url origin 2>/dev/null +``` + +Attempt to read `~/.claude/skills/rhdh/references/rhdh-repos.md`. If the file does not exist, skip RHDH detection and proceed with generic assessment — do not stop or warn the user. If found, check whether the remote URL matches any repo's upstream URL. If matched, note the repo name, tech stack, key paths, and conventions — these inform AGENTS.md generation and finding triage. Store as `rhdh_context`. -## Step 2: Run the assessment +**Config file:** Only use a config file if the user explicitly provided one. Do not ask. -Create a temp directory and run the assessment: +## Step 3: Run the assessment ```bash REPORT_DIR=$(mktemp -d) # on Windows: use %TEMP% or Python tempfile uvx --from git+https://github.com/ambient-code/agentready agentready -- assess \ -o "$REPORT_DIR" \ - . # replace . with the user-provided path if one was given + ``` -Append `-c ` to the command if the user provided a config file. +Append `-c ` if the user provided a config file. -Note the value of `$REPORT_DIR` — shell variables do not persist across tool calls and Step 5 will need it. +Note the value of `$REPORT_DIR` — shell variables do not persist across tool calls. Parse `$REPORT_DIR/assessment-latest.json`. Extract: - `overall_score`, `certification_level` - `findings` — each with `attribute.id`, `attribute.tier`, `attribute.default_weight`, `attribute.name`, `status`, `score`, `evidence`, `remediation` -## Step 3: Present summary - -Show a brief summary before diving into findings: +## Step 4: Present summary ``` Score: /100 — Failing: findings ( Tier 1, Tier 2, ...) ``` -If there are no failing findings, congratulate the user and stop — do not ask to work through anything. +If no failing findings, congratulate the user and stop. Otherwise ask: @@ -62,75 +75,110 @@ Otherwise ask: > **auto** (default) — apply self-contained fixes immediately; prompt only when input is needed > **review** — prompt yes/skip/defer/quit for every finding" -Default to **auto** if the user just says yes, presses Enter, or says "fix everything". +Default to **auto** if the user says yes, presses Enter, or says "fix everything". + +## Step 5: Work through findings -## Step 4: Work through findings +Work only through `status == "fail"` findings. Skip `not_applicable` and `pass` silently. -Work only through findings where `status == "fail"`. Skip `not_applicable` and `pass` findings silently. +**Sort order:** ascending tier, then descending `attribute.default_weight` within each tier. -**Sort order:** ascending tier (Tier 1 first), then descending `attribute.default_weight` within each tier. +If `rhdh_context` is set, skip findings that clearly don't apply to the detected tech stack (e.g., lock file checks for a Bash-only repo, `src/` layout for a GitOps YAML repo) — note them in the summary. ### Auto mode -Apply each fix without prompting **unless** any of the following are true — in which case, pause and prompt: +Apply each fix without prompting **unless**: -- The fix requires project-specific input (CI platform, package ecosystem, project name, language) -- The finding might not apply to this repo type (e.g., `src/` layout for a GitOps YAML repo, lock files for a repo with no package dependencies) — present it and ask whether to apply or skip -- It is the `agent_instructions` finding — always delegate to `init-agents-md` interactively +- The fix requires project-specific input (CI platform, package ecosystem) +- The finding might not apply to this repo type — present it and ask whether to apply or skip -**Skip without prompting** findings that require human rationale to be meaningful — ADRs, design intent, and architecture decisions. These cannot be generated without fabricating context the agent doesn't have. +**Skip without prompting:** ADRs, design intent, architecture decisions — these require human rationale. Note them in the final summary. -After processing all findings, list what was applied, what was prompted, and what was skipped, then proceed to Step 5. +For the `agent_instructions` finding, follow the inline AGENTS.md generation in the `agent_instructions` section below — this applies in both auto and review modes. + +After processing, list what was applied, prompted, and skipped, then proceed to Step 6. ### Review mode -For each finding, present: +For each finding: ``` [Tier ] — /100 -Evidence: +Evidence: Remediation: Apply this fix? [yes / skip / defer / quit] ``` -**yes** — apply the fix (see special cases below), then move to the next finding. -**skip** — move on; do not revisit. Use this if the finding doesn't apply to this repo. -**defer** — note it; present again after the re-run. +**yes** — apply the fix, then move to the next finding. +**skip** — move on; do not revisit. Use this if the finding doesn't apply to this repo. +**defer** — note it; surface again after re-run. **quit** — stop immediately. -**ADR and design intent findings in review mode:** Do not present the JSON remediation. Instead ask: +**ADR and design intent findings:** Do not use JSON remediation. Ask instead: + +> "Do you have any architectural decisions worth capturing? Describe the decision and rationale — I'll write the ADR. Skip to add manually later." + +Write only if the user provides input. Never invent rationale. + +### `agent_instructions` finding (both modes) + +Generate `AGENTS.md` and `CLAUDE.md` inline — do not delegate to another skill. -> "Do you have any architectural decisions worth capturing here? If so, describe the decision and why it was made — I'll write the ADR. Skip if you'd prefer to add these manually later." +**Scan the repo for commands:** +- `package.json` → `scripts` entries (build, test, lint, typecheck, dev) +- `Makefile` / `GNUmakefile` → targets +- `pyproject.toml` → `[tool.pytest]`, `[tool.ruff]`, `[tool.mypy]`, `[project.scripts]` +- `.github/workflows/*.yml` → `run:` steps containing test/lint/build/typecheck keywords -If the user provides input, write the ADR or design doc using their rationale. If they skip, move on. +**If `rhdh_context` is set:** pull key paths, tech stack, conventions, and branching model directly from the matched `rhdh-repos.md` entry — use these to pre-fill AGENTS.md sections and skip generic questions where RHDH context already answers them. -### Special case: `agent_instructions` finding (both modes) +**If not RHDH (or RHDH context doesn't cover it):** ask these three questions one at a time: +1. "What are 2-3 conventions an agent couldn't discover by reading the code? Skip if none." +2. "Any non-obvious architectural decisions or places where things live unexpectedly? Skip if obvious." +3. "Any commit format, CI checks, or PR conventions agents should know? Skip if standard." -Do not apply the JSON remediation. Instead, invoke the `init-agents-md` skill: +Write `AGENTS.md`: -> "Invoking the `init-agents-md` skill to create AGENTS.md for this repository." +```markdown +# -Use the Skill tool: `init-agents-md`. After it completes, return to this skill and continue with the next finding. +## Build & Test Commands +- Build: `` +- Test all: `` +- Test single file: `` +- Lint: `` +- Type check: `` -### Applying fixes (auto and review modes) +## Key Conventions + -Use the `remediation.steps`, `remediation.commands`, and `remediation.examples` from the JSON as the implementation guide. Do not invent steps beyond what the JSON provides. +## Architecture + -## Step 5: Re-run and present results +## PR Conventions +- Agent-assisted commits should include an `Assisted-by: ` footer + +``` + +Write `CLAUDE.md` with exactly: `@AGENTS.md` + +Omit any section — including its header — where there is nothing to say. Do not invent content. + +### Applying other fixes (both modes) -Re-run the assessment (shell variables from Step 2 do not persist — create a new temp dir): +Use `remediation.steps`, `remediation.commands`, and `remediation.examples` from the JSON. Do not invent steps beyond what the JSON provides. + +## Step 6: Re-run and present results ```bash REPORT_DIR=$(mktemp -d) # on Windows: use %TEMP% or Python tempfile uvx --from git+https://github.com/ambient-code/agentready agentready -- assess \ -o "$REPORT_DIR" \ - . # or user-provided path + ``` -Include `-c ` if the user provided a config file. - Show before/after: ``` @@ -140,16 +188,37 @@ After: /100 () Remaining failures: findings ``` -If there are remaining failures (including deferred ones), ask: +If remaining failures (including deferred), ask: "Would you like to continue addressing the remaining findings?" If yes, repeat Step 5. + +## Batch mode + +When the user selects batch assessment: -> "Would you like to continue addressing the remaining findings?" +1. Ask: "What directory are your RHDH repos cloned into? (e.g. `~/git`)" +2. Find subdirectories that are git repos: + +```bash +find -maxdepth 2 -name ".git" -type d | sed 's|/.git||' +``` + +3. For each, check if the remote URL matches a repo in `rhdh-repos.md`. Assess only matching repos. +4. Run the assessment on each matched repo (Step 3) and collect results. +5. Present a summary table: + +``` +Repo Score Level Failing +rhdh 72/100 Bronze 4 +rhdh-operator 45/100 Needs Improvement 11 +rhdh-plugins 88/100 Silver 1 +``` -If yes, repeat Step 4 with the remaining failures. If no, stop. +6. Ask: "Would you like to address findings for any of these repos?" If yes, the user picks one — run Step 3 (assessment) on that repo to get fresh findings, then run Steps 4–6 for it. ## Gotchas -- The first `uvx` run fetches and builds agentready from GitHub — this can take 30–60 seconds. Subsequent runs use the cache and are much faster. If the fetch fails (network error, build error), tell the user and stop — do not attempt to proceed without a valid report. +- The first `uvx` run fetches and builds agentready from GitHub — this can take 30–60 seconds. Subsequent runs use the cache. If the fetch fails, stop — do not proceed without a valid report. - Do not output the report to the repository directory — use the temp dir to avoid polluting the working tree. - `not_applicable` findings reflect the detected language stack; do not mention them unless the user asks. -- Deferred findings are not lost — they surface again after the re-run. -- Never invent rationale for ADRs, design docs, or architecture decisions — these require human context the agent doesn't have. In auto mode, skip them. In review mode, ask the user for the rationale before writing anything. +- Deferred findings surface again after the re-run. +- Never invent rationale for ADRs or design docs. In auto mode, skip them. In review mode, ask for rationale before writing anything. +- In batch mode, only assess repos whose remote URL matches `rhdh-repos.md` — do not assess unrelated repos in the same directory. diff --git a/skills/init-agents-md/SKILL.md b/skills/init-agents-md/SKILL.md deleted file mode 100644 index 5704f65..0000000 --- a/skills/init-agents-md/SKILL.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -name: init-agents-md -description: >- - Use when asked to bootstrap, create, initialize, or generate an AGENTS.md or - context file for a repository. Also use when asked to "set up AI agent - context", "create repo context file", "add AGENTS.md", "scaffold context - file", "init agents md", "create CLAUDE.md for a repo", "make my repo - AI-friendly", or "help agents understand this codebase". ---- - -## Goal - -Write a minimal `AGENTS.md` and `CLAUDE.md` in the current working directory. -The output is a starting point — the human must review and edit before committing. - -**Research finding (ETH Zurich, Feb 2026):** Auto-generated context files shipped -as-is reduce agent success rates by ~3% and increase costs by 20-23%. This skill -generates a draft. The human edits it aggressively before committing. - -## Step 1: Check for existing files - -If `AGENTS.md` already exists in the CWD, ask: - -> "AGENTS.md already exists. Overwrite it? (yes/no)" - -If no: stop. Tell the user to delete it first and re-run the skill. -If yes: proceed. - -## Step 2: Detect commands - -Scan these files in the CWD: - -| File | What to extract | -|------|-----------------| -| `package.json` | `scripts` entries matching build, test, lint, typecheck, dev/start | -| `Makefile` / `GNUmakefile` | Targets: build, test, lint, check, run | -| `pyproject.toml` | `[tool.pytest]`, `[tool.ruff]`, `[tool.mypy]`, `[project.scripts]` | -| `setup.cfg`, `tox.ini` | test commands | -| `Taskfile.yml` | task definitions | -| `go.mod` | signals Go project — look for `go test`, `go build`, `go vet` in Makefile or CI | -| `Cargo.toml` | signals Rust — look for `cargo test`, `cargo build`, `cargo clippy` | -| `.github/workflows/*.yml` | `run:` steps containing test/lint/build/typecheck keywords | -| `.gitlab-ci.yml` | `script:` entries | -| `Jenkinsfile` | `sh` steps | - -**Cross-reference rule:** If a `package.json` script and a CI `run:` step agree, use -that form. If they differ, prefer the CI form — it's what actually runs in the -pipeline. If a command cannot be found or confidently inferred, omit it. Do not guess. - -Look for these command categories: - -- **Build** — compiles, bundles, or packages the project -- **Test all** — runs the full test suite without external dependencies -- **Test single file/package** — runs tests for one module -- **Lint** — runs the linter across the project -- **Lint single file** — lints one file in isolation -- **Type check** — static type checking -- **Run/dev** — starts the dev server or app locally - -## Step 3: Interactive prompting - -Ask these questions **one at a time**. Wait for each answer before asking the -next. Accept "skip" or a blank answer to omit that section entirely. - -**Question 1 — Key Conventions:** -> "What are 2-3 project conventions an AI agent couldn't discover by reading the -> code? For example: a required wrapper type for API responses, a naming rule for -> files, a directory that must never be imported directly, or where generated -> files live. Skip if none come to mind." - -**Question 2 — Architecture:** -> "Are there any non-obvious places where things live — for example, a feature -> configured in one place but evaluated elsewhere, or a shared internal API that -> shouldn't be called directly? Skip if the directory names make it obvious." - -**Question 3 — PR Conventions:** -> "Any commit message format, required CI checks, or PR conventions agents should -> know? For example: Conventional Commits format, a required sign-off, or a label -> that blocks merge. Skip if standard." - -## Step 4: Write the files - -Infer the project name from `package.json` (`name` field), `go.mod` (module path, -last segment), `pyproject.toml` (`[project] name`), `Cargo.toml` (`[package] name`), -or the CWD directory name as a fallback. - -Write `AGENTS.md` using only the content that was found or provided. Omit any -section — including its header — where you have nothing to say: - -```markdown -# [Project name] - -## Build & Test Commands -- Build: `[command]` -- Test all: `[command]` -- Test single file: `[command]` -- Lint: `[command]` -- Lint single file: `[command]` -- Type check: `[command]` -- Run: `[command]` - -## Key Conventions -- [convention from Q1 answer] - -## Architecture -- [note from Q2 answer] - -## PR Conventions -- Agent-assisted commits should include an `Assisted-by: ` footer -- [convention from Q3 answer] -``` - -Write `CLAUDE.md` with exactly this content: - -```markdown -@AGENTS.md -``` - -## Step 5: Review gate - -After writing the files, say this exactly: - -> **Review before committing.** -> -> `AGENTS.md` and `CLAUDE.md` have been written to this directory. Before committing: -> -> 1. Open `AGENTS.md` in your editor -> 2. Run each listed command to confirm it actually works -> 3. Delete anything an agent could figure out by reading the code -> 4. Apply this test to every line: *"Would removing this cause an agent to make a -> mistake it wouldn't otherwise make?"* If not, delete it. -> -> Target: under 150 lines. Every unnecessary line makes agents slightly worse at -> following the lines that matter. - -Do not offer to commit the files. Do not suggest the files are ready to use. - -## Gotchas - -- If no commands are found at all, still write the file and tell the user which - files you looked in and found nothing useful -- Do not invent commands not present in config or CI — a hallucinated command is - worse than an omitted one -- If a script name is ambiguous (e.g., `npm run check` could be lint or typecheck), - add a brief inline note: `- Lint: \`npm run check\` (appears to run ESLint)` -- Omit the `## Architecture` and `## Key Conventions` sections entirely when the - user skips those questions — don't leave placeholder comment lines -- Always include the `Assisted-by` footer line in `## PR Conventions` even if the - user skips Q3 — it applies to any repo where agents contribute -- If `CLAUDE.md` already exists and contains more than `@AGENTS.md`, ask before - overwriting it From 4e58cde4a3303554ccb710710abd019e6dc8f998 Mon Sep 17 00:00:00 2001 From: John Collier Date: Wed, 10 Jun 2026 12:01:31 -0400 Subject: [PATCH 3/3] chore: bump version to 0.5.0; document rhdh-repos.md path assumption - Bump to 0.5.0 (minor) across pyproject.toml, plugin.json, and marketplace.json (2 occurrences) for the new agent-ready skill - Add Gotchas note explaining the ~/.claude/skills/rhdh install-path assumption for rhdh-repos.md detection Assisted-by: Claude Sonnet 4.6 --- .claude-plugin/marketplace.json | 4 ++-- .claude-plugin/plugin.json | 2 +- pyproject.toml | 2 +- skills/agent-ready/SKILL.md | 1 + 4 files changed, 5 insertions(+), 4 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index fae8fcf..3d1f67c 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -5,14 +5,14 @@ }, "metadata": { "description": "Orchestrator skill for RHDH plugin development - onboard, update, and maintain plugins in the Extensions Catalog", - "version": "0.4.0" + "version": "0.5.0" }, "plugins": [ { "name": "rhdh", "source": "./", "description": "Skills for RHDH plugin lifecycle management", - "version": "0.4.0", + "version": "0.5.0", "strict": true } ] diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 342541c..758136d 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "rhdh", "description": "All-in-one toolkit for Red Hat Developer Hub (RHDH). Covers plugin development, overlay management, environment setup, version compatibility, CI/CD, and RHDH ecosystem navigation.", - "version": "0.4.0", + "version": "0.5.0", "author": { "name": "RHDH Store Manager" }, diff --git a/pyproject.toml b/pyproject.toml index e6f9153..bad9a86 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "rhdh-skill" -version = "0.4.0" +version = "0.5.0" description = "Claude Code skill for RHDH plugin development" readme = "README.md" license = "Apache-2.0" diff --git a/skills/agent-ready/SKILL.md b/skills/agent-ready/SKILL.md index 53a848e..a0bcf67 100644 --- a/skills/agent-ready/SKILL.md +++ b/skills/agent-ready/SKILL.md @@ -222,3 +222,4 @@ rhdh-plugins 88/100 Silver 1 - Deferred findings surface again after the re-run. - Never invent rationale for ADRs or design docs. In auto mode, skip them. In review mode, ask for rationale before writing anything. - In batch mode, only assess repos whose remote URL matches `rhdh-repos.md` — do not assess unrelated repos in the same directory. +- `rhdh-repos.md` is expected at `~/.claude/skills/rhdh/references/rhdh-repos.md` — the default install path when using `npx skills add redhat-developer/rhdh-skill`. If the `rhdh` skill was installed to a different prefix, RHDH detection will silently degrade to generic mode. This is by design — no error, no warning.