Plugins, Gists, and Rotting AGENTS.md

Diff a mature collection of AGENTS.md files and the contradictions arrive quickly: two test commands for sibling packages, a package-manager rule one repo requires and another bans, or a commit convention copied into only part of a monorepo.

Call the result the agent lottery: same agent, same job, different behavior depending on which repository it is standing in, because the loaded instructions are whichever copy rotted least. Instruction rot is a quiet failure mode. It turns each repository into a slightly different set of hidden rules.

This hygiene playbook has four moves: what belongs in AGENTS.md, what belongs in a skill, how gists should be used, and a quarterly rot audit with receipts on top. It is the same instinct that runs the rest of a mixed agent fleet: one operating layer, traceable orders, and fewer agents guessing which copy is current.

The wound, named

The ecosystem already has distribution machinery. Anthropic maintains a community plugin directory, and Cursor publishes its plugin marketplace source. Those registries solve discovery better than a pasted snippet. Backpass attacks a related problem from another angle: it treats unsuccessful agent trajectories as evidence, then proposes durable instruction or skill improvements. It is not an AGENTS.md synchronizer, but its feedback-loop framing is useful here — instructions should change because evidence changed, not because another copy appeared in chat.

For anyone arriving from search: AGENTS.md is an open convention for agent instruction files. The root file covers the repository broadly; nested files can specialize instructions for subtrees, and the closest file in the directory tree takes precedence. The convention suggests build commands, test commands, style rules, security considerations, and local gotchas. Support and exact precedence still vary by harness, so verify the tool you run rather than assuming every CLI treats the file identically.

The multi-CLI reality of 2026 makes all of it worse. A file written for one agent may be read by several, while each harness can use different discovery and precedence rules. Rot varies by repo, subtree, and reader. The only safe starting point is an inventory of every instruction file that can govern the path being edited.

Loaded instructions make rot expensive in three modes. Drift: a file is fixed in one repository but not another, so siblings disagree with reality. Conflict: two governing files state different versions of a shared rule, and precedence changes with the edited path. Multiplication: the same portable procedure is pasted into every repository, and each copy ages alone. All three can stay invisible until a change follows the wrong rule, while every stale line also taxes the context.

What belongs in AGENTS.md: this repo’s facts, nothing else

The sorting test starts with one question: does this line describe this repository or subtree? If yes, AGENTS.md is a natural home. If it describes a reusable procedure, it is usually a skill. The test is a maintenance heuristic, not part of the convention itself.

What survives that test is short and operational: build and test commands as the repository actually runs them, layout notes an agent cannot infer quickly, conventions with a reason, and local gotchas. A scoped example looks like this:

# AGENTS.md — billing-service

- Build: `pnpm build` (Node 24; do not use npm here)
- Test: `pnpm vitest run` — integration tests need `docker compose up -d db`
- Migrations live in `db/migrations/`; never edit an applied migration
- `src/fixtures/` is generated by `pnpm gen:fixtures`; never hand-edit
- API errors follow RFC 9457 problem+json; see `src/errors.ts`

A screenful, current, and true only here. When the file grows past that, it’s usually because something portable snuck in — a review protocol, a release checklist, somebody’s prompt-engineering house style. Those travel, so they rot the moment a second copy exists. Out they go, to the next section.

Security and workflow constraints may belong in AGENTS.md when they are specific to the repository; the convention explicitly allows security considerations and deployment guidance. The limit is enforcement. “Never read production credentials” in Markdown is context, not an access control. Back it with the modes, scopes, and sandbox controls the harness actually enforces. Document the repo rule in AGENTS.md; enforce the boundary outside the prompt.

What belongs in a skill: procedures that travel

The moment the same procedural block is headed into a second repository’s AGENTS.md, it is a skill candidate: portable, versioned, and loaded on demand instead of riding every context window indefinitely.

A practical split puts release checklists, migration recipes, review protocols, commit-message house style, and planning procedures into one versioned source each. The names and loading behavior differ by CLI — Claude Code documents skills, while other harnesses have their own instruction packages — but the maintainable shape is a procedure with a version and trigger, kept outside any single repository.

The disk-level answer is a canonical, versioned skills repository plus deterministic installers for each harness. Copy or package the same source into the locations each tool documents, then verify hashes after installation. A symlink or directory junction is fine only when that harness resolves it correctly; do not make filesystem-link behavior the portability contract. Community registries can handle discovery, while your checked-in source and install script handle reproducibility.

Require versioning however installation is wired. Every skill gets a version line and a short changelog entry when it changes. That makes it possible to establish that a session used release checklist v4 before a rollback step existed. An unversioned procedure is difficult to audit.

A review protocol that used to exist in six wordings can now exist once, with generated or installed copies carrying the same version. Multiplication stops being an editorial task and becomes a hash mismatch a script can detect.

What belongs in a gist: discovery, not authority

A gist can be a useful example or transport mechanism. It is a poor runtime source of truth unless an installation process pins a revision, verifies it, and records provenance. A floating gist URL pasted into chat gives an agent no guarantee that the snippet matches the repository or the copy installed yesterday.

