Add Agents Md Style

---
name: add--agents-md-style
description: Use when generating or updating the project's AGENTS.md — migrates any legacy context file into it first, then defines what belongs vs. what stays in skills/docs, format rules (JSON for data, markdown for rules/instructions), and line budget. Load before any AGENTS.md write.
---

# AGENTS.md Style Guide

<!-- uses:
- skill: add--architecture-discovery
- skill: add--token-efficiency
- script: migrate-context-files.cjs
- mention: add--doc-schemas
- mention: add--skill-creator
- command: /add-wiki
-->

Defines content rules for the AGENTS.md file generated by ADD commands (primarily `add-wiki` STEP add-wiki.agents-md), and the migration every writer runs before touching it. **AGENTS.md is the only context file the framework writes or reads** — Claude Code (v2.1.277+), Codex, Cursor, OpenCode and Antigravity all read it natively. Source: Anthropic official docs (code.claude.com/docs/en/memory).

## When to Use

- Before any write to the project's AGENTS.md — `add-wiki` STEP add-wiki.agents-md, `add--architecture-discovery`.
- When a project still carries a CLAUDE.md, `.claude/CLAUDE.md` or GEMINI.md at its root.

## When NOT to Use

This skill is **only** for the project's AGENTS.md. Do not load when:

- Writing or updating any other doc (about.md, plan.md, README.md, hotfix docs) — use `add--doc-schemas` instead
- Authoring or editing skill files (`SKILL.md`) — use `add--skill-creator` and `add--token-efficiency`
- Updating repository README, web docs, or marketing copy — use `add-saas-copy` or general docs guidance

## Migration — Run It Before Any Write

**A legacy context file hides AGENTS.md.** Claude Code reads AGENTS.md only when no CLAUDE.md,
`.claude/CLAUDE.md` or `CLAUDE.local.md` exists in the working directory or above, and Antigravity
lets GEMINI.md override it. Writing AGENTS.md while one of them survives produces a file nobody reads.

```
IF ABOUT TO WRITE AGENTS.md:
  ⛔ DO NOT USE: Write or Edit on AGENTS.md before the migration below has run
  ⛔ DO NOT USE: Write or Edit on CLAUDE.md or GEMINI.md — they are migrated, never updated
  ✅ DO: Run node .codeadd/scripts/migrate-context-files.cjs at the project root, then write
```

`migrate-context-files.cjs` owns the mechanics and documents them in its header. What the writer does with its output:

| Line | Report to the user |
|---|---|
| `MIGRATED:<file>:created` | The file became AGENTS.md and was deleted |
| `MIGRATED:<file>:duplicate` | AGENTS.md already held its content; it was deleted |
| `MIGRATED:<file>:appended` | Its content was appended under `## Migrated from <file>` and it was deleted — the user tidies that section |
| `LEGACY_LOCAL:CLAUDE.local.md` | The file is personal and was left alone — while it exists, Claude Code ignores AGENTS.md |
| `CONTEXT_MIGRATION:none` | Nothing — there was nothing to migrate |

**Every line reaches the command's final report.** A deleted file the user did not hear about is a
file they go looking for.

## Why It Matters

AGENTS.md is injected into every session as a **user message** (not system prompt). Oversized files:
- Consume context tokens on every request, leaving less room for actual work
- Reduce adherence — more content means less attention per rule
- Duplicate content already available in the JIT-loaded project wiki

**Official target:** under 200 lines per context file.

## What Belongs in AGENTS.md

Facts the AI needs in **every session**, not available elsewhere:

- Architecture hierarchy and dependency rules
- Build/run/test commands
- Critical naming conventions (<10 items)
- Multi-tenancy critical rule (if applicable)
- App entry points
- Reference pointer to where detailed patterns live (JIT loading)

## Format Rules

**Target:** 80-150 lines total. The two managed blocks - Project Knowledge Base (17 lines) and Writing Style (13 lines) - are 31 lines together and are accounted for within this budget, leaving 49-119 lines for everything else. The Runtime policy managed block adds 5 more.

### JSON = DATA. Markdown = INSTRUCTIONS.

This is the fundamental rule. JSON minified is for **structured data that the agent looks up** (configs, mappings, paths, tech stack). Rules, instructions, orientation, and behavioral guidance use **markdown** (lists, tables, prose).

**Minified JSON — when:**
- Tech stack specs (framework, version, engine)
- Path mappings (package → path)
- Config values (env vars, ports, flags)
- Data lists (entity names, module names, enum names)

