{"slug":"agents-context-router","title":"agents-context-router","summary":"Split a bloated AGENTS.md / CLAUDE.md / README into a small always-loaded kernel plus task-routed wiki topics, loaded on demand by a zero-dependency script (`scripts/ai-context.py list||check`) with byte budgets, so agents stop burning their context window on docs unrelate","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-30T19:53:09.451965Z","repo":{"url":"https://github.com/runkids/my-skills","stars":14,"forks":1,"license":null,"updatedAt":"2026-09-30T18:53:08Z"},"bodyHtml":"
\n

name: agents-context-router\ndescription: Split a bloated AGENTS.md / CLAUDE.md / README into a small always-loaded kernel plus task-routed wiki topics, loaded on demand by a zero-dependency script (scripts/ai-context.py list|<topic>|check) with byte budgets, so agents stop burning their context window on docs unrelated to the task. Use this skill whenever the user says AGENTS.md or CLAUDE.md is too long, too big or loads too much context; asks to split, slim, reorganize, route or \"wiki-fy\" repo docs or agent instructions; wants a docs router, progressive disclosure or context budget for coding agents; mentions milestone logs piling up in the README; or wants multiple agents (Claude Code, Codex, Cursor, Gemini) to share one instruction file, even if they never say \"router\".

\n

Agents context router

\n

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:

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

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.

\n

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

\n\n

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

\n

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, and every item came from a real split.

\n

Workflow

\n

1. Measure

\n

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.

\n

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

\n

2. Classify every section

\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
BucketTestGoes to
KernelWould 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
TopicNeeded only when doing one kind of task: build and deploy, debugging, a subsystem, a tool catalog.wiki/<topic>.md
HistoryDated milestone logs, acceptance runs, \"what we did in M3\".wiki/history/<milestone>.md
HumanIntro, screenshots, setup for people.README.md
\n

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.

\n

3. Move, then write

\n
    \n
  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. \n
  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. \n
  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. \n
  4. Write the topic pages. Move reference text and runbooks in, and cut the duplication the old file had.
    5. \n
  5. Rewrite AGENTS.md as the kernel. Start from assets/AGENTS.kernel.md. It holds:\n
      \n
    • the one-paragraph purpose;
      • \n
    • the language rules, stated once;
      • \n
    • the always-apply rules, including Keep the docs true, verbatim or adapted;
      • \n
    • the hard limits;
      • \n
    • the load-context block with a topic table;
      • \n
    • the verification commands.
      • \n
    \n
    6. \n
  6. Slim README.md to intro, quickstart and a doc map pointing to wiki/README.md.
    7. \n
\n

4. Wire the router

\n
    \n

  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.

    \n
    2. \n

  2. Write docs/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.

    \n
    3. \n

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

    \n
    4. \n

  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. Adapt the paths if the repo uses other directories.

    \n
    5. \n

  5. Run python3 scripts/ai-context.py check. It fails when:

    \n
      \n
    • a path or heading is missing, or a heading is ambiguous;
      • \n
    • AGENTS.md is over its budget;
      • \n
    • a topic is over its budget;
      • \n
    • a topic is not named in AGENTS.md;
      • \n
    • 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.
      • \n
    \n

    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.

    \n
    6. \n
\n

4b. Make drift fail the build

\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Repo hasAdd
package.json\"docs:check\": \"python3 scripts/ai-context.py check\", chained into test
Makefilea docs-check target, made a prerequisite of test or check
.pre-commit-config.yamla local hook: entry: python3 scripts/ai-context.py check, pass_filenames: false
.github/workflows/*.ymla step run: python3 scripts/ai-context.py check in the existing test job
none of theseadd the command to the kernel's Verification block and say so in the report
\n

5. Point every agent at the kernel

\n\n

6. Verify and report

\n\n

Report in the user's language:

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

Maintaining it later

\n

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:

\n\n","files":[{"path":"assets/AGENTS.kernel.md","sizeBytes":2479,"isText":true},{"path":"assets/ai-context.json","sizeBytes":991,"isText":true},{"path":"assets/wiki-ai-context.md","sizeBytes":2923,"isText":true},{"path":"assets/wiki-README.md","sizeBytes":803,"isText":true},{"path":"evals/evals.json","sizeBytes":1870,"isText":true},{"path":"evals/trigger-evals.json","sizeBytes":3834,"isText":true},{"path":"references/gotchas.md","sizeBytes":5818,"isText":true},{"path":"scripts/ai-context.py","sizeBytes":5998,"isText":true},{"path":"SKILL.md","sizeBytes":10228,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-30T19:53:43.717914Z","sha256":"4099BF46EB30804E28010B047C61245BCF92B3FAA61DF3DECDBE8042D389363B","sizeBytes":16640},"review":null,"source":{"repositoryUrl":"https://github.com/runkids/my-skills","path":"agents-context-router","license":null,"commit":"7f33dbc5934c5e27920b3e88e8a6ccb06f304b98","subtreeSha":"6C821EA0D7474464C7F314735EC122D2C861B66897A94563A8B7A1E4553F0185","lastSyncedAt":"2026-09-30T19:53:09.4483Z"},"reviewedAt":"2026-09-30T20:00:17.685977Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/runkids/my-skills/tree/main/agents-context-router"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install runkids-my-skills@llmmart"},{"target":"git","command":"git clone https://github.com/runkids/my-skills.git"}]}