Adjust AGENTS.md - create or improve a project's instruction file
An AGENTS.md is read into every session and every custom subagent, so every line is paid for on every
message and earns its place only when removing it would make Claude get something wrong. Three homes,
never mixed:
- The template (
<stack>/stack/AGENTS.template.md, <stack> resolved in step 1) owns WHAT goes in - its authoring outline (the numbered
sections, Setup and Key files among them), the keep-out test and the five shapes to keep out (its
fill-in block), and where the file lives.
- This skill owns HOW - which mode, where the facts come from, what is shown before a write.
- The check (
scripts/agents-md-check.js) owns the verdict - every named path exists, every
command's program resolves, no placeholder, TODO or template text is left. It runs last, every time.
When to use
- A project's AGENTS.md written, filled in or brought up to date: the seeded
.claude/AGENTS.md still unfilled, an AGENTS.md gone stale against the code (a moved path, a changed build or test command, a missing setup step), an audit or improvement of the instruction file, a separate part of the repo (web/, api/, a package) that needs its own AGENTS.md, or what the AGENTS.md check reported.
- Covers setup, commands, key files and architecture sections, what to keep out, and the deterministic check that closes it.
- Not for a skill, a rule or a hook, nor a README, nor a preference or lesson, which Claude Code's own memory or the preferences docs keep.
1. Resolve the stack's files
A run that already holds the stack's snapshot (the /alfred-code:init run's $TMP/repo) uses that
folder's path as <stack>. Otherwise take the newest plugin-cache entry (normally the release these copies
came from; after a core update it can be newer) - the block prints its path, and every later command pastes that literal as <stack> (each Bash call is its
own shell, so a variable set here is gone by the next):
STACK=$(for d in "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/*/*/*; do # one glob: zsh aborts the loop when any named glob matches nothing
PN=${d%/*}; PN=${PN##*/}; [ "$PN" = alfred-code ] || continue
[ -f "$d/scripts/agents-md-check.js" ] && [ ! -e "$d/.orphaned_at" ] && printf '%s\t%s\n' "$(basename "$d")" "$d"
done 2>/dev/null | sort -V | tail -1 | cut -f2)
echo "stack: ${STACK:-absent}"
stack: absent (a copy-only install): the check cannot run - say so in the report, and take the
outline from the seeded instruction file when it still carries its comment blocks; with neither,
stop and name /alfred-code:update, which brings the stack's files back.
2. Pick the mode - the script says what is on disk
node "<stack>/scripts/agents-md-check.js" --root . --list
node "<stack>/scripts/update-preflight.js" --offers --root . | grep '^instructions-file:'
The second line names the file this install works with - instructions-file: agents is AGENTS.md, claude is
CLAUDE.md (the user's answer to the name ask of init, configure or update). Every file this skill writes takes that name, called
<name> below; never pick it yourself.
- Create - it printed
no AGENTS.md or CLAUDE.md in this project, or every file it lists is the seeded template (unfilled). The target is the seeded file; with none, write .claude/<name>
from <stack>/stack/AGENTS.template.md (the spot the installer seeds, loaded like a root one).
- Improve - any listed file holds the project's own text. Every listed file is in scope: the
root
AGENTS.md, .claude/AGENTS.md, each part's own, and a CLAUDE.md the project already keeps.
A root AGENTS.md is the project's own file, whoever wrote it: the installer seeds nothing beside
it, and it is improved in place with every change shown first, never overwritten or replaced by the
template. A project's own CLAUDE.md is improved as it stands and never renamed here (the name ask of configure or update renames) - say in
the report that Claude Code (2.1.277 or later) reads an AGENTS.md itself only while no CLAUDE.md or
CLAUDE.local.md sits beside or above it, so with both files the CLAUDE.md wins, and an
@ import of the AGENTS.md from it keeps both loading - it resolves from the importing file, so
@.claude/AGENTS.md from a root CLAUDE.md, @AGENTS.md from one beside it - or the user sets Project
instructions to 'claude-md-and-agents-md' in /config. Never the same facts written twice.
3. Gather the facts - read, never guessed
Every fact a section states comes from a file that states it, in this order:
- The first-look scan -
node "<stack>/scripts/scan-evidence.js" --orientation --root . prints the
stack, the modules, the build / test / run commands and the entry points, read from the manifests.
It is the map; do not re-derive it by reading source.
- The awareness docs when
capture-awareness has run: the docs hook pushes the architecture part's
orientation, and the awareness rule imports the project part's PROJECT-INFO-AWARENESS.md and
RUN-AND-DEBUG-AWARENESS.md into every session, so sections 1-4 and 6 point at them and keep only what
they lack (the template's outline names it); with the docs kept out of git they are written in full.
- Setup - the SDK pins (
global.json, .nvmrc, engines, <TargetFramework>), the compose
file or container package a test run needs, and the env var NAMES a test reads (appsettings.*.json,
the test fixtures, a CI workflow's env: block) - names only; a credential is read for presence,
never its value. Every .env* file, .env.example included, sits behind the install's secret-file
read deny: a probe of one is refused, and with it the whole batched call it rode in.
- Commands - the CI workflow's steps are the commands known to work; the manifests' scripts are
the rest. Beside the full-suite test command, the scoped one (one project, a filter, a spec path).
- Key files - the entry points the scan printed and the configs that decide behaviour, one line
each on what the file decides.
A separate part is a top-level folder with its own manifest whose stack or commands differ from the
root's (a web/package.json beside a .NET solution, an api/ with its own solution). It gets its own
<part>/<name> - Claude loads it when it reads a file there (an AGENTS.md only while no CLAUDE.md sits there or above) - carrying only that part's Setup,
Commands and Key files, which the root file then does not repeat (it points at the part's file); what
two parts share stays in the root file.
4. Create - fill the outline
- Write the sections the template's outline numbers, in its order, only where step 3 found a fact -
an empty section is not written. The H1 is the project's own name.
- Delete the template's two comment blocks once the sections are in. No rules list: every file in
.claude/rules/ loads itself.
- Write each part's
<part>/<name>.
The write needs no second ask when the user asked for it; a run the user did not ask for shows the
outline it would write, then asks through ONE AskUserQuestion:
Write <file> from the outline in this reply (<N> sections, facts from step 3)?
- 'Write it (Recommended)' - <file> is written with those sections, each fact from step 3
- 'Skip' - nothing is written
Either way the report names every file written with its line count.
5. Improve - show before writing, never rewrite the project's prose
Run the check first (step 7's command): its rows are the stale lines.
Read each listed file whole - they are small - and run the outline compare, which the script states:
node "<stack>/scripts/agents-md-check.js" --root . --outline
It prints each numbered outline section with the heading that holds it, or lacks. A lacks row
step 3 has a fact for is an addition (Setup and Key files most often); a matched heading is a guess,
so a section filed under another name is read before it is called missing, and the report says how
many sections lack and how many this run added. A stack-rules row is the rules list an older
template seeded - step 3 drafts its removal.
Draft three kinds of change, nothing else:
- a verified fix - a stale path whose new target this run confirmed on disk (a listing, a
read,
git log --follow), or the section a stack-rules row names: its lines that name the
stack's rules or repeat the template's rules text go, and the heading with them when nothing of
the project's own is left under it - fact, not heuristic;
- a fix per check row - only the flagged token changes: the path it moved to (the navigation
tools' symbol lookup,
LSP workspaceSymbol, or git log --follow --name-status -- <old path>), the command the
manifest or CI now runs. A path that is simply gone comes out of its line, the rule around it
kept - the whole line only when the path was all it said. A TODO or placeholder in the
project's own text is the user's to fill: named in the report, never invented;
- an addition - a section the template's outline numbers that the file lacks and step 3 found a
fact for, a missing line in an existing section, or a separate part's own
<part>/<name> where
it has none (step 3).
The project's own wording, order and sections are never reworded, reordered or deleted beyond that
(the stack's rules list is the stack's text, not the project's),
and a line the project wrote is never extended - an addition goes on a line of its own.
Show every change before writing: per file, a diff block and one line saying why it helps a
future session - in the reply, and again as the preview of each option that writes (the
AskUserQuestion option field, single-select only), so the ask cannot go out without its diffs. Then
ONE AskUserQuestion:
Apply these changes to <the files>? <N> additions and <N> verified fixes rest on facts read this run; <N> check fixes are heuristic - read each diff in this reply.
- 'Apply the additions and verified fixes (Recommended)' - every line backed by a fact or a target confirmed on disk
- 'Also apply the check fixes' - the heuristic rows too, each one read first
- 'Apply some' - I ask which changes next, in plain text; a check row named 'keep' gets the keep marker
- 'Skip' - nothing is written
An unverified check fix is never in the recommended option: the check is heuristic, and a row can
be correct text it could not resolve, so the user reads each one and picks. With only check fixes
drafted, the ask still runs - its keep option is the one route to the keep marker, so a row is never
ruled correct by the run itself - in this shape:
Apply the <N> check fixes to <the files>? Each is a heuristic row that can be correct text the check could not resolve - read each diff in this reply.
- 'Skip (Recommended)' - nothing is written; the rows come back on the next run
- 'Keep the lines as written for good' - each flagged line ends with the keep marker, and no later run raises it
- 'Apply the check fixes' - every diff in this reply is written
- 'Apply some' - I ask which changes next, in plain text; only those are written
A dispatched seat has no user channel: it returns the diffs in its report instead.
Before the write, git ls-files <file>: an untracked target (git-ignored, or never added) has no
diff to review and no history to restore - edit it with the harness's own edit tool (its history
rewinds) or copy it to the scratchpad first, never an in-place shell rewrite, and the report says
which. Then apply exactly the answer.
6. What never goes in
Hold every line to the template's keep-out test and its five shapes. On top of them, three things
this file is never the home of:
- A session's learnings, a correction or a personal preference - Claude Code's own memory keeps
them; an AGENTS.md line is neither. A
code, architecture or git preference is the user's to record with
/capture-preferences instead -
the template's wishlist shape.
- A
CLAUDE.local.md of personal notes - the same memory, for the same reason; it also makes Claude Code stop reading AGENTS.md, unless the user sets Project instructions to 'claude-md-and-agents-md' in /config.
- A score or a grade of the file - a judgment no check can hold it to; the check's rows are the
verdict.
7. Check last - the file matches the tree
node "<stack>/scripts/agents-md-check.js" --root .
- A row on a line this run wrote is this run's bug: fix it and run the check again.
- A row on a line the user kept (declined in step 5) stays, named in the report. When the user says
the line is right as written for good (step 5's keep option, or their own word), end it with
<!-- agents-md-check: keep --> - the check then raises no row on it, so the next run does not ask again.
- A
command row on a program only another OS runs (a PowerShell-only step on macOS) stays, named.
8. Report
The mode, each file written or changed (lines before and after), the check's last output line quoted,
and every row left with its reason. Nothing is committed - the user reviews the diff, or for an
untracked file the backup or the edit history step 5 named.
1---2name: habits-adjust-agents-md3description: "Use when asked to fill in or update AGENTS.md or CLAUDE.md, or one is written - an unfilled seed, a stale one, a part needing its own. Not for skills or rules."4metadata:5 source: https://skillmd.com/skills/envoydev/habits-adjust-agents-md6---78# Adjust AGENTS.md - create or improve a project's instruction file910An AGENTS.md is read into every session and every custom subagent, so every line is paid for on every11message and earns its place only when removing it would make Claude get something wrong. Three homes,12never mixed:1314- **The template** (`<stack>/stack/AGENTS.template.md`, `<stack>` resolved in step 1) owns WHAT goes in - its authoring outline (the numbered15 sections, Setup and Key files among them), the keep-out test and the five shapes to keep out (its16 fill-in block), and where the file lives.17- **This skill** owns HOW - which mode, where the facts come from, what is shown before a write.18- **The check** (`scripts/agents-md-check.js`) owns the verdict - every named path exists, every19 command's program resolves, no placeholder, TODO or template text is left. It runs last, every time.2021## When to use2223- A project's AGENTS.md written, filled in or brought up to date: the seeded `.claude/AGENTS.md` still unfilled, an AGENTS.md gone stale against the code (a moved path, a changed build or test command, a missing setup step), an audit or improvement of the instruction file, a separate part of the repo (web/, api/, a package) that needs its own AGENTS.md, or what the AGENTS.md check reported.24- Covers setup, commands, key files and architecture sections, what to keep out, and the deterministic check that closes it.25- Not for a skill, a rule or a hook, nor a README, nor a preference or lesson, which Claude Code's own memory or the preferences docs keep.2627## 1. Resolve the stack's files2829A run that already holds the stack's snapshot (the `/alfred-code:init` run's `$TMP/repo`) uses that30folder's path as `<stack>`. Otherwise take the newest plugin-cache entry (normally the release these copies31came from; after a core update it can be newer) - the block prints its path, and every later command pastes that literal as `<stack>` (each Bash call is its32own shell, so a variable set here is gone by the next):3334```bash35STACK=$(for d in "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/*/*/*; do # one glob: zsh aborts the loop when any named glob matches nothing36 PN=${d%/*}; PN=${PN##*/}; [ "$PN" = alfred-code ] || continue37 [ -f "$d/scripts/agents-md-check.js" ] && [ ! -e "$d/.orphaned_at" ] && printf '%s\t%s\n' "$(basename "$d")" "$d"38done 2>/dev/null | sort -V | tail -1 | cut -f2)39echo "stack: ${STACK:-absent}"40```4142`stack: absent` (a copy-only install): the check cannot run - say so in the report, and take the43outline from the seeded instruction file when it still carries its comment blocks; with neither,44stop and name `/alfred-code:update`, which brings the stack's files back.4546## 2. Pick the mode - the script says what is on disk4748```bash49node "<stack>/scripts/agents-md-check.js" --root . --list50node "<stack>/scripts/update-preflight.js" --offers --root . | grep '^instructions-file:'51```5253The second line names the file this install works with - `instructions-file: agents` is AGENTS.md, `claude` is54CLAUDE.md (the user's answer to the name ask of init, configure or update). Every file this skill writes takes that name, called55`<name>` below; never pick it yourself.5657- **Create** - it printed `no AGENTS.md or CLAUDE.md in this project`, or every file it lists is `the58 seeded template (unfilled)`. The target is the seeded file; with none, write `.claude/<name>`59 from `<stack>/stack/AGENTS.template.md` (the spot the installer seeds, loaded like a root one).60- **Improve** - any listed file holds the project's own text. Every listed file is in scope: the61 root `AGENTS.md`, `.claude/AGENTS.md`, each part's own, and a `CLAUDE.md` the project already keeps.6263A root `AGENTS.md` is the project's own file, whoever wrote it: the installer seeds nothing beside64it, and it is improved in place with every change shown first, never overwritten or replaced by the65template. A project's own `CLAUDE.md` is improved as it stands and never renamed here (the name ask of configure or update renames) - say in66the report that Claude Code (2.1.277 or later) reads an AGENTS.md itself only while no CLAUDE.md or67CLAUDE.local.md sits beside or above it, so with both files the CLAUDE.md wins, and an68`@` import of the AGENTS.md from it keeps both loading - it resolves from the importing file, so69`@.claude/AGENTS.md` from a root CLAUDE.md, `@AGENTS.md` from one beside it - or the user sets Project70instructions to 'claude-md-and-agents-md' in `/config`. Never the same facts written twice.7172## 3. Gather the facts - read, never guessed7374Every fact a section states comes from a file that states it, in this order:75761. **The first-look scan** - `node "<stack>/scripts/scan-evidence.js" --orientation --root .` prints the77 stack, the modules, the build / test / run commands and the entry points, read from the manifests.78 It is the map; do not re-derive it by reading source.792. **The awareness docs** when `capture-awareness` has run: the docs hook pushes the architecture part's80 orientation, and the awareness rule imports the project part's `PROJECT-INFO-AWARENESS.md` and81 `RUN-AND-DEBUG-AWARENESS.md` into every session, so sections 1-4 and 6 point at them and keep only what82 they lack (the template's outline names it); with the docs kept out of git they are written in full.833. **Setup** - the SDK pins (`global.json`, `.nvmrc`, `engines`, `<TargetFramework>`), the compose84 file or container package a test run needs, and the env var NAMES a test reads (`appsettings.*.json`,85 the test fixtures, a CI workflow's `env:` block) - names only; a credential is read for presence,86 never its value. Every `.env*` file, `.env.example` included, sits behind the install's secret-file87 read deny: a probe of one is refused, and with it the whole batched call it rode in.884. **Commands** - the CI workflow's steps are the commands known to work; the manifests' scripts are89 the rest. Beside the full-suite test command, the scoped one (one project, a filter, a spec path).905. **Key files** - the entry points the scan printed and the configs that decide behaviour, one line91 each on what the file decides.9293A separate part is a top-level folder with its own manifest whose stack or commands differ from the94root's (a `web/package.json` beside a .NET solution, an `api/` with its own solution). It gets its own95`<part>/<name>` - Claude loads it when it reads a file there (an AGENTS.md only while no CLAUDE.md sits there or above) - carrying only that part's Setup,96Commands and Key files, which the root file then does not repeat (it points at the part's file); what97two parts share stays in the root file.9899## 4. Create - fill the outline1001011. Write the sections the template's outline numbers, in its order, only where step 3 found a fact -102 an empty section is not written. The H1 is the project's own name.1032. Delete the template's two comment blocks once the sections are in. No rules list: every file in104 `.claude/rules/` loads itself.1053. Write each part's `<part>/<name>`.106107The write needs no second ask when the user asked for it; a run the user did not ask for shows the108outline it would write, then asks through ONE AskUserQuestion:109110```ask111Write <file> from the outline in this reply (<N> sections, facts from step 3)?112- 'Write it (Recommended)' - <file> is written with those sections, each fact from step 3113- 'Skip' - nothing is written114```115116Either way the report names every file written with its line count.117118## 5. Improve - show before writing, never rewrite the project's prose1191201. Run the check first (step 7's command): its rows are the stale lines.1212. Read each listed file whole - they are small - and run the outline compare, which the script states:122123 ```bash124 node "<stack>/scripts/agents-md-check.js" --root . --outline125 ```126127 It prints each numbered outline section with the heading that holds it, or `lacks`. A `lacks` row128 step 3 has a fact for is an addition (Setup and Key files most often); a matched heading is a guess,129 so a section filed under another name is read before it is called missing, and the report says how130 many sections lack and how many this run added. A `stack-rules` row is the rules list an older131 template seeded - step 3 drafts its removal.1323. Draft three kinds of change, nothing else:133 - **a verified fix** - a stale path whose new target this run confirmed on disk (a listing, a134 read, `git log --follow`), or the section a `stack-rules` row names: its lines that name the135 stack's rules or repeat the template's rules text go, and the heading with them when nothing of136 the project's own is left under it - fact, not heuristic;137 - **a fix per check row** - only the flagged token changes: the path it moved to (the navigation138 tools' symbol lookup, `LSP` `workspaceSymbol`, or `git log --follow --name-status -- <old path>`), the command the139 manifest or CI now runs. A path that is simply gone comes out of its line, the rule around it140 kept - the whole line only when the path was all it said. A TODO or placeholder in the141 project's own text is the user's to fill: named in the report, never invented;142 - **an addition** - a section the template's outline numbers that the file lacks and step 3 found a143 fact for, a missing line in an existing section, or a separate part's own `<part>/<name>` where144 it has none (step 3).145146 The project's own wording, order and sections are never reworded, reordered or deleted beyond that147 (the stack's rules list is the stack's text, not the project's),148 and a line the project wrote is never extended - an addition goes on a line of its own.1494. Show every change before writing: per file, a `diff` block and one line saying why it helps a150 future session - in the reply, and again as the `preview` of each option that writes (the151 AskUserQuestion option field, single-select only), so the ask cannot go out without its diffs. Then152 ONE AskUserQuestion:153154 ```ask155 Apply these changes to <the files>? <N> additions and <N> verified fixes rest on facts read this run; <N> check fixes are heuristic - read each diff in this reply.156 - 'Apply the additions and verified fixes (Recommended)' - every line backed by a fact or a target confirmed on disk157 - 'Also apply the check fixes' - the heuristic rows too, each one read first158 - 'Apply some' - I ask which changes next, in plain text; a check row named 'keep' gets the keep marker159 - 'Skip' - nothing is written160 ```161162 An unverified check fix is never in the recommended option: the check is heuristic, and a row can163 be correct text it could not resolve, so the user reads each one and picks. With only check fixes164 drafted, the ask still runs - its keep option is the one route to the keep marker, so a row is never165 ruled correct by the run itself - in this shape:166167 ```ask168 Apply the <N> check fixes to <the files>? Each is a heuristic row that can be correct text the check could not resolve - read each diff in this reply.169 - 'Skip (Recommended)' - nothing is written; the rows come back on the next run170 - 'Keep the lines as written for good' - each flagged line ends with the keep marker, and no later run raises it171 - 'Apply the check fixes' - every diff in this reply is written172 - 'Apply some' - I ask which changes next, in plain text; only those are written173 ```174175 A dispatched seat has no user channel: it returns the diffs in its report instead.1765. Before the write, `git ls-files <file>`: an untracked target (git-ignored, or never added) has no177 diff to review and no history to restore - edit it with the harness's own edit tool (its history178 rewinds) or copy it to the scratchpad first, never an in-place shell rewrite, and the report says179 which. Then apply exactly the answer.180181## 6. What never goes in182183Hold every line to the template's keep-out test and its five shapes. On top of them, three things184this file is never the home of:185186- **A session's learnings, a correction or a personal preference** - Claude Code's own memory keeps187 them; an AGENTS.md line is neither. A188 code, architecture or git preference is the user's to record with `/capture-preferences` instead -189 the template's wishlist shape.190- **A `CLAUDE.local.md` of personal notes** - the same memory, for the same reason; it also makes Claude Code stop reading AGENTS.md, unless the user sets Project instructions to 'claude-md-and-agents-md' in `/config`.191- **A score or a grade** of the file - a judgment no check can hold it to; the check's rows are the192 verdict.193194## 7. Check last - the file matches the tree195196```bash197node "<stack>/scripts/agents-md-check.js" --root .198```199200- A row on a line this run wrote is this run's bug: fix it and run the check again.201- A row on a line the user kept (declined in step 5) stays, named in the report. When the user says202 the line is right as written for good (step 5's keep option, or their own word), end it with203 `<!-- agents-md-check: keep -->` - the check then raises no row on it, so the next run does not ask again.204- A `command` row on a program only another OS runs (a PowerShell-only step on macOS) stays, named.205206## 8. Report207208The mode, each file written or changed (lines before and after), the check's last output line quoted,209and every row left with its reason. Nothing is committed - the user reviews the diff, or for an210untracked file the backup or the edit history step 5 named.