new-agents-md

The cross-tool projection organ. Closes the gap that the entire instruction surface here is Claude-Code-exclusive: CLAUDE.md, the @claude-md/... imports, the ~/.claude/architectural-rules/ loader, the typed-memory warning/feedback corpus, and every skill are invisible to any other coding agent. The moment a non-Claude agent (Codex, Cursor, Aider, Continue, Zed) is pointed at a repo, it starts blind and guesses exactly what the corpus already pins — test commands, package manager, the "never commit AI attribution" landmine, the architectural defaults.

This skill projects the lean corpus into a vendor-neutral, repo-root AGENTS.md (plus a global one) that those agents read on session start. It is a distill-then-interview organ: it reads the corpus and proposes a draft before asking anything, then interviews only for what no corpus read can supply.

When to run

• User types /new-agents-md (explicit trigger).
• User says "generate an AGENTS.md," "make this repo readable by Codex/Cursor/Aider," "scaffold cross-tool instructions," "I want a vendor-neutral agents file."
• Do not auto-fire. No session-start or event-hook triggers. Mode A only — every run goes through the full distill + interview. (Trigger lives in the frontmatter description per universal/skill-auto-fire.md; there is no SessionStart hook.)

Why this skill exists

The cross-tool convention is AGENTS.md — a vendor-neutral, repo-root instruction file. The naive fix from the convention's write-ups is "make AGENTS.md canonical and reduce CLAUDE.md to a thin @AGENTS.md stub." That stub-inversion is rejected here. The value of this environment lives in machinery a generic agent cannot execute — on-demand rule loading, discovery/prep organs, typed memory, skills. A generic reader can run none of it, so AGENTS.md cannot @import the essentials; it must carry a flattened, behaviour-only projection of the corpus.

Hand-maintaining that projection beside the live corpus would reintroduce the duplication that single-source-of-truth exists to avoid — a stale hand-copied AGENTS.md is worse than none. So AGENTS.md is treated as a derived artefact (like a codemap: regenerate on demand), not a hand-maintained twin (like memory: authored, versioned). This skill is the generator.

CLAUDE.md + the organ machinery stay canonical for Claude Code. AGENTS.md is a downstream projection for everyone else.

Inputs

1. Triggering message. Anything after /new-agents-md is hint text (e.g. a path, or "global only") — used to bias the run, never to skip a pass.
2. The corpus (read in Pass 1, never written): the CLAUDE.md tree (global ~/.claude/CLAUDE.md + project <repo>/CLAUDE.md + their @-imports), the architectural-rules tree in resolved form, the warning/ + feedback/ memory entries, and the canonical-commands file if it exists.
3. The repo (scanned in Pass 1 for language/domain detection; read in Pass 2 for architecture orientation): file extensions, directory layout, an existing .claude/codemap.md if present.
4. Config. The global-AGENTS.md destination path is read from machine-local config (~/.claude/hook-config.json), never hardcoded — see "Write & pointer" and universal/no-hardcoded-machine-paths.md.

Procedure

Pass 1 — Distill (read the corpus, propose a draft)

This pass runs before any interview prompt. It produces a non-empty draft AGENTS.md (and a draft global AGENTS.md) held in-conversation. Read order:

1. CLAUDE.md tree. Read global ~/.claude/CLAUDE.md, the project <repo>/CLAUDE.md, and every file they @-import. Inline the import targets as flat imperative prose — the generic reader cannot follow @claude-md/..., so the content goes in, not the reference. These become the Core-principles / conventions section.

2. Architectural rules — resolved form. Load rules via skills/discover/SKILL.md, so the tier overlay is already applied: user/company/project overrides + patches in, disables dropped, <!-- id: --> anchors stripped. Never read the raw shipped tree — a rule the user disabled or patched must project in its effective form, not its shipped form. Invoke discover programmatically (same call shape prep/review use):

   {
     task_keywords: [<derived from repo: languages, top-level dirs>],
     scopes: [<detected language>, <detected domain>, "global", "project-<name>"],
     kind: "architectural-rule",
     relevance_phases: ["always"],
     top_n: 20,
     render_bodies: true,
     include_recaps: false
   }

