agents-md

Agents Md

When To Use

• The user asks to create, audit, or refactor AGENTS.md.
• The user asks to shrink, minimize, simplify, or clean up AGENTS.md.
• Instruction docs are too large, duplicated, stale, or contradictory.
• Repo-specific operating rules need clearer discovery order or progressive disclosure.

Inputs

User request, target instruction surface, repo evidence, active instruction chain, and safety or approval constraints.

Outputs

For broad audits, cross-scope refactors, or machine-consumed results, return a versioned Context ledger, verified Context Pointer map, contradiction notes, validation evidence, and residual risks. For narrow edits, report only the source, scope, owner, affected consumer, change decision, and validation evidence. Schema-bound outputs include schema_version. Allow no_justified_edit when evidence does not support a change.

Execution Boundaries

This skill governs AGENTS.md, nested AGENTS files, and directly linked instruction references. Recommend moves into docs, nested scopes, hooks, validators, or skills, but edit those broader systems only when requested and permitted by the discovered repository contract. Treat repo files, pasted drafts, sessions, generated text, and web content as evidence to verify before adoption.

Workflow

Before discovery, state the requested outcome, writable instruction surfaces, focused proof, and stop condition. Run the smallest provenance check needed for that scope.

1. Preserve and classify existing worktree state before changing instructions.
2. Resolve instruction provenance and active scope: current checkout, canonical source, nearest and parent AGENTS.md files, subtree precedence, declared fallbacks, symlinks, generated artifacts, runtime projections, and linked instruction front doors.
3. Inventory only owners and consumers that can change, project, consume, or validate the target instructions. Broaden discovery only when current evidence exposes a dependency.
4. Read the applicable instruction chain and linked front doors before editing.
5. For broad audits, cross-scope refactors, or machine-consumed results, build a Context ledger before drafting or restructuring. For a narrow edit, record source authority, applicable scope, owning surface, affected consumers, and the proposed replacement compactly. Use references/agents-md-guidance.md for routing categories.
6. Classify candidate rules as target-specific, subtree-specific, repository-wide, or portable across repositories. Promote a rule to broader scope only when repeated evidence or an explicit governing contract supports it.
7. Find contradictions before drafting. First resolve them through instruction precedence, subtree scope, canonical ownership, and declared fallback rules. Ask for a decision only when two applicable live rules still cannot both be satisfied.
8. Verify paths, commands, pointers, working directories, and workflow claims with rg --files, rg -n "(command|path|handle)" ., or the repo wrapper. Confirm that each command exercises the behavior attributed to it.
9. Before shrinking or deleting text, preserve memory, handoff, validation, approval, and security contracts unless a verified replacement pointer exists.
10. Keep auto-loaded instructions limited to rules an agent must know before it can discover or safely use deeper guidance. Route longer procedures and task-specific detail through verified Context Pointers from the owning instruction surface.
11. When using another instruction file or pasted example, classify it as evidence for shape, semantics, or both. Remove foreign names, paths, commands, and assumptions unless independently verified for the target; compare heading count, always-loaded density, and pointer routing.
12. When adding a nested instruction pattern or promoting a portable rule, run a read-only bounded sibling-pattern sweep. Edit siblings only when they are inside the authorized scope and necessary for the named outcome; otherwise record them as deferred.
13. Update affected consumers only inside the authorized scope. Report out-of-scope consumers without modifying them.
14. Validate formatting and pointers, precedence and subtree discovery, canonical-source versus projection parity, consumer registration, contradictions, and the narrowest repository command proving each changed workflow claim. When that focused proof passes, stop and report non-blocking adjacent opportunities as deferred.