skim

Your agent wrote 11 paragraphs. You needed 6 facts.

Skim is output discipline for coding agents.

It turns the usual foam into compact, vertical answers: one fact per line, useful symbols, shallow nesting, no warm-up paragraph, no tiny management consultant living in your terminal.

before
  "I've updated the authentication flow..."
  1 paragraph
  3 files hiding inside it
  warning bolted onto the end

after
  facts visible at left edge
  files grouped by job
  warning impossible to miss

Skim works anywhere that can load a SKILL.md, including Claude Code, Cursor, Pi, and compatible agent runners.

See it

Normal output:

I've updated the authentication flow. I modified three files: auth.ts to add token refresh, session.ts to extend expiry handling, and api.ts to retry on 401. All 42 tests pass. I didn't touch the mobile client, which may need the same fix.

Skim output:

Auth flow updated.

✓ changes
  auth.ts refresh logic
  session.ts expiry handling
  api.ts retry on 401

✓ verification
  tests 42/42

⚠ remaining
  mobile client untouched

Same payload. Less archaeology.

Install

Pi installs the complete extension and packaged profiles from npm:

pi install npm:@joshbochu/skim

Portable skill-only install for compatible runners:

npx skills add joshbochu/skim

Manual install for Cursor:

git clone https://github.com/joshbochu/skim ~/dev/skim
ln -s ~/dev/skim/skills/skim ~/.cursor/skills/skim

Manual install for Claude Code:

ln -s ~/dev/skim/skills/skim ~/.claude/skills/skim

Pi loads the extension from the npm package. Its selected mode persists between sessions and its packaged rules reload on every turn.

Use

Use the Pi commands:

/skim on        activate and persist
/skim off       disable
/skim capture   save last exchange for review
/skim pr        reshape and update the current branch PR body
/skim pr <url>  reshape and update the given GitHub PR body

/skim pr is a one-shot write action. It does not persist and does not change later agent turns. With a GitHub PR URL it reshapes that PR's description; with no URL it resolves the open PR for the current branch.

Capture accepts a note:

/skim capture too much normal prose

Captures stay local in ~/.pi/agent/skim/captures/. They may contain prompts, responses, code, or other sensitive material. Inspect them before sharing.

Candidate profile sandbox

The main /skim on profile is the promoted Caveman-Ultra contract. Infrastructure for trying alternate versions remains in the repo (skills/skim-v2/, compare evals, ENABLE_VERSION_OPTIONS in extensions/skim-mode.mjs), but version options are hardcoded off. Users only see regular skim.

When iterating internally, overwrite skills/skim-v2/ with a candidate, evaluate with eval:skim-v2 / eval:compare, then promote into skills/skim/ and rules/ after review.

The contract

Skim does not ask the agent to "be concise" and hope for the best. It gives the output a grammar.

shape
  0-1 terse headline
  1 fact per line
  structured body: 1-5 top-level anchors
  1-5 child facts per anchor
  3 indent levels maximum

wording
  Caveman-Ultra fragments
  answer-first ordering
  numerals instead of number words
  no invented abbreviations

line budget
  18 default (DEFAULT_ULTRA)
  42 only on exact "Full Explanation Please"
  45-65 visible characters preferred
  split before 72 when possible
  code and errors remain exact

escape hatch
  fewer than 3 facts
  use 1-2 plain fact lines
  put the machinery away

Hard boundary: code, commands, URLs, identifiers, quoted text, and error messages stay byte-exact. Compression never gets to "fix" the evidence.

Commits, documentation, and code comments keep normal prose. Pull request descriptions do too unless /skim pr explicitly applies the PR-body rules. Skim is a reply format, not permission to write cursed release notes.

Small symbol cult

The vocabulary is deliberately boring. If a symbol needs a decoder ring, it does not belong here.

| Symbol | Meaning | Symbol | Meaning | |---|---|---|---| | → | next, result | ✓ | done, pass | | ⇒ | rule, implication | ✗ | fail, missing | | ∵ | cause | ⚠ | caution, risk | | ∴ | conclusion | Δ | changed | | ? | unknown | ≈ < > ≠ | comparison | | · | shared predicate | \| | choice |

Relations get their own lines. Horizontal symbol soup is still soup.

bad
  leak → pool fills → tests fail

good
  tests fail
    ∵ pool exhausted
    ∵ connections leaked

Caveman ancestry

caveman attacks output-token count. Skim borrows its telegraphic wording, then aims at a different bill: reader attention.

| | caveman | skim | |---|---|---| | optimizes | output tokens | reader effort | | design unit | token | fact line | | layout | mostly horizontal | vertical and grouped | | symbols | usually avoided | used when immediately clear |

Use Caveman when the token bill hurts. Use Skim when the scrollback hurts.

Repository anatomy

skills/skim/SKILL.md       portable skill contract (main)
skills/skim-v2/            candidate sandbox for next iteration
extensions/skim.ts         on/off toggle, persistence, injection
extensions/skim-mode.mjs   command parsing + ENABLE_VERSION_OPTIONS
rules/                     live-reloaded Pi rules for main mode
evals/cases.json           main behavior corpus
evals/compare-cases.json   balanced main/candidate A/B corpus
evals/compare.mjs          matched skill comparison
evals/skim-v2-cases.json   candidate behavior corpus
evals/gold/                hand-approved outputs
evals/lint.mjs             deterministic structure checks

The skill is the product. The Pi extension is the switchboard. The evals keep prompt edits from quietly turning "dense" back into "sounds professional."

Hack on it

npm test
npm run eval:lint
npm run eval:dry
npm run eval -- --label baseline
npm run eval:skim-v2:dry
npm run eval:skim-v2 -- --label candidate
npm run eval:compare:dry
npm run eval:compare:smoke

eval:lint checks the gold corpus without calling a model. eval:dry shows the planned benchmark. The full eval stores raw outputs, exact prompts, stderr, and summaries under evals/results/. The comparison runner also records exact token/cost/timing data, blind semantic grades, a Markdown report, and a side-by-side feedback reviewer.

See evals/README.md for the benchmark loop and IMPROVING.md for the backlog.

npm releases

The package version is owned by the publish workflow on main. Feature pull requests do not need to bump package.json; every publishable merge ships a fresh npm version. See RELEASING.md.

Why these numbers

The 3-5 item groups and short lines are engineering defaults, not scripture. They are informed by working-memory research, readable line-length guidance, and left-edge scanning behavior. More importantly, they are executable rules that can be tested instead of an adjective like "concise."

When a rule makes an answer harder to decode, meaning wins.

License

MIT