Use the section layout in template.md. What are the exact commands for: test / lint / typecheck / build / run? Which package manager (and any "use X not Y" rule)? What's the required post-edit check order?

If the canonical-commands seed (Pass 1 step 4) pre-filled any of these, **confirm-or-edit**
rather than asking cold: "Pinned command for tests is `<X>` — correct for this repo? (y/edit)".

2. **Repo-specific "Never X".** The reactive-rule pattern — landmines born from *this repo's*
mistakes that aren't yet typed memories.

What are 3–5 repo-specific "never do this" rules, each with the symptom if it slips through? (These join the corpus warning/feedback landmines at the top of the file.) Blank line to finish.

**Collect these — do not capture yet.** They are batched at the end (see Capture batch).
Soft-reject entries with no symptom clause (the symptom is what makes it real).

3. **Architecture orientation.** Where things live, not why.

One paragraph: what is this project? Then a directory-purpose map and any path-alias / import conventions.

**Seed from codemap when present:** if `.claude/codemap.md` exists, propose its structure tree
as the directory map and ask confirm-or-edit. If absent, **degrade gracefully** to a cold ask —
never fail because there's no codemap.

4. **Non-code infra hints.** The class of knowledge the corpus has none of.

Any infra/workflow hints a fresh agent needs? (e.g. "API server runs in tmux window 3", "dev server live-reloads — don't restart it", "when I say 'commit' use the X skill") Blank line to skip.

### Size check (advisory, never blocking)

After distill + interview, estimate the projection size. The guidance threshold is **~3k tokens**
— a *soft budget*, not a hard cap. If the projection crosses it (typically a polyglot +
multi-domain repo with several language and domain tiers inlined):

This projection is ~<N>k tokens across <M> language tier(s) and <K> domain tier(s). That's heavier than the lean target (~3k). Options: (t)rim — keep only the primary language/domain tiers, drop the rest (I'll list what's dropped) (k)eep — keep the full projection Choice?

The user decides. **Never silently truncate** a language or domain tier — overflow is always
surfaced. Below the threshold, no prompt fires. (Same advisory posture as the rest of the corpus:
surface, user decides, no enforcement.)

### Capture batch (one propose-confirm at the end)

The repo landmines collected in Pass 2 step 2 are durable corpus material, not just projection
content. Offer the **whole set at once** (not one prompt per landmine):

You named <N> repo-specific landmines. These can also become durable warning-kind memories via /capture (so future Claude sessions get them, not just other tools reading AGENTS.md):

1. <landmine 1>
2. <landmine 2> ...

Capture which? (a)ll / (s)ubset — list numbers / (n)one

On `all` / a subset → invoke `skills/capture/SKILL.md` with the chosen landmines as candidate
`warning`-kind content; capture's own confirm flow runs. On `none` → skip. **Either way the
landmines are still written to `AGENTS.md`** — capture is the durable-corpus add-on, independent
of the AGENTS.md write. This is the loop that keeps `AGENTS.md` a *projection of* the corpus, not
a second source drifting beside it.

### Compose

Assemble each `AGENTS.md` in this order (lead-with-prohibitions):