So the decision rule has no authoritative gist branch. Repo-specific fact or constraint: AGENTS.md. Portable procedure: a versioned skill. Explanatory material for humans: repository documentation. A gist can point people toward those artifacts, but it should not quietly outrank them.

The quarterly AGENTS.md rot audit

Run the playbook quarterly and after instruction-sensitive incidents. Every contradiction it finds removes one way a future session can start under the wrong rule.

Step 1 — inventory. Every instruction file on the machine, both conventions:

find ~/code -type f \( -name "AGENTS.md" -o -name "CLAUDE.md" \) \
  -not -path '*/.git/*' | sort

Step 2 — cluster the copies. Identical hashes are fine (a template repo, deliberately shared facts). Near-misses are rot:

find ~/code -type f -name "AGENTS.md" -not -path '*/.git/*' -print0 \
  | xargs -0 -r sha256sum | sort

Step 3 — surface the contradictions that bite hardest: commands.

find ~/code -type f -name "AGENTS.md" -not -path '*/.git/*' -print0 \
  | xargs -0 -r grep -H -E "^[[:space:]]*-?[[:space:]]*(Build|Test|Run|Lint)|(npm|pnpm|yarn|make|cargo|pytest|go test)"

Read that output beside each repository’s current package scripts and CI configuration. A command that differs may be valid local specialization or stale drift; the repository decides, not visual similarity.

Step 4 — classify every diverged line. Three verdicts, no fourth: a repo fact stays (re-verified against the repo, not against memory); a portable procedure moves to a skill and gets deleted from every AGENTS.md that carried a copy; a stale line dies. Deletion is most of the value. The file that survives is shorter, truer, and cheaper to load.

Step 5 — record the audit. Save the inventory, hashes, decisions, and verifier in an issue or review artifact tied to a commit. Avoid touching every instruction file only to refresh a date; that creates noisy diffs without proving the commands still work.

Symptom	Rot mode	Fix
Same procedure, four wordings in four repos	Multiplication	Extract to one versioned skill; delete all copies
Test command works here, fails in the sibling repo	Drift	Re-verify per repo; keep only what’s currently true
Two repos disagree on a shared convention	Conflict	Decide once; write it where every agent loads it

Second and later audits run short — most of what dies doesn’t come back, because the skill library absorbed the recidivists.

Quarterly is the floor, not the whole schedule. Three events should trigger an off-cycle audit: a new CLI joins the machine; a repository is forked or templated; or a change follows an unexplained runner, package manager, or convention. The last case also triggers the final move: collect receipts for the instructions that governed the session.

The receipts move: which instructions produced the PR

The audit fixes what the files say. It cannot, by itself, tell you what an agent actually loaded on the day a PR went sideways — the file may have changed since, the harness may have selected a nested file, or an installed skill may have been one version behind. For that you need receipts.

Some harness transcripts or debug logs preserve loaded instructions; others do not expose the system context verbatim. Do not assume the transcript alone proves the briefing. A stronger launcher records the governing instruction paths, content hashes, skill versions, working directory, and agent version at session start. Then the transcript identifies the session and the hash identifies the briefing.

Two search habits make the receipts fast. Filter sessions by repository and time, then search for distinctive command strings, version stamps, or the recorded hash. If the harness captured the instruction text, the exact wording can corroborate it. If it did not, the hash record remains the evidence.

Keep a local library of supported CLI sessions — imported, tagged, searchable — and use it as one part of the evidence layer under instruction hygiene. The audit tells you what agents should read; session metadata and recorded hashes tell you which artifacts governed a particular run. It is the same reflex as refusing to trust an architecture diagram nobody can source: claims need provenance. Automater Lite is free on automater.ai; Pro is $29/year.

Run all four moves and the lottery shrinks. AGENTS.md files stay scoped, procedures have one versioned source, gists remain discovery aids, and each session can carry a verifiable instruction fingerprint. No two agents guessing which copy was intended.

FAQ: AGENTS.md best practices

What should go in an AGENTS.md file?

Repository or subtree-specific guidance: build and test commands as they actually run, layout notes, conventions with reasons, security considerations, and local gotchas. Keep it concise because loaded instructions consume context. Reusable procedures are usually easier to maintain as versioned skills.

What is the difference between AGENTS.md and a skill?

AGENTS.md scopes repository instructions, including nested subtree overrides. A skill packages a reusable procedure that a supporting harness can load when relevant. Repo facts and constraints stay near the code; release checklists, review protocols, and migration recipes are better versioned as skills.

How do I stop AGENTS.md files from drifting across repos?

Audit quarterly: inventory root and nested instruction files, hash and diff related copies, and compare commands with current CI and package scripts. Move portable procedures to a versioned skill, delete stale lines, and record the audit at a commit. Capture governing file hashes at session start so an incident can identify the actual briefing.

Sources

• agents.md — the AGENTS.md convention
• Backpass — transcript-driven instruction and skill improvement
• Anthropic community plugins — official community plugin directory
• Cursor plugins — official plugin marketplace source
• Claude Code skills — skill structure and loading behavior