|
| 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