agents-md · diff
git:20260729.2d74b64 to git:20260902.92daffc
177 added, 90 removed. Audit A to A.
---
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.
+ description: Create, revise, or audit AGENTS.md files from repository evidence, verified commands, and correctly scoped instructions without overwriting maintainer intent.
+ category: development
risk: critical
source: community
+ date_added: "2026-03-06"
---
- # Maintaining AGENTS.md
+ # Maintain AGENTS.md from repository evidence
- 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.
+ ## Overview
+ Create or improve agent instructions that help a coding agent change the
+ repository correctly without rediscovering its workflow. Base every
+ repository-specific command, path, and rule on evidence in the current
+ checkout.
+
+ Prefer a focused diff over a wholesale rewrite. There is no universal line
+ limit, required section list, symlink layout, or commit-attribution policy;
+ follow the repository's own needs and maintainer intent.
+
## 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
+ - The user asks to create, update, shorten, or audit `AGENTS.md`.
+ - A monorepo needs root instructions plus narrower package-level overrides.
+ - Existing agent instructions contain stale commands, duplicated policy, or
+ unsupported claims.
+ - The user wants to reconcile `AGENTS.md` with `CLAUDE.md`,
+ `.github/copilot-instructions.md`, or other repository instruction files.
- 1. Create `AGENTS.md` at project root
- 2. Create symlink: `ln -s AGENTS.md CLAUDE.md`
+ Use `@agents-generator` instead when the task specifically calls for its
+ packaged generation modes, assets, or backup workflow. Use this skill when a
+ maintainer-readable, evidence-first edit is the primary goal.
- ## Before Writing
+ ## How It Works
- Analyze the project to understand what belongs in the file:
+ ### 1. Preserve existing intent
- 1. **Package manager** — Check for lock files (`pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `uv.lock`, `poetry.lock`)
- 2. **Linter/formatter configs** — Look for `.eslintrc`, `biome.json`, `ruff.toml`, `.prettierrc`, etc. (don't duplicate these in AGENTS.md)
- 3. **CI/build commands** — Check `Makefile`, `package.json` scripts, CI configs for canonical commands
- 4. **Monorepo indicators** — Check for `pnpm-workspace.yaml`, `nx.json`, Cargo workspace, or subdirectory `package.json` files
- 5. **Existing conventions** — Check for existing CONTRIBUTING.md, docs/, or README patterns
+ Before writing, read every instruction file that applies to the target path,
+ including existing `AGENTS.md` files and relevant tool-specific files such as
+ `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, and
+ `.github/instructions/*.instructions.md`.
- ## Writing Rules
+ - Improve an existing `AGENTS.md` in place when possible.
+ - Preserve accurate maintainer-authored rules and repository-specific policy.
+ - Do not replace another tool's instruction file with a symlink unless the
+ user requests it and repository evidence shows identical content is desired.
+ - Do not silently choose between conflicting instructions. Follow the
+ higher-priority applicable rule, or ask when the intended policy cannot be
+ established from the repository.
- - **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
+ ### 2. Build a bounded evidence map
- ## Required Sections
+ Inspect only enough of the repository to establish how work is actually done:
- ### Package Manager
- Which tool and key commands only:
- ```markdown
- ## Package Manager
- Use **pnpm**: `pnpm install`, `pnpm dev`, `pnpm test`
- ```
+ 1. Read the project overview and contribution guidance, such as `README*`,
+ `CONTRIBUTING*`, and relevant docs.
+ 2. Read manifests, lockfiles, workspace files, task runners, and build config
+ to identify supported tools and exact commands.
+ 3. Read CI workflows to learn required checks. Do not assume every CI or
+ deployment job is safe or appropriate to run locally.
+ 4. Inspect representative source and test files for naming, layout, and test
+ conventions.
+ 5. Identify generated files, migrations, vendored code, large fixtures,
+ secrets boundaries, and production-only operations.
- ### File-Scoped Commands
- Per-file commands are faster and cheaper than full project builds. Always include when available:
+ Prefer `rg --files` and `rg` for discovery when available. Track the source of
+ each non-obvious command or rule so unsupported claims do not enter the final
+ file.
+
+ ### 3. Choose the instruction scope
+
+ Use the root `AGENTS.md` for repository-wide guidance. Add or revise a nested
+ `AGENTS.md` only when a subtree has materially different commands,
+ architecture, conventions, or safety boundaries.
+
+ Keep shared rules at the root and only differences in nested files. For tools
+ that implement the public AGENTS.md convention, the nearest file in the
+ directory tree controls the working subtree. Do not copy the full root file
+ into every package.
+
+ ### 4. Write high-signal guidance
+
+ Choose headings that fit the repository instead of forcing a fixed template.
+ Include the following only when supported by evidence:
+
+ - **Repository map:** the few directories and boundaries an agent must know.
+ - **Setup and commands:** exact install, development, build, lint, type-check,
+ and test commands, with the working directory when it is not obvious.
+ - **Focused validation:** targeted checks for a small change and broader checks
+ required before handoff.
+ - **Change rules:** generated-file ownership, migrations, schemas, APIs,
+ dependencies, and cross-package coordination.
+ - **Safety boundaries:** secrets, production data, destructive commands,
+ deployments, and operations that require explicit authorization.
+ - **Contribution rules:** repository-specific naming, formatting, commit, or
+ pull-request requirements that affect implementation or handoff.
+
+ Write direct, testable statements. Prefer:
+
```markdown
- ## File-Scoped Commands
- | Task | Command |
- |------|---------|
- | Typecheck | `pnpm tsc --noEmit path/to/file.ts` |
- | Lint | `pnpm eslint path/to/file.ts` |
- | Test | `pnpm jest path/to/file.test.ts` |
+ - From the repository root, run `npm test -- path/to/file.test.ts` for a focused test.
```
- ### Commit Attribution
- Always include this section. Agents should use their own identity:
+ over:
+
```markdown
- ## Commit Attribution
- AI commits MUST include:
- ```
- Co-Authored-By: (the agent model's name and attribution byline)
- ```
- Example: `Co-Authored-By: Claude Sonnet 4 <noreply@example.com>`
+ - Make sure tests pass and follow best practices.
```
- ### Key Conventions
- Project-specific patterns agents must follow. Keep brief.
+ Link to maintained documentation instead of copying it. Distinguish required
+ checks from optional, slow, privileged, or deployment-only checks.
- ## Optional Sections
+ ### 5. Validate before handoff
- Add only if truly needed:
- - API route patterns (show template, not explanation)
- - CLI commands (table format)
- - File naming conventions
- - Project structure hints (point to critical files, flag legacy code to avoid)
- - Monorepo overrides (subdirectory `AGENTS.md` files override root)
+ 1. Re-read each changed `AGENTS.md` completely.
+ 2. Remove contradictions, duplicate rules, placeholders, and stale claims.
+ 3. Confirm every mentioned file and directory exists.
+ 4. Cross-check commands against manifests or CI, and run safe, proportionate
+ checks when useful.
+ 5. If nested files changed, confirm each contains only subtree-specific rules
+ and does not conflict accidentally with the root.
+ 6. Review the diff as a maintainer: every added line should change an agent's
+ decision or prevent a realistic mistake.
- ## Anti-Patterns
+ Report the files changed, evidence used, checks actually run, and unresolved
+ uncertainty. Never say a command was tested when it was only read from config.
- Omit these:
- - "Welcome to..." or "This document explains..."
- - "You should..." or "Remember to..."
- - Linter/formatter rules already in config files (`.eslintrc`, `biome.json`, `ruff.toml`)
- - Listing installed skills or plugins (agents discover these automatically)
- - Full project-wide build commands when file-scoped alternatives exist
- - Obvious instructions ("run tests", "write clean code")
- - Explanations of why (just say what)
- - Long prose paragraphs
+ ## Examples
- ## Example Structure
+ ### Create a focused root file
+ Evidence found:
+
+ - `package-lock.json` selects npm.
+ - `package.json` defines `lint`, `typecheck`, and `test` scripts.
+ - CI runs those three checks from the repository root.
+ - `src/generated/` is produced by `npm run generate`.
+
+ A useful result might include:
+
```markdown
- # Agent Instructions
+ # Agent instructions
- ## Package Manager
- Use **pnpm**: `pnpm install`, `pnpm dev`
+ ## Commands
+ - Run commands from the repository root.
+ - Install with `npm ci`.
+ - For handoff, run `npm run lint`, `npm run typecheck`, and `npm test`.
- ## Commit Attribution
- AI commits MUST include:
- ```
- Co-Authored-By: (the agent model's name and attribution byline)
+ ## Generated code
+ - Do not edit `src/generated/` directly; update its source and run `npm run generate`.
```
- ## File-Scoped Commands
- | Task | Command |
- |------|---------|
- | Typecheck | `pnpm tsc --noEmit path/to/file.ts` |
- | Lint | `pnpm eslint path/to/file.ts` |
- | Test | `pnpm jest path/to/file.test.ts` |
+ Do not add a package manager, command, or generated-file rule that the evidence
+ did not establish.
- ## API Routes
- [Template code block]
+ ### Revise without erasing policy
- ## CLI
- | Command | Description |
- |---------|-------------|
- | `pnpm cli sync` | Sync data |
- ```
+ If an existing file has accurate release restrictions but a stale test
+ command, change only the stale command and any directly affected explanation.
+ Preserve the release restrictions, even when a shorter replacement would look
+ cleaner.
+ ## Best Practices
+
+ - Keep instructions concise enough to scan, but let repository complexity
+ determine length.
+ - Prefer repository-specific decisions over generic engineering advice.
+ - Include targeted commands when the project supports them; do not invent a
+ file-scoped invocation for a tool that only supports suite-level runs.
+ - State where commands run and whether they modify files.
+ - Reference formatter and linter config instead of restating every rule.
+ - Make tool-specific files additive when their semantics differ; do not assume
+ all agents interpret formats or precedence identically.
+
+ ## Security & Safety Notes
+
+ - Treat this as a state-changing skill because it may edit repository files.
+ Review the diff before handoff.
+ - Never include secrets, credentials, internal URLs, personal data, or local
+ environment values in agent instructions.
+ - Do not run deployment, publication, database mutation, history rewrite, or
+ other consequential commands merely to validate documentation.
+ - Preserve approval gates already present in repository policy.
+ - Do not upload private repository instructions to third-party services. Ask
+ for explicit consent before transmitting any repository content externally.
+
+ ## Common Pitfalls
+
+ - **Guessing commands:** infer tools from manifests and CI, not popularity.
+ - **Forcing one layout:** a symlink or a fixed section list may erase
+ tool-specific or maintainer-authored guidance.
+ - **Overwriting an existing file:** make the smallest evidence-backed change.
+ - **Copying the README:** include only information that changes agent behavior.
+ - **Duplicating nested files:** keep shared guidance at the root and local
+ differences near the relevant code.
+ - **Claiming validation that did not run:** distinguish inspection from
+ execution in the handoff.
+
## Limitations
- - Use this skill only when the task clearly matches the scope described above.
- - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
+
+ - Repository evidence can be incomplete or contradictory; ask when a material
+ policy choice cannot be resolved safely.
+ - A documented command may still require credentials, services, or operating
+ system support that are unavailable locally.
+ - AGENTS.md support and precedence vary across coding tools; verify the target
+ tool when interoperability matters.
+ - This skill improves instruction quality but cannot prove that every future
+ agent will follow the file correctly.
+
+ ## Related Skills and Tools
+
+ - `@agents-generator` - packaged generation, dry-run, update, and backup modes.
+ - `@folder-specific-claude-and-agents-md` - deeper guidance for scoped
+ Claude/AGENTS instruction layouts.
+ - [agents.md](https://agents.md/) - public format and scope guidance.