Maintain AGENTS.md files from repository evidence

This skill creates, revises, or audits AGENTS.md from repository evidence rather than a fixed template, preferring a focused diff over a wholesale rewrite. It first reads every applicable instruction file already in the repository - existing AGENTS.md, plus CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, .github/instructions/*.instructions.md - and preserves accurate maintainer-authored rules rather than replacing them; it never silently picks a side between conflicting instructions, following the higher-priority applicable rule or asking when the intended policy cannot be established. It then builds a bounded evidence map: README/CONTRIBUTING and docs for project overview, manifests/lockfiles/workspace files/build config for the exact supported commands, CI workflows for required checks (without assuming every CI job is safe to run locally), representative source and test files for naming and layout conventions, and generated files, migrations, vendored code, and secrets boundaries to know what not to touch. Root AGENTS.md carries repository-wide guidance; a nested AGENTS.md is added only when a subtree has materially different commands, architecture, or safety boundaries - shared rules stay at the root, never copied into every package.

Use it when asked to create, update, shorten, or audit AGENTS.md, when a monorepo needs root instructions plus narrower package-level overrides, when existing instructions have stale commands or unsupported claims, or to reconcile AGENTS.md with CLAUDE.md or Copilot instructions. Use @agents-generator instead when the task specifically calls for its packaged generation modes, assets, or backup workflow - this skill is for a maintainer-readable, evidence-first edit as the primary goal.

Input is the repository checkout and its existing instruction files. Output is a direct, testable AGENTS.md (and nested files where warranted) using only headings the evidence supports - repository map, setup and commands, focused validation, change rules, safety boundaries, contribution rules - written as From the repository root, run npm test -- path/to/file.test.ts for a focused test rather than Make sure tests pass and follow best practices. Documentation gets linked rather than copied, and required checks are distinguished from optional, slow, privileged, or deployment-only ones. Before handoff, every changed file is re-read for contradictions, duplicate rules, and stale claims; every mentioned file and directory is confirmed to exist; and commands are cross-checked against manifests or CI. The final report names files changed, evidence used, checks actually run, and unresolved uncertainty - never claiming a command was tested when it was only read from config.

rg --files and rg for repository discovery; the repository's own manifests, lockfiles, CI workflow files, and existing instruction files across tools (Claude, Gemini, Copilot).

Maintainers who want a coding agent's instructions to be true and evidence-backed - exact commands, real file paths, actual CI checks - instead of generic best-practice language, without their own hand-written rules getting silently overwritten.