lean-ctx-review — Claude Code skill: audit ctx_* MCP tools
lean-ctx-review — a skill for Claude Code, Cline, and Kiro that scans the session transcript for ctx_* tool failures and fallbacks to native tools. Confirmed problems get filed as GitHub issues against yvgude/lean-ctx.
Apache-2.0 ★ 3,956 updated 2026-10-29
npx skills add yvgude/lean-ctx --skill lean-ctx-review -a claude-codeWhat lean-ctx-review does
The skill parses the session transcript and builds a table of every ctx_* call — which ones carried is_error, which repeated identical arguments, which requested raw or fresh output, and how many native Read/Grep/Bash calls clustered after a failure.
Parsing requires python3: the skill runs python3 scripts/scan_session.py from its own directory and defaults to the latest file under ~/.claude/projects/*/. The script reports facts; deciding what counts as a problem is left to the developer. Before confirming any finding, the skill queries the yvgude/lean-ctx tracker via gh issue list — a closed issue defines intended behaviour, and a shipped fix that still fails is a regression.
Reproducible findings go to the tracker via gh issue create, with exact arguments, the version from lean-ctx --version, and the OS. If a finding does not reproduce, the skill reports that plainly rather than speculating. Zero findings is a normal and common outcome.
What it helps with
- identify
ctx_*calls that returnedis_error - spot fallbacks to native
Read/Grep/Bashfollowing a tool failure - detect retries with identical arguments
- distinguish a regression from a closed tracker issue
- file a bug in
yvgude/lean-ctxwith a minimal reproduction
Example prompts for the agent
- Review how
ctx_*tools performed in this session - lean-ctx review — why did
ctx_readfall back to native tools? - File an issue in
yvgude/lean-ctxfor the confirmedctx_grepfailure
How to install lean-ctx-review
1Skills CLI (Vercel)
npx skills add yvgude/lean-ctx --skill lean-ctx-review -a claude-code2Manually: put the files in place
~/.claude/skills/lean-ctx-review/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/lean-ctx-review/
1Skills CLI (Vercel)
npx skills add yvgude/lean-ctx --skill lean-ctx-review -a codex2Manually: put the files in place
.agents/skills/lean-ctx-review/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add yvgude/lean-ctx --skill lean-ctx-review -a cursor2Manually: put the files in place
.cursor/skills/lean-ctx-review/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install yvgude/lean-ctx skills/lean-ctx-review2Manually: put the files in place
.github/skills/lean-ctx-review/SKILL.md1Skills CLI (Vercel)
npx skills add yvgude/lean-ctx --skill lean-ctx-review -a gemini-cli2Platform CLI
gemini skills install https://github.com/yvgude/lean-ctx --path skills/lean-ctx-reviewManually: put the files in place
.devin/skills/lean-ctx-review/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about lean-ctx-review
How do I install lean-ctx-review in Claude Code?
Run npx skills add yvgude/lean-ctx --skill lean-ctx-review -a claude-code; the skill will be available at ~/.claude/skills/lean-ctx-review/SKILL.md.
What does lean-ctx-review do?
It reads the session transcript, builds a table of all ctx_* calls with their error flags and fallback patterns, then files confirmed bugs in yvgude/lean-ctx via GitHub CLI.
Does the skill require GitHub CLI?
Yes — tracker searches (gh issue list) and issue creation (gh issue create) both need gh installed and authenticated. Triage still runs without it, but filing issues will not work.
Source text
SKILL.md · Apache-2.0
--- name: lean-ctx-review description: Review how the lean-ctx ctx_* MCP tools performed in the current session and file upstream issues for confirmed problems. Use when the user asks to review/audit lean-ctx tool performance, says "lean-ctx review", asks why ctx_* tools failed or fell back to native tools, or wants to report a lean-ctx bug. --- # lean-ctx session review Upstream repo: `yvgude/lean-ctx` (https://github.com/yvgude/lean-ctx). Reads a Claude Code session transcript, so it applies to agents that write `~/.claude/projects/*/*.jsonl`. Other harnesses need their own extractor; the triage rules below are harness-independent. ## 1. Extract Run from this skill's directory (needs `python3`): ```bash python3 scripts/scan_session.py ``` Defaults to the newest transcript under `~/.claude/projects/*/` — the live Claude Code session. Pass a path to review a different one. `-d N` dumps call `#N` in full. The script reports **facts, not verdicts**: every `ctx_*` call in order, which results the harness flagged `is_error`, which calls repeated identical arguments, which asked for `raw`/`fresh` output, and how many native `Read`/`Grep`/`Bash` calls happened. It deliberately does not guess which of those is a problem — that judgment is yours, below. Transcripts run to megabytes, so read the table, not the raw JSONL. ## 2. Triage **Start from `is_error`.** In practice every genuine tool failure carries it. Then read the call list for the softer signals: identical retries, `raw`/`fresh` re-reads, native calls clustered right after a `ctx_*` call, or a sequence that only completed once `ctx_*` was abandoned. ### Before absolving anything, do these two things Skipping them is how this review returns a false "nothing to report". Both cost one command each. **Search the tracker for the guard or tool you are about to excuse.** Do this during triage, not at step 4. A closed issue defines intended behaviour: if a shipped fix says a form is supported and you just watched it fail, that is a regression and one of the most valuable things this review finds. It also stops you re-filing a settled design decision. ```bash gh issue list --repo yvgude/lean-ctx --search "<guard or tool keyword>" --state all ``` **Probe the stated rationale — never accept a message's self-description.** An error explains itself, and that explanation can be wrong. Three checks, each one command: - *Does the sanctioned alternative achieve the same thing?* If the block is bypassable through a route the message itself recommends, it constrains syntax, not capability. Sometimes that is deliberate (structured input parses reliably where a shell string does not) — decide which, do not assume. - *Does the stated reason match the observed rule?* Vary one axis at a time. A guard blaming payload size that actually keys on path, or blaming a pipe on a command that is piped, is misdiagnosing itself. - *Does the message contradict itself?* A rejection that also states the rejected form is allowed is a finding on its own, whichever way the policy should go. A wrong diagnostic is a real bug even when the block is correct: it sends the next caller down a route that cannot work. ### Not a finding - **Words inside returned content.** A file containing `http.StatusConflict`, a `git rebase` printing `CONFLICT (content):`, `gh` returning `"mergeable":"CONFLICTING"`, a test run printing `not found`. The tool returned exactly what was asked for. Judge the tool's own behaviour, never the payload's vocabulary. - **Self-reference.** Any result that quotes a previous scan, this skill, or a transcript will echo every error word in it. - **Guard blocks — only after they survive the probe above.** Inline env overrides (`GIT_EDITOR=`), shell redirects (`>`/`>>`), non-allowlisted commands, paths outside the project root. "It offered an alternative and the alternative worked" is *not* enough to clear one: that is true of a guard whose reason is wrong, whose rule is different from its description, or that contradicts itself. Clear it only once the stated rationale holds up. - **Malformed tool input.** `InputValidationError` on `__unparsedToolInput` is the caller's own JSON serialization — commonly a raw tab or newline inside a string — rejected before lean-ctx ever ran. - **My own wrong arguments**, a genuinely missing file, a failing build. ### Confirmable The tool did something wrong or unhelpful *given correct input*: - wrong, lossy, or truncated output where the mode promises otherwise - content injected into output documented as verbatim, or anything that breaks a documented output format (e.g. corrupting batch-read separators) - a crash, hang, or schema mismatch against the documented parameters - a documented mode behaving differently than described - a retry that only succeeded after dropping to native tools - **a wrong or self-contradicting diagnostic**, even where the block itself is right — naming the wrong cause sends the next caller down a route that cannot work, and costs more than the block did - **a regression against a closed issue**: a shipped fix says the form is supported, and it is not ## 3. Reproduce **No minimal repro, no issue.** Re-run the exact tool and arguments. If it passes, try to isolate the trigger; if you cannot, do not file — report the observation to the user instead, saying plainly that it did not reproduce and what you tried. Guessing at internals is worse than silence. `lean-ctx --version` for the version line. Zero confirmed findings is a valid and common result. Say so and file nothing. ## 4. File Only for confirmed findings, one issue per distinct problem. You searched the tracker during triage; widen it here if the finding shifted: ```bash gh issue list --repo yvgude/lean-ctx --search "<keywords>" --state all ``` Skip if already reported — and read the close text before re-filing, since a closed issue may have already conceded the point you are about to raise. When a finding contradicts a closed fix, cite it and frame the issue as the gap in that fix. Otherwise: ```bash gh issue create --repo yvgude/lean-ctx --title "..." --body-file <file> ``` Body: what happened, expected, minimal repro (exact tool + args), version, OS. No speculation about internals. End every issue body with the Claude Code attribution footer. Report the issue `html_url` back to the user.
© yvgude · Apache-2.0 · yvgude/lean-ctx