"This skill should be used when the user says their AGENTS.md is outdated, stale, or needs refreshing, or when they say 'update AGENTS.md', 'refresh AGENTS.md', 'AGENTS.md is out of date', or 'sync AGENTS.md with project'. Provides a step-by-step process to update an existing AGENTS.md to reflect current project state."
Update an existing AGENTS.md file to reflect current project state. Default to keeping the file compact; ask about references folder only if content becomes too verbose.
Load the agents-md skill for format guidance:
Use Skill tool with skill="agd:agents-md"
Provides: sections, structure, validation checklist, best practices
Trigger updates when:
Read existing AGENTS.md:
cat AGENTS.md
Freshness check — determine what has changed since AGENTS.md was last updated:
# When was AGENTS.md last committed?
git log -1 --format="%ar" -- AGENTS.md
# What files changed since then? (guard against untracked/never-committed case)
AGENTS_COMMIT=$(git log -1 --format="%H" -- AGENTS.md)
[ -n "$AGENTS_COMMIT" ] && git diff --name-only "$AGENTS_COMMIT" HEAD || git status --short
$AGENTS_COMMIT will be empty and the command falls back to git status --short automaticallygit diff --name-only HEAD silently diffs the working tree instead — always use the guarded formplugins/, src/, packages/) → structure driftpackage.json, Makefile, or build configs → commands may be outdated.github/workflows/) → undocumented pipeline steps.eslintrc, vitest.config.ts) → style section staleAnalyze project for changes:
Identify update scope:
Update sections incrementally:
./docs/agents/testing.md, ../api/AGENTS.md)docs/agents/ or similar, check those files for stale content (outdated architecture trees, removed components, renamed paths) and update them in the same passCheck line count before writing:
If projected content exceeds 100 lines — ask and then act: Use AskUserQuestion:
questions: [
{
"question": "The AGENTS.md will exceed 100 lines. Would you like me to split detailed content into a references folder?",
"header": "References",
"options": [
{
"label": "No, keep it compact",
"description": "Try harder to condense. Keep AGENTS.md as a single file."
},
{
"label": "Yes, create docs/agents/",
"description": "Create docs/agents/ and move detailed sections there, leaving brief summaries with links in AGENTS.md."
},
{
"label": "Yes, use custom path",
"description": "Specify a custom path for the references folder."
}
]
}
]
If user chooses to split:
docs/agents/<section-name>.md (or user-specified path)See docs/agents/<section-name>.md for details.Write updated AGENTS.md:
Validate the updated file:
Report changes: Summarize what was updated:
Updated AGENTS.md:
- Added: New testing commands (vitest)
- Updated: Build process (now uses turbo)
- Removed: Obsolete npm scripts
- Line count: 65 (was 58)
After update, verify:
Show changes in unified diff format for clarity:
## Setup commands
- Install: `npm install`
+ Install: `pnpm install`
- Dev server: `npm run dev`
+ Dev server: `pnpm dev`