Skip to content

Commit 3172988

Browse files
johnmcollierjohnmcollier
committed
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
1 parent c415a59 commit 3172988

3 files changed

Lines changed: 313 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,13 @@ Track work across the four RHDH Jira projects.
7171

7272
- **[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.
7373

74+
### Repository Readiness
75+
76+
Prepare any git repository for effective AI agent use.
77+
78+
- **[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`.
79+
- **[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.
80+
7481
### Meta
7582

7683
- **[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.

‎skills/agent-ready/SKILL.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
name: agent-ready
3+
description: |
4+
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".
5+
---
6+
7+
## Prerequisites
8+
9+
`uvx` is a hard dependency. Verify it is available before any other step:
10+
11+
```bash
12+
uvx --version
13+
```
14+
15+
If missing, stop: "`uvx` is required. Install via `pip install uv` or see [uv installation](https://docs.astral.sh/uv/getting-started/installation/)."
16+
17+
## Step 1: Setup
18+
19+
**Path:** Default to the current working directory. If the user provided a path, use that instead. Validate it is a git repository:
20+
21+
```bash
22+
git -C . rev-parse --is-inside-work-tree # replace . with the user-provided path if one was given
23+
```
24+
25+
If not a git repository, stop and tell the user.
26+
27+
**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.
28+
29+
## Step 2: Run the assessment
30+
31+
Create a temp directory and run the assessment:
32+
33+
```bash
34+
REPORT_DIR=$(mktemp -d) # on Windows: use %TEMP% or Python tempfile
35+
uvx --from git+https://github.com/ambient-code/agentready agentready -- assess \
36+
-o "$REPORT_DIR" \
37+
. # replace . with the user-provided path if one was given
38+
```
39+
40+
Append `-c <config-path>` to the command if the user provided a config file.
41+
42+
Note the value of `$REPORT_DIR` — shell variables do not persist across tool calls and Step 5 will need it.
43+
44+
Parse `$REPORT_DIR/assessment-latest.json`. Extract:
45+
- `overall_score`, `certification_level`
46+
- `findings` — each with `attribute.id`, `attribute.tier`, `attribute.default_weight`, `attribute.name`, `status`, `score`, `evidence`, `remediation`
47+
48+
## Step 3: Present summary
49+
50+
Show a brief summary before diving into findings:
51+
52+
```
53+
Score: <overall_score>/100 — <certification_level>
54+
Failing: <N> findings (<N1> Tier 1, <N2> Tier 2, ...)
55+
```
56+
57+
If there are no failing findings, congratulate the user and stop — do not ask to work through anything.
58+
59+
Otherwise ask:
60+
61+
> "Fix applicable findings automatically, or review each one individually?
62+
> **auto** (default) — apply self-contained fixes immediately; prompt only when input is needed
63+
> **review** — prompt yes/skip/defer/quit for every finding"
64+
65+
Default to **auto** if the user just says yes, presses Enter, or says "fix everything".
66+
67+
## Step 4: Work through findings
68+
69+
Work only through findings where `status == "fail"`. Skip `not_applicable` and `pass` findings silently.
70+
71+
**Sort order:** ascending tier (Tier 1 first), then descending `attribute.default_weight` within each tier.
72+
73+
### Auto mode
74+
75+
Apply each fix without prompting **unless** any of the following are true — in which case, pause and prompt:
76+
77+
- The fix requires project-specific input (CI platform, package ecosystem, project name, language)
78+
- 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
79+
- It is the `agent_instructions` finding — always delegate to `init-agents-md` interactively
80+
81+
**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.
82+
83+
After processing all findings, list what was applied, what was prompted, and what was skipped, then proceed to Step 5.
84+
85+
### Review mode
86+
87+
For each finding, present:
88+
89+
```
90+
[Tier <N>] <attribute.name> — <score>/100
91+
Evidence: <evidence items, one per line>
92+
93+
Remediation: <remediation.summary>
94+
95+
Apply this fix? [yes / skip / defer / quit]
96+
```
97+
98+
**yes** — apply the fix (see special cases below), then move to the next finding.
99+
**skip** — move on; do not revisit. Use this if the finding doesn't apply to this repo.
100+
**defer** — note it; present again after the re-run.
101+
**quit** — stop immediately.
102+
103+
**ADR and design intent findings in review mode:** Do not present the JSON remediation. Instead ask:
104+
105+
> "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."
106+
107+
If the user provides input, write the ADR or design doc using their rationale. If they skip, move on.
108+
109+
### Special case: `agent_instructions` finding (both modes)
110+
111+
Do not apply the JSON remediation. Instead, invoke the `init-agents-md` skill:
112+
113+
> "Invoking the `init-agents-md` skill to create AGENTS.md for this repository."
114+
115+
Use the Skill tool: `init-agents-md`. After it completes, return to this skill and continue with the next finding.
116+
117+
### Applying fixes (auto and review modes)
118+
119+
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.
120+
121+
## Step 5: Re-run and present results
122+
123+
Re-run the assessment (shell variables from Step 2 do not persist — create a new temp dir):
124+
125+
```bash
126+
REPORT_DIR=$(mktemp -d) # on Windows: use %TEMP% or Python tempfile
127+
uvx --from git+https://github.com/ambient-code/agentready agentready -- assess \
128+
-o "$REPORT_DIR" \
129+
. # or user-provided path
130+
```
131+
132+
Include `-c <config-path>` if the user provided a config file.
133+
134+
Show before/after:
135+
136+
```
137+
Before: <old_score>/100 (<old_certification_level>)
138+
After: <new_score>/100 (<new_certification_level>)
139+
140+
Remaining failures: <N> findings
141+
```
142+
143+
If there are remaining failures (including deferred ones), ask:
144+
145+
> "Would you like to continue addressing the remaining findings?"
146+
147+
If yes, repeat Step 4 with the remaining failures. If no, stop.
148+
149+
## Gotchas
150+
151+
- 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.
152+
- Do not output the report to the repository directory — use the temp dir to avoid polluting the working tree.
153+
- `not_applicable` findings reflect the detected language stack; do not mention them unless the user asks.
154+
- Deferred findings are not lost — they surface again after the re-run.
155+
- 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.

‎skills/init-agents-md/SKILL.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
name: init-agents-md
3+
description: >-
4+
Use when asked to bootstrap, create, initialize, or generate an AGENTS.md or
5+
context file for a repository. Also use when asked to "set up AI agent
6+
context", "create repo context file", "add AGENTS.md", "scaffold context
7+
file", "init agents md", "create CLAUDE.md for a repo", "make my repo
8+
AI-friendly", or "help agents understand this codebase".
9+
---
10+
11+
## Goal
12+
13+
Write a minimal `AGENTS.md` and `CLAUDE.md` in the current working directory.
14+
The output is a starting point — the human must review and edit before committing.
15+
16+
**Research finding (ETH Zurich, Feb 2026):** Auto-generated context files shipped
17+
as-is reduce agent success rates by ~3% and increase costs by 20-23%. This skill
18+
generates a draft. The human edits it aggressively before committing.
19+
20+
## Step 1: Check for existing files
21+
22+
If `AGENTS.md` already exists in the CWD, ask:
23+
24+
> "AGENTS.md already exists. Overwrite it? (yes/no)"
25+
26+
If no: stop. Tell the user to delete it first and re-run the skill.
27+
If yes: proceed.
28+
29+
## Step 2: Detect commands
30+
31+
Scan these files in the CWD:
32+
33+
| File | What to extract |
34+
|------|-----------------|
35+
| `package.json` | `scripts` entries matching build, test, lint, typecheck, dev/start |
36+
| `Makefile` / `GNUmakefile` | Targets: build, test, lint, check, run |
37+
| `pyproject.toml` | `[tool.pytest]`, `[tool.ruff]`, `[tool.mypy]`, `[project.scripts]` |
38+
| `setup.cfg`, `tox.ini` | test commands |
39+
| `Taskfile.yml` | task definitions |
40+
| `go.mod` | signals Go project — look for `go test`, `go build`, `go vet` in Makefile or CI |
41+
| `Cargo.toml` | signals Rust — look for `cargo test`, `cargo build`, `cargo clippy` |
42+
| `.github/workflows/*.yml` | `run:` steps containing test/lint/build/typecheck keywords |
43+
| `.gitlab-ci.yml` | `script:` entries |
44+
| `Jenkinsfile` | `sh` steps |
45+
46+
**Cross-reference rule:** If a `package.json` script and a CI `run:` step agree, use
47+
that form. If they differ, prefer the CI form — it's what actually runs in the
48+
pipeline. If a command cannot be found or confidently inferred, omit it. Do not guess.
49+
50+
Look for these command categories:
51+
52+
- **Build** — compiles, bundles, or packages the project
53+
- **Test all** — runs the full test suite without external dependencies
54+
- **Test single file/package** — runs tests for one module
55+
- **Lint** — runs the linter across the project
56+
- **Lint single file** — lints one file in isolation
57+
- **Type check** — static type checking
58+
- **Run/dev** — starts the dev server or app locally
59+
60+
## Step 3: Interactive prompting
61+
62+
Ask these questions **one at a time**. Wait for each answer before asking the
63+
next. Accept "skip" or a blank answer to omit that section entirely.
64+
65+
**Question 1 — Key Conventions:**
66+
> "What are 2-3 project conventions an AI agent couldn't discover by reading the
67+
> code? For example: a required wrapper type for API responses, a naming rule for
68+
> files, a directory that must never be imported directly, or where generated
69+
> files live. Skip if none come to mind."
70+
71+
**Question 2 — Architecture:**
72+
> "Are there any non-obvious places where things live — for example, a feature
73+
> configured in one place but evaluated elsewhere, or a shared internal API that
74+
> shouldn't be called directly? Skip if the directory names make it obvious."
75+
76+
**Question 3 — PR Conventions:**
77+
> "Any commit message format, required CI checks, or PR conventions agents should
78+
> know? For example: Conventional Commits format, a required sign-off, or a label
79+
> that blocks merge. Skip if standard."
80+
81+
## Step 4: Write the files
82+
83+
Infer the project name from `package.json` (`name` field), `go.mod` (module path,
84+
last segment), `pyproject.toml` (`[project] name`), `Cargo.toml` (`[package] name`),
85+
or the CWD directory name as a fallback.
86+
87+
Write `AGENTS.md` using only the content that was found or provided. Omit any
88+
section — including its header — where you have nothing to say:
89+
90+
```markdown
91+
# [Project name]
92+
93+
## Build & Test Commands
94+
- Build: `[command]`
95+
- Test all: `[command]`
96+
- Test single file: `[command]`
97+
- Lint: `[command]`
98+
- Lint single file: `[command]`
99+
- Type check: `[command]`
100+
- Run: `[command]`
101+
102+
## Key Conventions
103+
- [convention from Q1 answer]
104+
105+
## Architecture
106+
- [note from Q2 answer]
107+
108+
## PR Conventions
109+
- Agent-assisted commits should include an `Assisted-by: <model>` footer
110+
- [convention from Q3 answer]
111+
```
112+
113+
Write `CLAUDE.md` with exactly this content:
114+
115+
```markdown
116+
@AGENTS.md
117+
```
118+
119+
## Step 5: Review gate
120+
121+
After writing the files, say this exactly:
122+
123+
> **Review before committing.**
124+
>
125+
> `AGENTS.md` and `CLAUDE.md` have been written to this directory. Before committing:
126+
>
127+
> 1. Open `AGENTS.md` in your editor
128+
> 2. Run each listed command to confirm it actually works
129+
> 3. Delete anything an agent could figure out by reading the code
130+
> 4. Apply this test to every line: *"Would removing this cause an agent to make a
131+
> mistake it wouldn't otherwise make?"* If not, delete it.
132+
>
133+
> Target: under 150 lines. Every unnecessary line makes agents slightly worse at
134+
> following the lines that matter.
135+
136+
Do not offer to commit the files. Do not suggest the files are ready to use.
137+
138+
## Gotchas
139+
140+
- If no commands are found at all, still write the file and tell the user which
141+
files you looked in and found nothing useful
142+
- Do not invent commands not present in config or CI — a hallucinated command is
143+
worse than an omitted one
144+
- If a script name is ambiguous (e.g., `npm run check` could be lint or typecheck),
145+
add a brief inline note: `- Lint: \`npm run check\` (appears to run ESLint)`
146+
- Omit the `## Architecture` and `## Key Conventions` sections entirely when the
147+
user skips those questions — don't leave placeholder comment lines
148+
- Always include the `Assisted-by` footer line in `## PR Conventions` even if the
149+
user skips Q3 — it applies to any repo where agents contribute
150+
- If `CLAUDE.md` already exists and contains more than `@AGENTS.md`, ask before
151+
overwriting it

0 commit comments

Comments
 (0)