Parent directory

SKILL.md

5166 bytes

name: agents-md-cleanup description: Cleans and right-sizes repository AGENTS.md files while preserving generated-content contracts and human-owned guidance. Use when an agent guide is too long, repetitive, or overly detailed. disable-model-invocation: true

AGENTS.md cleanup

Use this skill to make AGENTS.md a navigation and working guide, not a reference manual.

Respect the maintenance contract

Many repositories use agents-md.yml to update these guides. Its ownership rules override normal cleanup preferences:

  • Content outside AGENTS-MD:AUTO markers is human-owned. Preserve it verbatim.
  • Content inside the markers is machine-owned and may be reconciled with the code.
  • AGENTS-MD:PIN blocks inside the auto region are human-frozen. Preserve their markers and text byte-for-byte. Do not add pins yourself.
  • If a pinned claim conflicts with the code, leave the pin unchanged and add a short nearby unpinned note for a human.
  • Do not make a stamp-only change to _Last synced by agents-md.yml. Update it only when the same file has other content changes.

Determine scope

  1. Find tracked AGENTS.md files inside the target repository. Do not search parent directories or the whole home directory.
  2. Each guide owns its own directory. A nested guide covers its directory instead of its ancestor guide.
  3. If the task targets all guides, read every guide and explore only its owned scope. In a nested guide, use paths relative to that directory.
  4. Read the current guide, then verify its claims from code, configuration, scripts, and package tests. Never speculate.
  5. Check git status --short before editing. Preserve user changes.
  6. Modify only the requested AGENTS.md files.

Adopt or update a guide

Existing auto-managed guide

Keep its notice, markers, human-owned text, and pins. Edit only the content between these markers:

<!-- AGENTS-MD:AUTO:START -->
<!-- AGENTS-MD:AUTO:END -->

The auto region uses this section order. Omit a section only when it does not apply:

  1. ## Overview
  2. ## Tech Stack
  3. ## Repository Map
  4. ## Setup
  5. ## Build, Test & Run
  6. ## Conventions
  7. ## Testing
  8. ## Gotchas & Constraints
  9. ## Key Entry Points
  10. the Last synced line

Keep required sections concise. For example, list languages and package managers in Tech Stack, but do not add a dependency inventory.

Existing human-only guide

Do not alter, reorder, summarize, or delete its existing text. Insert one auto-managed block after the first top-level heading, or at the start if there is no heading. Add a one-line notice that content outside the markers is human-owned. Keep the existing text outside the new auto block.

New guide

Create the title, auto-maintenance notice, auto block, and a ## Human Notes section after the closing marker.

Keep

Keep concise, stable information that helps an agent find the right place and work safely:

  • a one-paragraph repository purpose
  • a package or module map at directory level
  • setup, build, lint, test, and focused-test commands
  • the usual path for an API or feature change
  • migration, generated-code, secrets, deployment, and production-access constraints
  • pointers to source-of-truth code, manifests, protobuf contracts, and README sections

Remove or condense

Remove information that an agent can find by reading the named file or package:

  • dependency inventories and file-by-file descriptions
  • API schemas, database schemas, and domain edge cases
  • implementation algorithms, cache settings, and internal call sequences
  • code, logging, tracing, test, benchmark, and concurrency examples
  • generic language advice and duplicate sections
  • full environment-variable tables and step-by-step operational commands
  • volatile deployment details, including image tags, ports, hostnames, and workflow internals

Do not remove a non-obvious safety constraint just because its explanation is too detailed. Keep a short rule and point to the source of truth.

Operations and README

Check whether the README documents releases, rollbacks, production commands, breakglass access, and secret procedures.

  • If the README covers a procedure, keep only a short safety rule and a pointer in AGENTS.md.
  • If a critical procedure is absent from the README, retain its safety constraint in AGENTS.md. Add or propose concise README documentation when the task includes documentation changes.
  • Never include credentials, secret values, or breakglass command lines in AGENTS.md.

Persistent scope rule

Put this rule outside the auto region so the maintenance workflow preserves it:

Keep this document lean. It is a navigation and working guide, not a reference manual. Do not add dependency inventories, file-by-file descriptions, API schemas, implementation details, code examples, or step-by-step operational commands. Put durable operational procedures in README.md instead.

Use a different line target only when the user requests one.

Validate

Run git diff --check, verify the line count, and review the diff. Confirm that markers, pins, human-owned text, and safety constraints remain intact.