| name | agents-md |
| description | This skill should be used when the user asks to \\"create AGENTS.md\\", \\"update AGENTS.md\\", \\"maintain agent docs\\", \\"set up CLAUDE.md\\", or needs to keep agent instructions concise. Enforces research-backed best practices for minimal, high-signal agent documentation. |
| type | skill |
| created | 2026-02-27T00:00:00.000Z |
| domain | productivity |
| category | developer-experience |
| risk | unknown |
| source | community |
| tags | ["skill","productivity","developer-experience","agents"] |
Maintaining AGENTS.md
AGENTS.md is the canonical agent-facing documentation. Keep it minimal—agents are capable and don't need hand-holding. Target under 60 lines; never exceed 100. Instruction-following quality degrades as document length increases.
When to Use
- The user asks to create, update, or audit
AGENTS.md or CLAUDE.md.
- The project needs concise, high-signal agent instructions derived from the actual toolchain and repo layout.
- Existing agent documentation is too long, duplicated, or drifting away from real project conventions.
File Setup
- Create
AGENTS.md at project root
- Create symlink:
ln -s AGENTS.md CLAUDE.md
Before Writing
Analyze the project to understand what belongs in the file:
- Package manager — Check for lock files (
pnpm-lock.yaml, yarn.lock, package-lock.json, uv.lock, poetry.lock)
- Linter/formatter configs — Look for
.eslintrc, biome.json, ruff.toml, .prettierrc, etc. (don't duplicate these in AGENTS.md)
- CI/build commands — Check
Makefile, package.json scripts, CI configs for canonical commands
- Monorepo indicators — Check for
pnpm-workspace.yaml, nx.json, Cargo workspace, or subdirectory package.json files
- Existing conventions — Check for existing CONTRIBUTING.md, docs/, or README patterns
Writing Rules
- Headers + bullets — No paragraphs
- Code blocks — For commands and templates
- Reference, don't embed — Point to existing docs: "See
CONTRIBUTING.md for setup" or "Follow patterns in src/api/routes/"
- No filler — No intros, conclusions, or pleasantries
- Trust capabilities — Omit obvious context
- Prefer file-scoped commands — Per-file test/lint/typecheck commands over project-wide builds
- Don't duplicate linters — Code style lives in linter configs, not AGENTS.md
