| name | qi-layer |
| description | Use when writing or maintaining AGENTS.md, .context/CONTEXT.md, or CLAUDE.md mirrors: keep intent docs minimal and load-bearing. |
qi-layer
/qi-maintenance owns when colocated knowledge must move with source changes.
This skill owns how to write and structure that knowledge.
Load /knowledge-layers for where each layer lives and what it holds.
Load /llm-writing if it isn't already loaded.
This skill is about how to write and maintain the directory-local pair:
AGENTS.md and .context/CONTEXT.md. The pair governs any tree agents work
in — code, the KB, docs, work directories. AGENTS.md loads into an agent's
bounded context as standing instructions: write it like a prompt, minimal,
every line load-bearing.
The Four Principles
- Fractal Compression: leaf AGENTS.md summarizes its directory's
content; parent AGENTS.md summarizes its children. Each level is a
compression of the level below.
- Hierarchical Summarization: root provides broad architectural
frame. Leaves provide local working knowledge. Agents accumulate
understanding as they descend.
- LCA Deduplication: shared knowledge appears once at the shallowest
node covering all relevant paths. Never duplicate between siblings.
- Progressive Disclosure: give just enough to work correctly at this
level. Link to
.context/CONTEXT.md for depth.
Writing AGENTS.md
Agents read AGENTS.md before opening anything else in the tree — write for
that moment. Ask: what must someone understand before working here?
That's what AGENTS.md captures.
Keep AGENTS.md as short as the directory allows, rarely past 200 lines.
Include only what has substance:
- Purpose: what this area IS and what it ISN'T (1–3 sentences)
- Mental model: how to think about this area, key abstractions
- Key rules: constraints, what breaks if you get it wrong
- Anti-patterns: what NOT to do here
- Downlinks: to
.context/ for depth, to related areas
An agent that only reads AGENTS.md should be able to work correctly here.
An agent that also reads .context/ should be able to change things safely.
Writing .context/CONTEXT.md
Reference depth, co-located with the code it describes. Where an agent
goes when it needs contracts, architecture, or rationale in detail.
Sections (use only those with substance):
- Contracts: interfaces, invariants, what breaks if violated
- Architecture: component relationships, data flow, dependency direction
- Rationale: why X over Y, rejected alternatives
- Patterns: how to work here, concrete pitfalls
The .context/ directory is extensible: additional files alongside
CONTEXT.md for specialized concerns.
What Does NOT Belong in AGENTS.md
Apply the every-session test: root AGENTS.md loads on every session.
If knowledge is only relevant when working in a specific domain, it belongs
in that domain's AGENTS.md or .context/, not root.
Apply the think-vs-lookup test: text whose removal would cause a
wrong decision belongs in AGENTS.md. Text an agent would merely have to
look up belongs in .context/. Text that changes no behavior gets
deleted — agents already know how to code and follow common conventions.
Specific failure modes:
- Session bleed: LLM working notes that calcified into the instruction
file. Tells: status-update language ("deleted", "shipped", "deferred"),
implementation terms packed without framing, history narration.
- Reference material posing as intent: tables, command blocks, full
scheme vocabularies, implementation specifics.
- Redundant guards: prose warnings for invariants already enforced by
tests or types. The code is the real guard; prose rots faster.
- Duplicated knowledge: restating what lives in a skill, a domain
.context/, or a KB page. Point, don't duplicate.
- Domain-specific detail at root: URI scheme tables, gateway pricing
internals, auth implementation details. These belong in their domain's
AGENTS.md, not root.
Structural Rules
- Relative paths for all links
- AGENTS.md and .context/ at the same directory level (siblings)
- Link to files, not headings (headings change more often)
- Lateral links between
.context/ directories with contracts between them
- LCA deduplication: if two siblings share context, put it in the parent
CLAUDE.md Mirrors
Claude harnesses read CLAUDE.md, not AGENTS.md. Give every AGENTS.md a
sibling CLAUDE.md whose first line is @AGENTS.md — normally the whole
file. Run meridian qi claude-md-fix <target-root> on the containing tree
after creating or moving AGENTS.md files: it creates missing mirrors, skips
exact ones, and reports anything else as a conflict.
Never write shared instructions into CLAUDE.md. Claude-only knowledge is
rare; when it exists, put it below the @AGENTS.md import and expect
claude-md-fix to keep flagging the file, so the divergence stays visible.
Loading differs by level. At the root, each harness auto-loads its own
file every session: Claude reads CLAUDE.md, others read AGENTS.md. In
subdirectories, Claude auto-injects CLAUDE.md when it touches files there;
other agents see nested AGENTS.md only by reading it on entry. Don't lean
on Claude's auto-injection: a nested AGENTS.md carries the local additions
an agent needs on entry, with everything else inherited from ancestors.
