Maintain agent guidance
Use this skill when the root or nested AGENTS.md tree may have drifted,
grown, or started constraining agents unnecessarily. The goal is not to
document the whole repository. It is to keep inherited context small,
durable, and useful at every scope.
Place context deliberately
Before adding guidance, classify it:
| Destination |
Admission test |
Root AGENTS.md |
Broadly applicable, non-obvious, durable, and costly when missed |
Scoped AGENTS.md |
The same, but limited to one subtree |
| Skill |
A workflow loaded for a recognizable task |
| Existing docs or source |
Detailed reference material or implementation truth |
| Nowhere |
Generic advice or facts an agent can discover cheaply |
Prefer the narrowest destination. Do not repeat the same instruction at
multiple levels.
Seed scopes sparingly
A stable, major subtree may have a stub AGENTS.md before it has local
guidance. A stub provides an obvious extension point and states only that the
area currently adds no instructions beyond its parent. Do not copy root rules
into it.
Seed area boundaries, not every package. Replace a stub only when guidance
passes the same admission test as any other scoped instruction.
Audit procedure
- Inventory the root and nested guidance tree. Read the affected guide, its
parents, and its children fully; inspect their Git diff and relevant
history. Use commit history to find likely drift, not as a requirement to
summarize every intervening commit.
- Check concrete claims against their owning source, manifest, tests, or
official dependency contract. Distinguish shipped behavior from plans.
- Identify content that is duplicated, readily discoverable, local to one
area, task-specific, temporary, ideological, or phrased more absolutely
than the underlying risk requires.
- Remove obsolete context. Move local guidance to a scoped guide and
workflows to skills. Link to detailed references rather than compressing
their contents into a parent guide. Leave intentional stubs free of local
rules.
- Add new guidance only when a recurring or high-cost failure cannot be
prevented more precisely by code, tests, schemas, or tooling. Place it at
the narrowest stable scope.
- Read the result as one instruction set. Resolve overlap and conflicts, and
prefer clear outcomes over prescribed agent process.
Editing principles
- Prefer deletion and routing over denser prose. A soft size target can prompt
review, but do not optimize for a hard line count.
- Hard language is appropriate for security, destructive operations, data
isolation, provenance, authentication, and publish integrity. Elsewhere,
preserve room for task context and engineering judgment.
- Specs, issues, PRs, mockups, tests, and other repositories can all be useful
references. Do not present planned behavior as shipped, and prefer
executable or source-backed evidence for current contracts.
- Avoid freshness dates that imply more verification than Git history proves.
- Keep
AGENTS.md canonical and preserve the CLAUDE.md symlink.
Finish
Check the changed guides, their links, inheritance, and scope boundaries.
Confirm that removing a detail did not remove a genuine high-risk gotcha,
that moved guidance is discoverable from its parent, and that stubs have not
accumulated generic rules. Then verify:
test -L CLAUDE.md && test "$(readlink CLAUDE.md)" = "AGENTS.md"
git diff --check -- AGENTS.md '**/AGENTS.md' .agents/agents-md-sync/SKILL.md
1---2name: agents-md-sync3description: Prune and route AGENTS.md trees for durable, high-signal context.4---56# Maintain agent guidance78Use this skill when the root or nested `AGENTS.md` tree may have drifted,9grown, or started constraining agents unnecessarily. The goal is not to10document the whole repository. It is to keep inherited context small,11durable, and useful at every scope.1213## Place context deliberately1415Before adding guidance, classify it:1617| Destination | Admission test |18|---|---|19| Root `AGENTS.md` | Broadly applicable, non-obvious, durable, and costly when missed |20| Scoped `AGENTS.md` | The same, but limited to one subtree |21| Skill | A workflow loaded for a recognizable task |22| Existing docs or source | Detailed reference material or implementation truth |23| Nowhere | Generic advice or facts an agent can discover cheaply |2425Prefer the narrowest destination. Do not repeat the same instruction at26multiple levels.2728## Seed scopes sparingly2930A stable, major subtree may have a stub `AGENTS.md` before it has local31guidance. A stub provides an obvious extension point and states only that the32area currently adds no instructions beyond its parent. Do not copy root rules33into it.3435Seed area boundaries, not every package. Replace a stub only when guidance36passes the same admission test as any other scoped instruction.3738## Audit procedure39401. Inventory the root and nested guidance tree. Read the affected guide, its41 parents, and its children fully; inspect their Git diff and relevant42 history. Use commit history to find likely drift, not as a requirement to43 summarize every intervening commit.442. Check concrete claims against their owning source, manifest, tests, or45 official dependency contract. Distinguish shipped behavior from plans.463. Identify content that is duplicated, readily discoverable, local to one47 area, task-specific, temporary, ideological, or phrased more absolutely48 than the underlying risk requires.494. Remove obsolete context. Move local guidance to a scoped guide and50 workflows to skills. Link to detailed references rather than compressing51 their contents into a parent guide. Leave intentional stubs free of local52 rules.535. Add new guidance only when a recurring or high-cost failure cannot be54 prevented more precisely by code, tests, schemas, or tooling. Place it at55 the narrowest stable scope.566. Read the result as one instruction set. Resolve overlap and conflicts, and57 prefer clear outcomes over prescribed agent process.5859## Editing principles6061- Prefer deletion and routing over denser prose. A soft size target can prompt62 review, but do not optimize for a hard line count.63- Hard language is appropriate for security, destructive operations, data64 isolation, provenance, authentication, and publish integrity. Elsewhere,65 preserve room for task context and engineering judgment.66- Specs, issues, PRs, mockups, tests, and other repositories can all be useful67 references. Do not present planned behavior as shipped, and prefer68 executable or source-backed evidence for current contracts.69- Avoid freshness dates that imply more verification than Git history proves.70- Keep `AGENTS.md` canonical and preserve the `CLAUDE.md` symlink.7172## Finish7374Check the changed guides, their links, inheritance, and scope boundaries.75Confirm that removing a detail did not remove a genuine high-risk gotcha,76that moved guidance is discoverable from its parent, and that stubs have not77accumulated generic rules. Then verify:7879```bash80test -L CLAUDE.md && test "$(readlink CLAUDE.md)" = "AGENTS.md"81git diff --check -- AGENTS.md '**/AGENTS.md' .agents/agents-md-sync/SKILL.md82```
signet-ai