# Habits Adjust Agents Md

> 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.

- Skill: `envoydev/habits-adjust-agents-md` (Agent Skill)
- Install (CLI): `npx get-skill add envoydev/habits-adjust-agents-md`
- Raw SKILL.md: https://api.skillmd.com/api/skills/envoydev/habits-adjust-agents-md/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: envoydev (https://skillmd.com/u/envoydev)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/envoydev/habits-adjust-agents-md

---


# 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):

```bash
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

```bash
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:

1. **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.
2. **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.
3. **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.
4. **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).
5. **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

1. 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.
2. Delete the template's two comment blocks once the sections are in. No rules list: every file in
   `.claude/rules/` loads itself.
3. 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:

```ask
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

1. Run the check first (step 7's command): its rows are the stale lines.
2. Read each listed file whole - they are small - and run the outline compare, which the script states:

   ```bash
   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.
3. 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.
4. 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:

   ```ask
   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:

   ```ask
   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.
5. 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

```bash
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.

