agents-md skill

Maintain AGENTS.md from repository evidence

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

unsupported claims.

• 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

.github/copilot-instructions.md, or other repository instruction files.

• The user wants to reconcile AGENTS.md with 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.

How It Works

1. Preserve existing intent

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.

user requests it and repository evidence shows identical content is desired.

• 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

higher-priority applicable rule, or ask when the intended policy cannot be established from the repository.

• Do not silently choose between conflicting instructions. Follow the

2. Build a bounded evidence map

Inspect only enough of the repository to establish how work is actually done:

CONTRIBUTING*, and relevant docs.

1. Read the project overview and contribution guidance, such as README*,

to identify supported tools and exact commands.

1. Read manifests, lockfiles, workspace files, task runners, and build config

deployment job is safe or appropriate to run locally.

1. Read CI workflows to learn required checks. Do not assume every CI or

conventions.

1. Inspect representative source and test files for naming, layout, and test

secrets boundaries, and production-only operations.

1. Identify generated files, migrations, vendored code, large fixtures,

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:

and test commands, with the working directory when it is not obvious.

• Repository map: the few directories and boundaries an agent must know.
• Setup and commands: exact install, development, build, lint, type-check,

required before handoff.

• Focused validation: targeted checks for a small change and broader checks

dependencies, and cross-package coordination.

• Change rules: generated-file ownership, migrations, schemas, APIs,

deployments, and operations that require explicit authorization.

• Safety boundaries: secrets, production data, destructive commands,

pull-request requirements that affect implementation or handoff.

• Contribution rules: repository-specific naming, formatting, commit, or

Write direct, testable statements. Prefer:

- From the repository root, run `npm test -- path/to/file.test.ts` for a focused test.

over:

- Make sure tests pass and follow best practices.

Link to maintained documentation instead of copying it. Distinguish required checks from optional, slow, privileged, or deployment-only checks.

5. Validate before handoff

checks when useful.

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

and does not conflict accidentally with the root.

1. If nested files changed, confirm each contains only subtree-specific rules

decision or prevent a realistic mistake.

1. Review the diff as a maintainer: every added line should change an agent's

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.

Examples

Create a focused root file