How to use the Maintain AGENTS.md Files agent skill

What agent skills are and what this one does

An agent skill is a set of instructions packaged as a folder with a SKILL.md file. When it is installed, a compatible agent can load it and follow its procedure for matching tasks. This skill has one file, SKILL.md.

The skill makes the agent read the repository before it writes anything. It looks at existing docs such as README and CONTRIBUTING files, manifests and lockfiles, task runners, and CI workflows, so the commands it records come from the project rather than from guesses. It also reads any existing instruction files that apply to the target path, such as CLAUDE.md or .github/copilot-instructions.md.

• Creates a focused root AGENTS.md when none exists.
• Revises an existing file with small, focused edits instead of a full rewrite.
• Audits a file for stale commands, duplicated policy and unsupported claims.
• Adds narrower nested AGENTS.md files in monorepos only where a subtree genuinely differs.

Install the agents-md skill

Download the ZIP for this skill from the page you are reading. Unzip it into one of these locations, depending on where you want it available:

For all of your projects, put the skill folder in ~/.claude/skills/. For a single project, put it in that project's .claude/skills/ folder. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal use across projects: ~/.claude/skills/
• One project only: .claude/skills/ inside the project
• Claude apps: Settings → Capabilities → Skills, then upload

How to trigger the skill with natural requests

You do not need a special command. Describe the task in plain language that mentions AGENTS.md, and the agent should match the request to the skill. Name the repository or path when it matters, because the skill works from evidence in the current checkout.

The skill's own guidance says to use it when a maintainer-readable, evidence-first edit is the main goal. If you want the packaged generation modes or backup workflow of a different skill called @agents-generator, ask for that instead.

• "Create an AGENTS.md for this repo based on its README, package.json and CI config."
• "Audit the AGENTS.md in this project and fix any commands that no longer match the scripts."
• "Add a packages/api/AGENTS.md that only covers rules that differ from the root file."
• "Reconcile AGENTS.md with CLAUDE.md without deleting any release restrictions."

Examples of what the agent produces

Suppose the evidence shows that package-lock.json selects npm, package.json defines lint, typecheck and test scripts, CI runs those three from the repository root, and src/generated/ is produced by npm run generate. A useful root file might contain a short commands section and a generated-code rule. The skill is told not to add a package manager, command or generated-file rule that the evidence does not establish.

When revising, the skill changes only what is stale. If an existing file has accurate release restrictions but an outdated test command, only the test command and any directly affected explanation should change. The release restrictions stay.

What the skill needs and its safety limits

The skill lists no required tools or packages. It does not run scripts and does not use the network. Its risk rating in the source is critical because it may edit repository files, so review the diff before you commit or hand off the result.

The skill's safety rules say not to include secrets, credentials, internal URLs, personal data or local environment values in the file. It should not run deployment, publication, database mutation or history rewrite commands just to check documentation. It also says not to upload private repository instructions to third-party services without explicit consent.

• Treat the output as a state-changing edit; read the full diff.
• Check that no secrets, internal URLs or personal data slipped into the file.
• Expect the agent to report which files changed, what evidence it used, and which checks it actually ran.

Tips for better results

Give the agent a clear scope: root file, one package, or an audit of existing files. Point it at the existing AGENTS.md or CLAUDE.md so it can preserve maintainer rules instead of inventing new ones.

If the intended policy cannot be found in the repository, the skill is designed to ask you rather than guess. Answer those questions instead of skipping them, because a user who skips review could still publish wrong rules.

• Keep shared rules at the root and put only differences in nested files.
• Ask for targeted commands only where the project actually supports them.
• Make tool-specific files additive, since agents do not all read formats or precedence the same way.
• Check each command yourself before relying on it; the skill separates commands read from config from commands it ran.