From spellbook-skills
Maintain AGENTS.md-based project instructions for tools that support AGENTS.md. Use for instruction audits, session learnings, AGENTS.md updates, or migrating useful CLAUDE.md rules into a shared instruction source. Not for general docs, code review, runtime debugging, or global memory unless asked.
How this skill is triggered — by the user, by Claude, or both
Slash command
/spellbook-skills:agents-md-improverThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Maintain concise project instructions for AGENTS.md-compatible tools such as Codex, Copilot, Cursor, and similar coding agents.
Maintain concise project instructions for AGENTS.md-compatible tools such as Codex, Copilot, Cursor, and similar coding agents.
Core principle: Find the effective instruction source -> extract durable learnings -> propose compact diffs -> apply approved changes only.
Announce at start: "I'm using the agents-md-improver skill to maintain concise AGENTS.md project instructions."
AGENTS.md, nested AGENTS.md, or compatible instruction files.Find instruction files from the repository root:
find . \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name ".claude.local.md" \) 2>/dev/null | head -50
Use these targeting rules:
./AGENTS.md: primary shared project instructions for AGENTS.md-compatible tools.AGENTS.md: module-specific instructions; update only when the learning applies to that subtree.AGENTS.md: if it contains only an include such as @./CLAUDE.md, read the target and treat that target as the effective source. Update the target only when the repository intentionally shares one instruction file across tools.CLAUDE.md: Claude Code-specific instructions, or a shared source when AGENTS.md intentionally points to it. Do not update it just because it exists..claude.local.md: personal Claude Code local notes. Do not create or edit it for shared AGENTS.md project memory.~/.codex/AGENTS.md: update only when the user explicitly asks for global behavior..project_context/: historical exploration, plans, and execution summaries. Use it for trace records, not agent steering instructions.If no AGENTS.md exists, propose creating the narrowest useful one, usually ./AGENTS.md.
Choose exactly one primary mode before scanning or proposing edits:
CLAUDE.md or another tool-specific instruction file into an AGENTS.md-compatible source. Reuse Session Learning Mode for extraction rules, but keep tool-only slash commands, hooks, or UI shortcuts in tool-specific files unless the user asks to make them shared.AGENTS.md is prompt context. Prefer dense, operational bullets.
Good format:
- Use `rg` for repo-wide search; fall back only if unavailable.
- Run `pnpm test -- --runInBand` for flaky integration tests in this repo.
- Keep API compatibility normalization in the service layer unless a spec explicitly changes request validation.
Avoid adding:
Always show proposed changes before modifying files. Group proposals by target file.
Use this format:
### Update: ./AGENTS.md
Why: <one-line reason this helps future agent sessions>
```diff
+ <concise addition>
```
If multiple files could be updated, explain the placement tradeoff:
AGENTS.md for project-wide behavior;AGENTS.md for module-local behavior;.project_context/ for historical records;CLAUDE.md only for Claude Code-specific behavior or an intentional shared source.Ask for approval before editing. If the user already explicitly said to apply changes, proceed with the smallest safe patch.
When approved:
.project_context/ as agent steering context. It is for traceability, not instructions that should load every session.CLAUDE.md for a shared AGENTS.md request when the repo does not intentionally share one source file.AGENTS.md and patching the wrapper instead of the effective source.For Repository Audit Mode, provide the quality report format from references/repository-audit.md.
For Session Learning Mode or Migration Mode, provide:
npx claudepluginhub yyykf/spellbook-skills --plugin spellbook-skillsGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.