**Markdown (lists, tables, prose) — when:**
- Dependency rules ("domain never imports outer")
- Behavioral instructions ("always use X before Y")
- Architecture hierarchy and layer rules
- Naming conventions
- Build/run/test commands
- Any orientation or guidance

### Canonical Example

```markdown
# ❌ WRONG — rule as JSON
{"hierarchy":"domain → backend → workers → apps","rule":"inner never imports outer"}

# ✅ RIGHT — rule as markdown, data as JSON
### Layers
domain → backend/database → workers → apps. Inner never imports outer.

### Packages
{"domain":"@rd/domain","backend":"@rd/backend","database":"@rd/database","workers":"@rd/workers"}
```

Same principle applies to import rules and placement maps: render them as **tables** (behavioral guidance), not JSON objects.

## Section Templates

### Architecture Contract

Rules and constraints the agent must follow. Uses **markdown** (tables, lists, prose).

```markdown
## Architecture Contract

> Dependency hierarchy. Check BEFORE implementing or reviewing.

### Layers
domain → backend/database → workers → apps. Inner never imports outer.

### Import Rules
| Package | Can import |
|---|---|
| domain | nothing |
| backend, database | domain |
| workers | domain, database |
| api | all libs |
| frontend | domain |

### Placement
| What | Where |
|---|---|
| Entities | libs/domain/src/entities |
| Services | libs/backend/src/services |
| Repositories | libs/app-database/src/repositories |
| NestModules | apps/backend/src/api/modules |
```

### Technical Spec

Data the agent looks up. Uses **minified JSON** (one object per line).

```markdown
## Technical Spec
{"pkg":"npm","build":"turbo","lang":"typescript"}
{"backend":{"framework":"NestJS","version":"10","entry":"apps/backend/src/api/main.ts"}}
{"database":{"engine":"PostgreSQL","orm":"Kysely"}}
```

**Do NOT include:** full entity lists, all enum names, all type names, all API routes, all guard names, worker handler names.

### Validation Gates

Auto-derived data block emitted by `add--architecture-discovery`. Maps the 5 universal gate intents (lint, typecheck, test, build, format) to the actual command this project uses. Consumed by `add-plan`, `add-build`, `add-review` to inject and enforce checklist items in `tasks.md`.