```markdown
# AGENTS.md

<one-paragraph: what this project is>

## Never do this
<the warning/feedback landmines + Pass-2 repo landmines, each: rule — symptom/why>

## Commands
<exact dev commands: test / lint / typecheck / build / run, package manager, post-edit order>

## Architecture
<one-paragraph orientation + directory-purpose map + path-alias / import conventions>

## Conventions
<flattened always-tier + detected-language (+ confirmed-domain) rules, as imperative prose>

## Domain Language
<present ONLY when a project-tier glossary (`.claude/rules/glossary.md`) exists:
project the ubiquitous-language terms — term → one-line definition — so a non-Claude agent
shares the domain's vocabulary. Omit the whole section when there is no glossary. Project the
terms + definitions; drop the per-term code-symbol map (an AGENTS.md reader wants the meaning,
not the Claude-internal symbol link).>

## Working discipline
<fixed cross-tool behavioral patterns — see below. Project verbatim; these are vendor-neutral
and apply to any agent reading this file. Not interviewed, not corpus-derived.>

## Infrastructure
<non-code infra hints, if any>

The Working discipline section is a fixed block — it projects durable, vendor-neutral prompting patterns into a form a generic agent can act on. Insert verbatim:

- Run one tool/command at a time and read its actual result before the next. Do not chain
  actions on an assumed outcome — a wrong assumption compounds across chained steps faster
  than it surfaces.
- Attempt-vs-ask by ambiguity depth: if the request has one dominant reading, make a good-faith
  attempt and state the assumption you made; if there are two or more reasonable readings, or
  you'd be inventing requirements, ask before acting.
- Separate gathering information from changing things. For non-trivial work, plan first and get
  the plan confirmed before mutating files.
- Comments and docs state the non-obvious why, in one sentence — if a comment restates the code,
  delete it. Commit messages are the same: signal only, no restating the diff.

This is the only fixed-content section. Everything else in the file is corpus-projected or interviewed; this block is constant because the patterns are tool-agnostic by construction.

Output contract — verifiable, this is the DC1 gate:

• No @-imports anywhere (import targets are inlined).
• No organ / skill references (/prep, /discover, "the capture organ", etc.) — the generic reader can't run them. Translate any rule that mentions an organ into the plain behaviour it encodes.
• Everything is flat imperative prose a stateless agent can act on in one read.
• The "Never do this" block is first.
• The "Working discipline" block is present and verbatim (the fixed cross-tool patterns) — it is the one section that does not vary by repo.

Preview & write

Show each composed file as a preview:

About to write:
  <repo>/AGENTS.md            (~<N> lines)
  <global-agents-path>/AGENTS.md   (~<M> lines)   ← if generating the global file

Preview (project AGENTS.md):
<full content>

Preview (global AGENTS.md):
<full content>

Proceed? (y/N — or name a section to revise)

On a section name → revise that section, re-preview. On n → ask which section. On y → write.

Write & pointer

1. Project AGENTS.md → <repo>/AGENTS.md.

2. Global AGENTS.md → the path read from ~/.claude/hook-config.json (key agentsMdGlobalPath). If the key is absent, do not guess a location — surface:

   No global AGENTS.md path configured. To generate the global file, set "agentsMdGlobalPath"
   in ~/.claude/hook-config.json (e.g. the directory your other agents read for global
   instructions). Skipping the global file for now; project AGENTS.md was written.

   Never hardcode a drive letter, username, or ~/.config literal in this skill body (universal/no-hardcoded-machine-paths.md).

3. Pointer line → add ONE line to the project <repo>/CLAUDE.md (a signpost, not an @import stub):

   > Vendor-neutral instructions for other coding agents live in AGENTS.md (generated via /new-agents-md).

   If CLAUDE.md already has the pointer, leave it. If there's no project CLAUDE.md, skip the pointer (nothing to point from).

Report

✓ AGENTS.md generated.
  Project:  <repo>/AGENTS.md
  Global:   <global-path>/AGENTS.md   (or "skipped — agentsMdGlobalPath not configured")
  Pointer:  <repo>/CLAUDE.md updated   (or "skipped — no project CLAUDE.md")
  Captured: <N> landmines → warning-kind memories   (or "none")

AGENTS.md is a derived projection — re-run /new-agents-md to refresh it when the corpus evolves.

Stop. Do not commit. Do not invoke /review. The files go into the next user-confirmed commit.

More in reference.md: What this skill does NOT do, relationship to other organs, anchors — house style.