Maintain AGENTS.md files from repository evidence

This skill creates or improves AGENTS.md agent instructions grounded strictly in evidence from the current repository checkout, so a coding agent can work correctly without rediscovering the repo's workflow. It prefers a focused diff over a wholesale rewrite - there is no universal line limit, required section list, symlink layout, or commit-attribution policy, it follows the repository's own needs and maintainer intent.

Use it when the user asks to create, update, shorten, or audit AGENTS.md; when a monorepo needs root instructions plus narrower package-level overrides; when existing agent instructions contain stale commands, duplicated policy, or unsupported claims; or when the user wants to reconcile AGENTS.md with CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or other repository instruction files. 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, it reads every applicable instruction file, including existing AGENTS.md and tool-specific files, preserving accurate maintainer-authored rules rather than silently choosing between conflicting instructions - following the higher-priority rule, or asking when the intended policy can't be established from the repository. It builds a bounded evidence map: project overview and contribution docs (README*, CONTRIBUTING*), manifests, lockfiles, workspace files, task runners, and build config for exact commands, CI workflows for required checks (without assuming every CI or deployment job is safe to run locally), representative source and test files for conventions, and generated files, migrations, vendored code, large fixtures, secrets boundaries, and production-only operations - preferring rg --files and rg for discovery, and tracking the source of each non-obvious claim so unsupported ones don't enter the final file. It chooses instruction scope - root AGENTS.md for repository-wide guidance, a nested AGENTS.md only for a subtree with materially different commands, architecture, conventions, or safety boundaries, shared rules kept at the root rather than copied into every package - and writes high-signal sections only when evidence supports them: a repository map, setup and commands (exact install, development, build, lint, type-check, and test commands with working directory when not obvious), focused validation, change rules (generated-file ownership, migrations, schemas, APIs, dependencies, cross-package coordination), safety boundaries, and contribution rules, preferring direct, testable statements over vague advice. Before handoff it re-reads every changed file, removes contradictions, duplicate rules, placeholders, and stale claims, confirms every mentioned file and directory exists, cross-checks commands against manifests or CI, and reports files changed, evidence used, checks actually run, and unresolved uncertainty - never claiming a command was tested when it was only read from config.

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

It reconciles with other instruction-file formats in the same repository - CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, .github/instructions/*.instructions.md - making tool-specific files additive rather than assuming all tools interpret formats or precedence identically, and never replacing another tool's file with a symlink unless the user requests it and evidence shows identical content is wanted. Related tools named: @agents-generator for packaged generation, dry-run, update, and backup modes; @folder-specific-claude-and-agents-md for deeper scoped-layout guidance; and the public agents.md format itself.

Maintainers and agents who want AGENTS.md kept accurate and evidence-backed rather than templated or stale. The skill treats itself as state-changing - its diff should be reviewed before handoff - and it never includes secrets, credentials, internal URLs, or personal data in the generated instructions, and never runs deployment, publication, database-mutation, or history-rewrite commands merely to validate documentation.