⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
context-doctor
Reduces token waste in Claude Code sessions across two axes — context footprint (auto-generates .claudeignore, guides over-read files and /clear timing) and command output (routes to a command-output proxy/hook such as rtk to trim verbose CLI stdout). In hub environments, regularly audits bloated CLAUDE.md/MEMORY.md/memory/*.md files and proposes compression. Usable standalone without a hub clone.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
forge-harness (FH)
FH is a meta-harness for Claude Code: it helps you build harnesses and skills — the rules, gates and memory a project needs — and checks them before they ship.
A harness is what you wrap around an AI agent in one project so it stops needing the same instructions every session: rules it follows, checks that block bad changes, and a record of what it learned. A meta-harness is the one that builds and verifies those, project after project.
Stop re-explaining your rules to your agent. Put them in the project.
Who it is for, and what you get
For people who use Claude Code (or another coding agent) on real projects and are tired of repeating themselves or of finding out too late that a change was wrong. You get three things:
| You get | In practice | Evidence |
|---|---|---|
| A gate before merge | A diff is judged before it lands, and the verdict names what the change lost. The verdict is a typed value (PASS · PENDING · BLOCKED · ESCALATE), not text you grep. It works on your own code, not only an agent's. | Demo GIF below · a run on code someone else wrote and a planted-hole test, with sample sizes: Evidence · method and controlled ablation: arXiv:2609.04218 |
| Memory that carries over | tracks/ keeps what each session learned, so session 2 starts where session 1 stopped. | At session end the card in tracks/_meta/ is updated, and the next session starts from it (CLAUDE.md §Session Wrap-up). |
| Someone who picks the check for you | Say "diagnose this project" or "accelerate this project" and you get a ranked list of what to fix or install. Nothing is changed until you approve each item. | The procedure is in CLAUDE.md §Field-Harness Diagnostic. Each item lands only after you approve it |
The gates catch you, not only your agent: on 2026-08-22 they blocked the author of FH seven times, and the author caught none of those first (one day of gate blocks).
Quick start
Pick one door. They install differently and give you different things.
Door ① — just the gate. No clone, no plugin, no Claude Code session.
cd your-repo && npx --package @chrono-meta/fh-gate fh-gate # reviews the git diff of the current repo
It finds your changed files from git diff, sends them to a review backend, and prints a verdict
(FH_GATE_VERDICT: PASS | PENDING | BLOCKED | ESCALATE) plus an exit code. A PASS counts only if the review actually ran: a backend that never answered, a dry run, or an unknown exit code is not a PASS, and the GitHub Actions step fails on it by default. Needs Node ≥ 16 and one backend
CLI installed and logged in: claude (default) or codex (FH_BACKEND=codex). Use it in CI, a pre-commit
hook, or beside another agent. A GitHub Actions step and a Homebrew tap exist too — see Run the gate.
Door ② — the whole harness, inside Claude Code.
claude plugin marketplace add https://github.com/chrono-meta/forge-harness.git
claude plugin install -s user fh-meta@forge-harness
git clone https://github.com/chrono-meta/forge-harness.git ~/projects/forge-harness
cd ~/projects/forge-harness && claude # then type: hi (or 안녕 · こんにちは · 你好)
-
Open the cloned folder in Claude Code (the
cd … && claudeline). -
Say hello. In a fresh clone FH reads the checkout, sees no session files, and opens a short menu for new users: create your first project · map an existing project · read the guide. It also tells you if the install wizard has not run yet.
-
Take one win in the same session. Say «Connect a project» (FH scans
../for git repos and createstracks/{project}/), then «accelerate this project» (ranked, approval-gated plan) or «run /context-doctor» (token-waste scan). For full setup, run/install-wizard: every item is approved one by one and a decline is recorded.
Taking it off again. From the FH clone, python3 scripts/fh_detach.py --project <the project you ran the wizard in> prints what the wizard wrote for that project; add --apply to undo it. Other projects keep FH. Add
--machine to also remove what every project shares: the ~/.zshrc block and the FH clone's own hooks and
core.hooksPath (without it they are listed as kept). Another project you ran the wizard in needs its own --project — detach those
first and run --machine last. Changed in 3.32.0: before that, --apply removed the shared setup too. If --project
is the FH clone itself, its own hooks count as that project's and go without --machine. --plugin also runs
claude plugin uninstall fh-meta@forge-harness and removes the forge-harness marketplace entry. A hook counts
as FH's only when every field equals a shipped snippet entry (or the wizard's companion-store hook form) — so o
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
plugins/fh-meta/skills/context-doctor/SKILL.md7.9 KBupstream ↗
--- name: context-doctor description: Reduces token waste in Claude Code sessions across two axes — context footprint (auto-generates .claudeignore, guides over-read files and /clear timing) and command output (routes to a command-output proxy/hook such as rtk to trim verbose CLI stdout). In hub environments, regularly audits bloated CLAUDE.md/MEMORY.md/memory/*.md files and proposes compression. Usable standalone without a hub clone. user-invocable: true allowed-tools: ["Read", "Write", "Bash", "Glob", "Grep"] model: sonnet complexity_routing: base: sonnet high: opus escalate_when: - cold_start - cross_project --- # context-doctor — Token Efficiency Diagnosis + Automatic Prescription Diagnoses the main causes of session token waste and prescribes immediate remedies: 1. No `.claudeignore` → unnecessary files loaded wholesale into context 2. Repeated full reads of large files → paying the same cost N times 3. Not using `/clear` after direction changes → continuing work with accumulated noise 4. Verbose CLI output → every `git`/`ls`/build/test call floods context with stdout (a *different* layer from 1–3 — see §Command-Output Reduction) **Two reduction axes — keep them distinct.** Causes 1–3 are the **context-footprint** axis (what gets read *into* context: files, history). Cause 4 is the **command-output** axis (tokens produced *by* the tools you run). `.claudeignore` cannot touch command output, and a command-output proxy cannot touch file reads — they are complementary, not substitutes. (Step 3.5 below adds an optional **third**, orthogonal lever — provider-side cache billing — distinct from both.) **Standalone install** — this skill works normally with plugin install only, without cloning the full meta-harness. **Built-in `/doctor` first (sister anchor, 2026-07-25)**: since the Claude 5 generation, the official `/doctor` command claims skill/CLAUDE.md rightsizing ("The new rules of context engineering for Claude 5 generation models" — https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models). Run the built-in first when available — its scope is skills + CLAUDE.md rightsizing only. This skill's increment over it = `.claudeignore` diagnosis/generation (Step 1), `/clear` timing guidance, command-output proxying (§Command-Output Reduction), hub-wide memory/CLAUDE.md audits, and the measurement discipline (resident footprint is measured only via a fresh top-level `/context`, and any diet is followed by a `prompt-regression` probe — the blog's own "no measurable loss" claim ships no method, so treat that number as a vendor claim). Triage record: `tracks/_audit/session_2026_07_25_claude5-context-rules-sister.md`. ## Execution Steps ### Step 1. `.claudeignore` Diagnosis + Generation Check whether `.claudeignore` exists in the project root (bash in §Step-Bash). **If absent**: Scan project structure and auto-generate. **If already present**: Keep existing content + suggest additional patterns only (no overwrite). Check for sentinel comment (`# context-doctor:`) and add to first line if absent. Generation criteria — by project type: | Detected type | Additional patterns | |---|---| | Node.js (`package.json`) | `node_modules/` · `dist/` · `build/` · `.next/` · `coverage/` | | Python (`pyproject.toml` / `setup.py`) | `__pycache__/` · `.venv/` · `*.egg-info/` · `dist/` · `.pytest_cache/` | | Java (`pom.xml` / `build.gradle`) | `target/` · `build/` · `.gradle/` | | Common (always include) | `.git/` · `*.log` · `*.lock` · `*.min.js` · `*.min.css` | Present preview to user after generation → save after confirmation. Automatically add sentinel comment to first line when generating/updating: ``` # context-doctor: configured YYYY-MM-DD ``` → Suppresses auto-invocation in subsequent sessions. > **Detail**: See `SKILL_detail.md §Step-Bash` — detection bash for Steps 1/2/4/5, large-file warning format, audit report format — read when executing any step's commands. ### Step 2. Large File Detection + Split Strategy Guidance Detect files exceeding 500 lines (top 10 — bash in §Step-Bash) and output the split-read guidance per file (offset + limit, section by section). **Repeated full-read pattern** (burst pattern) detection criteria (behavioral): - 3+ files over 500 lines exist and `.claudeignore` was absent - User mentions "read it all at once" / "re-read the whole thing every time" When burst pattern is detected → **trigger harvest-loop integration in Step 4**. ### Step 3. `/clear` + Model Switching Timing Guide Check session state with the user, then prescribe according to context: **Wrap-then-Compact** (when approaching context limit — CC subscription only): When context is near the limit and you want to *preserve state* rather than reset: 1. Ask Claude: `"wrap up — completed items, modified files, pending tasks"` 2. Claude writes a structured summary → that summary anchors the `/compact` output 3. Run `/compact` — the wrap becomes the cold-start primer for next session > This is superior to blind `/compact` because you control what's preserved. Bedrock/API has no meter warning — CC subscription only. → Full pattern + table: `CHEATSHEET.md §10 Lever 6` **`/clear` recommended situations** (reset, not preserve): ``` □ Work direction has changed significantly (exploration → implementation, bug fix → refactor, etc.) □ Switching to a different track/project □ Error debugging has gone long and noise has accumulated □ Previous attempts are unrelated to current work □ Context has grown large (context rot — measurable quality degradation as input length grows, well before the window fills; threshold varies by model/task. Chroma 2025 context-rot research) ``` → Recommend immediate `/clear` and restart in fresh context. **Model switching criteria**: | Current task | Recommended | Command | |---|---|---| | Complex design decisions · architecture review | Opus — dispatch-first: package into an opus/sidecar agent dispatch (consent-gated); session pin secondary | dispatch · or `/model opus` | | Code writing · file editing · refactoring | Sonnet (default) | — | | Simple file lookup · short Q&A | Haiku | `/model haiku` | > Models are tools for allocating the right expertise to complexity. Opus for simple tasks = wasted expertise; Haiku for design decisions = insufficient expertise. Switch models when task nature changes. ### Step 3.5. Cache-Boundary Audit (prompt caching, optional third lever) Distinct from both axes above: Steps 1–3 reduce what occupies the context *window*; this reduces what the provider re-bills as **fresh input tokens** on each turn by preserving prompt-cache hits. **Optional** — run it when a metered/quota-limited backend makes cache cost the binding constraint (same gating logic as §Command-Output Reduction: diagnose and recommend, do not chase this when tokens are merely plentiful). **Audit checklist**: - Is the system prompt / CLAUDE.md content **stable byte-for-byte** across turns in a session? Any turn-to-turn diff in the fixed prefix invalidates the cache for that prefix — which is in tension with Step 5's CLAUDE.md-compression prescription: compress at session boundaries (before a fresh cache is built), never mid-session (which would invalidate one already warm). - Is session-specific / dynamic content (task state, recent results) placed at the **end of the user message**, not interleaved into the system prompt or early context? **Reported, UNCALIBRATED by FH** (2026-07-27 frontier digest, issue #102): input:output token ratio **> 10:1** favors cache/context engineering over model-level optimization; **> 50:1**, prefix caching dominates; cache-boundary control reportedly raised hit rate ~7%→84% in one production case (arXiv:2603.09619 *Context Engineering: From Prompts to Corporate Multi-Agent Architecture* · appscale.blog). **What is and is not verified** — the two are separate checks and only one has been run: the cited paper's **existence** was confirmed 2026-README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/chrono-meta-forge-harness-plugins-fh-meta-skills-context-doctor.md