Agents context router

Coding agents load the root instruction file (AGENTS.md, CLAUDE.md) on every task. As a project ages it collects milestone logs, tool catalogs, runbooks and one-off lessons, until every task pays tens of KB of context for text it does not need. The fix is a kernel + router layout:

AGENTS.md                 kernel: rules every task needs + how to load more (≤ 8 KB)
wiki/ai-context.json      topic → sources (whole file or one exact heading); the single truth
scripts/ai-context.py     list | <topic> | check  (bundled with this skill)
wiki/README.md            human router table (mirrors the JSON)
wiki/ai-context.md        in-repo maintenance manual (works without this skill)
wiki/<topic pages>.md     how-to / reference, one per task seam
wiki/history/*.md         milestone logs, verbatim, never loaded by default
README.md                 humans: what it is, quickstart, doc map

An agent reads the kernel, picks the one topic that matches its task, and runs python3 scripts/ai-context.py <topic> to print only those sections, each marked <!-- path § heading -->, so it knows where to edit.

The layout also maintains itself once this skill is gone, because every piece lives in the repo:

• The kernel's "Keep the docs true" rule makes every agent, on every task, fix a stale doc in the same change that makes it stale.
• wiki/ai-context.md is the procedure.
• check fails on orphans and budget overruns.
• CI runs check, so drift breaks the build instead of rotting quietly.

Leaving out any one of these four is how routed docs decay back into a pile.

Before you start, read references/gotchas.md. It lists the traps that make this refactor quietly lose content or route agents to the wrong text. It is short.

Workflow

1. Measure

List every file an agent loads automatically: root and nested AGENTS.md/CLAUDE.md, and anything they @import. Also list the files agents are told to read "first". Record their byte sizes (wc -c). These numbers go in your final report as before and after.

Keep a backup of each original outside the repo (or rely on git), because step 3 moves text and you will diff against it.

2. Classify every section

Read the whole file and put each section into exactly one bucket:

Bucket	Test	Goes to
Kernel	Would a wrong action happen on any task if the agent did not know this? Examples: hard limits, safety rules, language rules, where outputs may go, the rule that says when to load a topic.	AGENTS.md
Topic	Needed only when doing one kind of task: build and deploy, debugging, a subsystem, a tool catalog.	wiki/<topic>.md
History	Dated milestone logs, acceptance runs, "what we did in M3".	wiki/history/<milestone>.md
Human	Intro, screenshots, setup for people.	README.md

Some text changes buckets. A behaviour rule learned the hard way (for example "if every job fails the same way, suspect our code before the site") is kernel. The procedure for acting on it is topic. A history section that is still the operating manual (a "Usage" section in a milestone log) stays in history, and a topic references its exact heading.

3. Move, then write

1. Before moving any log, pull out the live rules hidden in it. Old logs often contain a rule that is still in force, written as an aside ("note: never run X on shared"). Once the log moves to history, no agent will ever see that rule again. Grep each log for imperative words in every language it uses, for example never|always|must|do not|don't|warning|note:|avoid|forbidden|required. For each hit that is still valid, copy it as a one-line rule into the kernel (if it applies to every task) or into its topic. List every promoted rule in your report.
2. Create wiki/history/ and move milestone logs there verbatim, in their original language. Do not translate or summarise while moving. Verbatim moves are diffable and lose nothing.
3. Design topics around tasks the agent will be doing, not around the old file order. Aim for 5–12 topics. Each one gets a kebab-case name and a single "use when…" line. Ask: "an agent is about to do X; which pages must it see?"
4. Write the topic pages. Move reference text and runbooks in, and cut the duplication the old file had.
5. Rewrite AGENTS.md as the kernel. Start from assets/AGENTS.kernel.md. It holds:
   • the one-paragraph purpose;
   • the language rules, stated once;
   • the always-apply rules, including Keep the docs true, verbatim or adapted;
   • the hard limits;
   • the load-context block with a topic table;
   • the verification commands.
6. Slim README.md to intro, quickstart and a doc map pointing to wiki/README.md.

4. Wire the router

1. Copy scripts/ai-context.py from this skill to <repo>/scripts/ai-context.py. It resolves the repo root as the script's parent's parent.

2. Write wiki/ai-context.json from assets/ai-context.json. Use {"path": ...} for a whole page. Use {"path": ..., "heading": "Exact Heading Text"} to pull one section out of a bigger page, such as a single tool group from a catalog.

3. Write wiki/README.md from assets/wiki-README.md: the topic table for humans, plus a history index.

4. Copy assets/wiki-ai-context.md to wiki/ai-context.md and keep the ai-context topic that points at it. This is the manual any future agent loads to maintain the router, with or without this skill. The config location wiki/ai-context.json is fixed in the script. If the repo uses other directories, set wikiDir, historyDir, routerFile or rootInstructions in the JSON, and update the paths in wiki/ai-context.md to match.

5. Pick the Python command for this machine and repo. The assets and examples in this skill write python3, which does not exist on a typical Windows install (it is often a Microsoft Store stub that fails). Probe python3 --version, then python --version, then py -3 --version; the first that prints Python 3.8+ is the command. On Windows expect python or py -3. Write that same command everywhere you copy text from the assets: AGENTS.md, wiki/README.md, wiki/ai-context.md, and the CI/hook entries in 4b. If the repo is used from both Windows and Unix, say so in the kernel's load-context block (for example "Windows: python or py -3"). Do not add a wrapper script.

6. Run check with that command (python3 scripts/ai-context.py check below). It fails when:

   • a path or heading is missing, or a heading is ambiguous;
   • AGENTS.md is over its budget;
   • a topic is over its budget;
   • a topic is not named in AGENTS.md;
   • there is an orphan: a wiki page no topic loads, a history file missing from the wiki/README.md index, or a nested AGENTS.md no topic loads.

   Fix the docs, not the caps. When a topic is too big, split it. When a page really is human-only, list it under "unrouted" with a reason, and remove the template's example entry.

4b. Make drift fail the build

Wire check into whatever the repo already runs on every change. Use the one that exists; do not add new tooling:

Repo has	Add
package.json	"docs:check": "python3 scripts/ai-context.py check", chained into test
Makefile	a docs-check target, made a prerequisite of test or check
.pre-commit-config.yaml	a local hook: entry: python3 scripts/ai-context.py check, pass_filenames: false
.github/workflows/*.yml	a step run: python3 scripts/ai-context.py check in the existing test job
none of these	add the command to the kernel's Verification block and say so in the report

5. Point every agent at the kernel

• One file for every agent. Keep the rules in AGENTS.md. If an agent you use does not read AGENTS.md natively, make its file a one-line pointer instead of a copy (for Claude Code, a CLAUDE.md holding @AGENTS.md). Two full copies drift apart within a week. Check each agent's current docs or version, because native support is changing fast.
• Skills and scripts are adapters. If the repo has skills, commands or prompts that restated the old docs, cut them down to workflow steps that say "load topic X". The rules live only in the kernel and the wiki.
• Other agents' stale paths. If other agents or sessions are working in the repo, tell them the docs moved and which topic replaces what, because their context still holds the old paths.

6. Verify and report

• Run check and show its output.
• Run ai-context.py <topic> for two or three topics, and read the output as an agent would. Can you do the task from this alone?
• Grep for links to old anchors and moved files, and fix them.
• Compare the byte totals between the backup and the new tree. A large drop in total bytes, not just kernel bytes, means content was lost rather than moved. Find out where it went.

Report in the user's language:

## Context split
- Always-loaded: <before> B → <after> B (<file list>)
- Topics: <n>; largest <name> <bytes> B; all under budget (check output below)
- Moved verbatim to wiki/history: <n> files
- Content kept: <total before> B → <total after> B (<explain any drop>)
- Adapters updated: <skills/CLAUDE.md/etc>
- Self-maintenance: kernel rule ✓, wiki/ai-context.md ✓, check in <CI/test/pre-commit> ✓
- Follow-ups: <e.g. translate zh pages, split topic X if it grows>

Maintaining it later

Upkeep is the job of the repo's own wiki/ai-context.md and the kernel rule, not this skill, so it happens on ordinary tasks too. When this skill is triggered for maintenance (for example "add this runbook", "check is failing" or "we finished M7"), load the ai-context topic and follow it:

• New knowledge: put it in the page for its topic. If no topic fits, add a page, map it in the JSON, add it to both tables and run check.
• New milestone: add wiki/history/<m>.md and one row in the history index. Nothing is added to the kernel unless it is a rule for every task.
• Kernel near its budget: that is the signal to move something out, not to raise the cap.
• Orphan failure: map the page to a topic, index the history file, or, only if it is really human-only, list it under "unrouted" with a reason.