writing-agents-md — Claude Code skill: write and audit agent instructions
writing-agents-md is a Claude Code skill for writing and reviewing AGENTS.md and CLAUDE.md files. It covers projects with rules agents cannot infer from code or tooling alone.
no license 305 installs ★ 655 updated 2026-10-20
npx skills add pedronauck/skills --skill writing-agents-md -a claude-codeWhat writing-agents-md does
The skill teaches agents what belongs in agent instructions and what does not. Focus on the non-obvious: custom commands, expensive constraints, domain vocabulary, project-specific compatibility decisions. Rules that overlap or grow stale should be removed, refined, or moved to narrower skills.
The method has five steps: read instructions and the repo, review rules (keep, rewrite, relocate, or remove), resolve conflicts, edit the canonical file, and verify important invariants remain reachable. The skill optimizes for context size per representative task, not line count alone. Output a summary of what changed and any remaining tradeoffs.
What it helps with
- Remove stale rules from agent instructions
- Resolve contradictions between commands in AGENTS.md
- Move long rationale into separate skills or links
- Keep only what the agent cannot infer from code
- Reduce instruction context load for typical workflows
Example prompts for the agent
- Audit AGENTS.md in this repo: drop stale rules and move conflicts into skills
- Write CLAUDE.md for the project based on current rules in README and code comments
- Check that all commands in .agents/skills align with AGENTS.md
How to install writing-agents-md
1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill writing-agents-md -a claude-code2Manually: put the files in place
~/.claude/skills/writing-agents-md/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/writing-agents-md/
1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill writing-agents-md -a codex2Manually: put the files in place
.agents/skills/writing-agents-md/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill writing-agents-md -a cursor2Manually: put the files in place
.cursor/skills/writing-agents-md/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pedronauck/skills skills/mine/writing-agents-md2Manually: put the files in place
.github/skills/writing-agents-md/SKILL.md1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill writing-agents-md -a gemini-cli2Platform CLI
gemini skills install https://github.com/pedronauck/skills --path skills/mine/writing-agents-mdManually: put the files in place
.devin/skills/writing-agents-md/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pedronauck/skills --skill writing-agents-md -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about writing-agents-md
How do I install writing-agents-md in Claude Code?
Run npx skills add pedronauck/skills --skill writing-agents-md -a claude-code. The skill will be at ~/.claude/skills/writing-agents-md/SKILL.md.
What does writing-agents-md do?
It helps you write and review agent instruction files (AGENTS.md, CLAUDE.md). It teaches how to distinguish important rules from duplicates and outdated ones, remove what is not needed, and move lengthy explanations into focused skills.
How is writing-agents-md different from just editing instructions manually?
The skill gives you a system: verify each rule is actually needed and only in the right place, resolve conflicts, and account for context size across different tasks. Manual editing can leave duplicate or outdated rules behind.