Uses **minified JSON** (it's data, not behavior). Only includes gates that actually exist — absence is meaningful. The `format` gate, when present, MUST be a non-mutating check command.

```markdown
## Validation Gates
{"validation_gates":{"lint":"npm run lint","typecheck":"npm run typecheck","test":"npm test","build":"npm run build","format":"npm run format:check"}}
```

Language-agnostic — the keys are intents, the values are the real commands for whatever ecosystem this project uses (Node, Python, .NET, Go, Rust, Ruby, Elixir, Java, etc.). If no gates are detected, omit the section entirely. Do not emit `{"validation_gates":{}}`.

### Project Knowledge Base (managed block)

Written and owned by `/add-wiki` STEP add-wiki.agents-md — not authored by hand. Delimited by
link-reference-definition markers, **deliberately NOT HTML comments**: the build
pipeline strips HTML comments (`<!-- -->`) from command sources uniformly (the same
mechanism that powers feature/plugin injection anchors), so a template using
`<!-- codeadd-wiki:start -->` inside a command source would be destroyed at build
time. `[//]: # (...)` is a link-reference-definition — invisible when rendered,
untouched by the build strip, and trivially matched for replace-or-append at
runtime.

```markdown
[//]: # (codeadd-wiki:start)

## Project Knowledge Base

`.codeadd/wiki/` holds this project's patterns, conventions, workflows, and architecture
rationale. Entrypoint: `.codeadd/wiki/index.md`.

- CONSULT BEFORE exploring source for: project conventions, established patterns,
  workflow/how-to questions, architecture rationale ("why is it built this way").
- Do NOT consult for live structural facts (callers, impact, dependencies) — derive those
  from the code graph or the code itself.
- Pages carry `commit` + `sources` frontmatter. If sources changed since (see index.md
  staleness check), verify against code before relying on the page.
- Do not hand-edit generated pages; run /add-wiki update instead. INSTRUCTIONS.md is
  user-owned and steers regeneration.

[//]: # (codeadd-wiki:end)
```

**Replace-or-append semantics:** if the markers are found, the block between them is
replaced in place; if absent, the block is appended (with a separating blank line).
This is `/add-wiki`'s responsibility, not a manual edit.

**Legacy cleanup:** a context file carrying the old, unmarked "Implementation Patterns"
section (pointing at `project-patterns/` and `pattern-search.sh`) predates this
mechanism and carries no markers, so replace-or-append cannot remove it automatically.
Any updater agent regenerating this file MUST detect and DELETE a legacy
"Implementation Patterns" section (or any section referencing `project-patterns` or
`pattern-search.sh`) before writing the managed block.

### Writing Style (managed block)

Written and owned by `{{cmd:add-wiki}}` STEP add-wiki.agents-md, alongside the Project Knowledge Base
block and under the same rules: `[//]: # (...)` markers rather than HTML comments,
replace-or-append semantics, copied verbatim and never paraphrased.

It is the compressed form of the figurative-language rule in
`{{skill:add--doc-schemas/SKILL.md}}` → Universal Rules → Voice. That skill is the
authority; this block exists because it is loaded on demand and `AGENTS.md` is in
context every session, which is what a rule binding chat, docs, commits and code
comments needs.

```markdown
[//]: # (codeadd-style:start)

## Writing Style

Describe the action, the mechanism or the state directly. Never put a figure of speech in its place.

- Applies to chat, docs, commit messages, PR descriptions, code comments and identifiers.
- Applies to the writing, not to the language of this rule — it holds in every output language.
- Established technical terms of figurative origin (branch, tree, cache, pipeline, parent, orphan) are the literal names of their concepts. Keep them.
- Test each sentence: does it name the action, or name something the action resembles? Replace a resemblance with the action.
- Not a list of banned words. One example of the device: "confirm the tests bite" → "run the tests and check they fail against the broken code".

[//]: # (codeadd-style:end)
```

**Hard cap: 14 lines, both markers included.** This is a fixed verbatim block, not
generated prose, so the cap is a budget line rather than the numeric advisory the
output-length doctrine bans. The bullets run long on purpose: wrapping them at the
usual width would double the line count against no reduction in tokens.

**The block carries no framework artefact name, no `{{...}}` variable and no HTML
comment.** A variable would resolve per provider and land a wrong path in the user's
file; an artefact name would fail the build's prose relationship gate; an HTML comment
would be stripped at build.

### Runtime Policy (managed block)

Written and owned by `{{cmd:add-wiki}}` STEP add-wiki.agents-md, under the same rules as the two
blocks above: `[//]: # (codeadd-shell:start)` / `[//]: # (codeadd-shell:end)` markers,
replace-or-append, copied verbatim. Its text lives in that STEP. The policy is the same on every
platform — the shipped entries are native Node CommonJS and need Node (>=22.19.0), not Bash, WSL
or Git Bash — so a legacy Git Bash "Shell policy" block carrying these markers is replaced by it.

It used to be appended to a copy that was rewritten from scratch on every run, which kept one copy.
AGENTS.md is now written in place, so without markers it would stack one copy per run.

## Validation Checklist

Before finalizing any generated AGENTS.md:

- [ ] Total lines ≤ 150?
- [ ] JSON used ONLY for data; rules/instructions/orientation in markdown (no behavioral guidance inside JSON)?
- [ ] Architecture hierarchy in markdown; import/placement rules as tables (not JSON)?
- [ ] Technical Spec uses compact JSON, one object per line?
- [ ] Validation Gates block present using minified JSON when gates detected; section omitted entirely when none (no empty `{}`); `format` only when non-mutating?
- [ ] Project Knowledge Base managed block present (`[//]: # (codeadd-wiki:start)` … `[//]: # (codeadd-wiki:end)`), and no legacy unmarked "Implementation Patterns" section remains?
- [ ] Writing Style managed block present (`[//]: # (codeadd-style:start)` … `[//]: # (codeadd-style:end)`), 14 lines or fewer, carrying no `{{...}}` variable and no framework artefact name?
- [ ] Runtime Policy managed block present exactly once (`[//]: # (codeadd-shell:start)` … `[//]: # (codeadd-shell:end)`)?
- [ ] No CLAUDE.md, `.claude/CLAUDE.md` or GEMINI.md left at the project root after the Migration?
- [ ] No section explaining a single concept in >5 lines?
- [ ] No anti-patterns: full frontend/backend/database patterns, API route lists, component/directory trees, inline code examples, feature/business-flow docs, security implementation details, domain type/struct docs, worker/job-queue details, version-specific dependency lists?

## Cross-references

- `{{skill:add--token-efficiency/SKILL.md}}` — generic compression rules (JSON=data, markdown=instructions)
- `{{skill:add--doc-schemas/SKILL.md}}` — doc generation standards (separate pipeline, not for AGENTS.md)