context-shunt - Claude MCP Skill

# Context Shunt — Read Cheap, Keep Context Small

Reading big files into context is the most expensive thing an agent does for the
least reasoning value. The shunt hands those reads to a cheap worker model
(`bulk-read`) that answers a question about the files and returns a compact
summary. The raw bytes never enter this session's context.

This is orthogonal to whole-turn routing (srooter / `route-task`): those pick the
model for the *turn*; the shunt trims what a *tool call* pulls into context when
the turn is legitimately here.

## Decision: read raw, shunt, or graph?

- **Editing this exact file** — read it raw. You need every line; never edit against a summary.
- **A fact/answer across large or many files** — `bulk-read "<question>" file...`.
- **A code symbol (function/class/route)** — `get_code_snippet(qualified_name)`: free and exact.
- **Small file (under threshold) you need in full** — read it raw.

A shunt answer is for understanding, not for producing a diff.

## Usage

```bash
bulk-read "how does token refresh work?" src/auth/session.ts src/auth/refresh.ts
bulk-read "which config keys are read at startup?" $(git ls-files 'config/*.yaml')
```

`bulk-read` prints structured bullets citing `path:line`, or
`NOT FOUND IN PROVIDED FILES`. A token-savings report goes to stderr.

## Configuration

Env vars or `~/.claude/shunt.conf` (see `templates/shunt.conf`):

- `SHUNT` — `on`/`off` master switch for the PreToolUse hook.
- `SHUNT_MIN_LINES` — large-read threshold (default 350).
- `SHUNT_MODE` — `suggest` (default) / `block` / `off` for the hook's large-read action.
- `SHUNT_GRAPH_NUDGE` — `on`/`off` once-per-session graph nudge.
- `SHUNT_MODEL` — worker command (default `deepseek --flash`; also `gemini-api --flash-lite`, `qwen3`, `glm`).

The `context-shunt-gate` PreToolUse hook enforces the thresholds; this skill tells
you when to reach for `bulk-read` yourself.