Skills for Context and Token Discipline: caveman, handoff, karpathy-guidelines

Context and token skills are Agent Skills that control what a coding agent writes, reads, and loses between sessions. caveman shortens the agent’s prose, handoff writes a portable brief that a fresh session resumes from, and karpathy-guidelines keeps each diff to the request. None of them proves the work is correct; tests and CI still do.

You are three hours into a webhook-retry migration. The context meter reads 70%, the agent narrates every tool call in four paragraphs, and the next compaction will squeeze the reasons behind six decisions into one line of summary. Tomorrow’s session will re-derive those decisions, or quietly contradict them. This page is for developers who run long agent sessions, and for tech leads who want one team-wide way to carry work from one session to the next.

What you get from context and token skills

• A map of five skills and one plugin: what each saves, what it costs, and when it is the wrong tool
• A decision table for the phase boundary: compact, clear, fork, or hand off
• Install commands for Claude Code, Codex, and Cursor, checked against skills CLI 1.7.0 on 2026-09-26
• A worked handoff at 70% context, with the prompts that write, audit, and resume it
• A multi-session workflow in which commits and tests, not the conversation, carry the state

Which context and token skills solve which problem?

Each skill attacks a different leak. Pick by the symptom you see, not by the install count.

Skill (repository)	What it changes	Fires	Pick it when
caveman (JuliusBrussee/caveman)	The agent answers in short fragments. Code, commands, paths, and exact errors stay verbatim; security warnings and irreversible-action confirmations return in full sentences	On /caveman, “be brief” or “less tokens”; the Claude Code plugin turns it on at every session start	Prose, not code, fills the conversation
caveman-compress (same repository)	Rewrites a memory file such as CLAUDE.md in compressed form and keeps a readable backup	On /caveman-compress <file>	A memory file loaded into every session has grown long
handoff (mattpocock/skills)	Writes a handoff document that references specs, plans, and commits instead of copying them, adds a “suggested skills” section, and redacts secrets	Only when you type /handoff (disable-model-invocation: true)	The work must outlive the session: overnight, another harness, a colleague, or a forked side task
karpathy-guidelines (multica-ai/andrej-karpathy-skills)	Four rules: think before coding, simplicity first, surgical changes, goal-driven execution with a verify step per plan item	When the agent writes, reviews, or refactors code	Diffs sprawl, and every sprawling diff costs context to read and time to verify
Agent Skills for Context Engineering (muratcankoylan)	17 skills on context design, such as context-degradation, context-compression, filesystem-context, and multi-agent-patterns	When you design or debug an agent harness	You build agents or subagent setups, not only use them
planning-with-files (OthmanAdi)	Keeps task_plan.md, findings.md, and progress.md on disk and re-reads the plan as work proceeds	Plugin commands and hooks	A task runs for days and needs a durable plan; covered in persistent memory plugins

Popularity, as of 2026-09-26: skills.sh all-time installs were handoff 869,575 and caveman 539,286. Both counts come from the third-party LinklyAI/best-skills scrape of that date (a secondary source; re-read the live numbers on skills.sh). GitHub stars on the same date: multica-ai/andrej-karpathy-skills 215.2k, JuliusBrussee/caveman 107.9k, OthmanAdi/planning-with-files 27.1k, and muratcankoylan/Agent-Skills-for-Context-Engineering about 18k. Stars measure attention on a repository, not use of one skill.

Should you compact, clear, fork, or hand off?

Every option except “keep going” turns the conversation into a summary. The difference is where the summary lives and who can read it. At most boundaries /compact is enough; reach for a handoff file only when the work has to travel.

Move	What survives	Use it when
Keep going	Everything	The task finishes well inside the window
/compact [focus]	A summary inside this session, steered by your focus text	Same tool, same directory, same task, and you stay in the loop
/clear	Nothing from the conversation; project memory files reload	The finished phase is disposable
/fork, /branch (Claude Code), /fork or codex fork (Codex)	An exact copy of the context	A side experiment on the same machine and tool
/handoff	A file you can read, correct, move, and share	The next session starts later, in another tool, or with another person
On-disk plan (planning-with-files or your own plan file)	The plan and progress, updated as work happens	The task spans days, whatever you do at each boundary

Claude Code 2.1.283 has no bundled /handoff command (checked against its command reference on 2026-09-26), so /handoff always means the skill.

How do you install the context and token skills?

The portable route is the skills CLI (npm skills 1.7.0). It installs into each agent’s own skills folder: .claude/skills/ for Claude Code and .agents/skills/ for Codex. It records every install in skills-lock.json. Install at project scope so the set is reviewed and committed like code.

1. Install the skills in the repository root.

   Claude Code

   # handoff: portable copy, invoked as /handoff
   npx skills add mattpocock/skills --skill handoff -a claude-code -y
   
   # caveman: the output style and the memory-file compressor only
   npx skills add JuliusBrussee/caveman --skill caveman caveman-compress -a claude-code -y
   
   # karpathy-guidelines as a plugin (the README's recommended route)
   claude plugin marketplace add multica-ai/andrej-karpathy-skills
   claude plugin install andrej-karpathy-skills@karpathy-skills
   
   # context engineering: name the skills; --full-depth is required
   npx skills add muratcankoylan/Agent-Skills-for-Context-Engineering --full-depth \
     --skill context-degradation context-compression -a claude-code -y

   Alternatives: claude plugin install mattpocock-skills --scope project installs all 25 Pocock skills, namespaced as /mattpocock-skills:handoff. claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman installs the caveman plugin, whose SessionStart and UserPromptSubmit hooks run Node scripts and switch caveman on in every session.

   Codex

   npx skills add mattpocock/skills --skill handoff -a codex -y
   npx skills add JuliusBrussee/caveman --skill caveman caveman-compress -a codex -y
   npx skills add multica-ai/andrej-karpathy-skills --skill karpathy-guidelines -a codex -y
   npx skills add muratcankoylan/Agent-Skills-for-Context-Engineering --full-depth \
     --skill context-degradation context-compression -a codex -y

   Codex reads .agents/skills/; type /skills to list what loaded and $handoff to invoke a skill by name. The handoff skill’s agents/openai.yaml sets allow_implicit_invocation: false, so Codex runs it only when you name it. The context-engineering repository has no Codex plugin marketplace manifest, so the skills CLI is the route there.

   Cursor

   npx skills add mattpocock/skills --skill handoff -a cursor -y
   npx skills add JuliusBrussee/caveman --skill caveman caveman-compress -a cursor -y
   npx skills add multica-ai/andrej-karpathy-skills --skill karpathy-guidelines -a cursor -y
   npx skills add muratcankoylan/Agent-Skills-for-Context-Engineering --full-depth \
     --skill context-degradation context-compression -a cursor -y

   The karpathy repository also ships a committed Cursor rule, .cursor/rules/karpathy-guidelines.mdc, which you can copy into your own .cursor/rules/ instead of installing the skill. Cursor’s skills documentation could not be re-checked on 2026-09-26; if a skill does not appear, ask the agent to use it by name.

2. Check what landed. npx skills list shows the installed skills. In Claude Code, claude plugin details andrej-karpathy-skills@karpathy-skills prints a plugin’s inventory and projected context cost, and /context before and after an install shows the difference in the current session.

3. Read the files, then commit them. Skills run with the agent’s permissions, and caveman-compress ships Python scripts that call Claude. Commit .agents/skills/, .claude/skills/, and skills-lock.json (or .claude/settings.json for plugins), and review changes to them in pull requests. See skill supply-chain security for the review checklist.

Traps when installing context and token skills

• caveman is 20 skills, not one. The repository also ships lean-build, surgical-patch, verify-and-stop, and others (skills CLI 1.7.0 --list, 2026-09-26). The README’s --skill '*' installs all 20, and several overlap karpathy-guidelines and your debugging skills. Name the skills you want.
• The caveman plugin is on everywhere. Its session-start hook activates caveman in every Claude Code session, including the ones where you write pull request descriptions or docs. Say stop caveman, or type /caveman off.
• The caveman proxy is a different product. @caveman-ai/cli sits between the agent and the provider, ships a BSL-1.1 runtime, and sends anonymous counts by default according to its README (caveman telemetry off). This page covers the MIT-licensed skill only.
• Agent Skills for Context Engineering needs --full-depth. Without it, skills CLI 1.7.0 finds one wrapper skill, context-engineering-collection. With it, --list shows 23 entries, including example and template skills you do not want in a coding repository.
• The karpathy repository moved. forrestchang/andrej-karpathy-skills now redirects to multica-ai/andrej-karpathy-skills. The README still prints the old owner; a redirect can break if the old name is registered again.
• claude-handoff is unfinished. mattpocock/skills also carries claude-handoff, which starts a claude --bg session with the summary as its prompt. It sits under skills/in-progress/; use handoff.
• --skill=<name> is silently ignored by skills CLI 1.7.0, and with -y it installs every skill in the repository. Write --skill handoff with a space.

What does a handoff at 70% context look like?

The example below is an illustration of the steps, not a recorded run. The repository, commits, and file names are invented for the example.

Why 70%: at that point the agent still writes the handoff from the full conversation, not from an earlier compaction summary, and there is room left for the handoff itself. It is a rule of thumb, not a vendor threshold. Claude Code on a model with a native 1M window compacts at about 967K tokens by default, so waiting for auto-compaction means waiting a long time with a lot of stale context.

1. Put the meter where you can see it. In Claude Code, add a status line to ~/.claude/settings.json; the example comes from Claude Code’s status line documentation:

   {
     "statusLine": {
       "type": "command",
       "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
     }
   }

   used_percentage measures against the model’s full window. If you set CLAUDE_CODE_AUTO_COMPACT_WINDOW, the percentage no longer tells you when compaction runs. /context shows the full breakdown. In Codex, add context usage to the footer with /statusline and hand off at the same 70% used; /status shows token usage. In Cursor, hand off at each phase boundary instead of at a number.

2. Reach a green checkpoint first. Finish the current slice, run the tests, and commit. A handoff written in the middle of an edit describes a state that no commit holds.

3. Write the handoff. Pass the next session’s job as the argument, so the skill keeps the reasoning that bears on it.

   Copy-paste prompt: write the handoff

   /handoff Next session: finish slice 4 of docs/plans/webhook-retry.md (dead-letter
   table and replay endpoint). In the document, split "Verified" (with the command
   or commit that proves it) from "Assumed, not checked". List the exact test command
   to run first. Reference the spec, the plan, and commits by path or hash; do not
   copy them. Tell me the absolute path of the file you wrote.

4. Move the file somewhere durable. The skill’s SKILL.md tells the agent to save to the operating system’s temp directory, not the workspace. A reboot, a container reset, or a sandbox that discards /tmp deletes it. Copy it into a git-ignored folder in the repository:

   mkdir -p .handoffs && grep -qx '.handoffs/' .gitignore || echo '.handoffs/' >> .gitignore
   cp /tmp/handoff-webhook-retry.md .handoffs/2026-09-26-webhook-retry.md

   Replace /tmp/handoff-webhook-retry.md with the path the agent reported.

5. Audit the handoff before you clear. The next agent treats the document as a contract and does not re-check it. A belief written as a fact (“the replay endpoint is done”) becomes a false premise.

   Copy-paste prompt: audit the handoff against the repository

   Read .handoffs/2026-09-26-webhook-retry.md. For every item under "Verified",
   confirm it against the repository: the commit exists on this branch, the file
   path exists, and the named test passes when you run it. Move anything you cannot
   confirm to "Assumed, not checked". Do not change code. Show me the diff of the
   handoff file only.

6. Start fresh and resume. Clear the session: /clear webhook-retry-day1 in Claude Code (the name labels the old conversation in the /resume picker), /new in Codex, or a new Agent chat in Cursor. Then point the new session at the file; do not paste the summary into a shell command, where backticks and $(...) get mangled.

   Copy-paste prompt: resume from a handoff

   Read .handoffs/2026-09-26-webhook-retry.md, then docs/plans/webhook-retry.md.
   Before any edit, run the test command the handoff lists and tell me whether the
   result matches its "Verified" section. If anything differs, stop and report the
   difference. If it matches, load the suggested skills and continue with the first
   open item of slice 4.

A good handoff for this task is short, because the spec and plan already hold the settled detail:

# Handoff: webhook retry, slice 4

## Goal for the next session
Dead-letter table and replay endpoint (docs/plans/webhook-retry.md, slice 4).

## Verified
- Slices 1-3 merged on branch feat/webhook-retry at 4f5e6a7.
- `npm test -- webhooks` passes at 4f5e6a7 (41 tests).

## Assumed, not checked
- Migration 021 (dead_letter table) is drafted in db/migrations/, not applied.

## Decisions and why
- Retries stop after 6 attempts: spec docs/specs/webhook-retry.md section 3.
- Replay is admin-only: ADR docs/adr/0012-replay-auth.md.

## Next steps
1. Apply migration 021 locally; run the migration test.
2. Write the failing test for POST /admin/webhooks/:id/replay.

## Suggested skills
tdd, diagnosing-bugs

How do you run a long task across sessions without compaction loss?

Compaction loss is a symptom of state that lives only in the conversation. The fix is to move state into artifacts the next session can read and CI can check, and to treat every session boundary as a checkpoint.

1. Plan on disk. Write the spec and a sliced plan to files before building; grill-me is the Pocock skill for getting there. For multi-day work, planning-with-files keeps plan, findings, and progress files current as the agent works.

2. Build in small slices. karpathy-guidelines makes the agent state assumptions, touch only what the request needs, and name a verify step for each plan item. A small diff costs less context to read now and less review time later.

3. End every slice green and committed. The commit and the passing tests are the checkpoint. The conversation is not.

4. Keep the window lean. Turn on /caveman lite for long debugging or exploration phases, where narration dominates. Run /caveman-compress CLAUDE.md once if your memory file has grown long, then review the diff line by line: that file steers every session. Keep focus text on compactions, for example /compact keep the decisions list, open questions, and failing test names.

5. At the phase boundary, pick the move from the decision table. Same tool and same task: compact. Next session tomorrow, in another tool, or for someone else: hand off, audit, and clear.

6. Resume with a test run, not a recap. The first action of every new session is the test command from the handoff. A green run that matches the handoff lets the work continue; a mismatch stops it.

The session commands differ by tool; the loop does not.

Claude Code

Meter: status line context_window.used_percentage, or /context. Boundary: /compact [focus], /clear [name], /fork, /branch, /resume. Compact earlier with /autocompact 500k (100K to 1M) or CLAUDE_AUTOCOMPACT_PCT_OVERRIDE, which can only lower the threshold. Session cost: /usage.

Codex

Meter: the context-usage item in the footer (configure it with /statusline), and /status for token usage. Boundary: /compact, /new, /fork, /resume; from the shell, codex resume --last and codex fork --last. Skills are invoked as $handoff, $caveman.

Cursor

Start a new Agent chat at each phase boundary and point it at the handoff and plan files. Cursor’s context indicator and summarisation behaviour could not be verified from cursor.com on 2026-09-26, so this page gives no Cursor threshold.

Where Agent Skills for Context Engineering fits

The context-engineering collection is for the tech lead who designs the harness: subagent layouts, memory, tool descriptions, and evals. context-degradation names five failure patterns (lost-in-middle, poisoning, distraction, confusion, and clash). context-compression argues for optimising tokens per task, including the cost of re-fetching what a summary dropped, rather than tokens per request. Each fired skill is large (about 18–19 KB of SKILL.md), so install two or three by name, not the collection.

Copy-paste prompt: diagnose an agent that forgets its rules

Use the context-degradation skill. In our Claude Code sessions on this repository,
the agent stops following the "never edit tests to make them pass" rule from
CLAUDE.md after roughly 40 turns. Read CLAUDE.md, .claude/settings.json and the
skills in .claude/skills/. Map the symptom to the degradation patterns the skill
describes, rank the likely causes, and propose one change per cause with a way to
check it worked. Do not edit files yet.

How do you prove the resumed work is still correct?

A shorter conversation is not evidence. These skills change how the agent talks and what it carries; the proof stays outside the agent.

• The handoff is checked against the repository. Every “Verified” line maps to a commit and a passing test. The audit prompt above downgrades the rest before /clear, and the resume prompt re-runs the tests before any edit.
• CI is the gate. caveman never rewrites code blocks, and karpathy-guidelines only shapes the diff. The pull request still passes typecheck, lint, and tests, and ships an evidence bundle a reviewer checks without rereading the diff.
• Savings are measured on your work. The token-saving figures in the caveman README are the author’s and third parties’ as the README reports them; this page did not verify them. The README itself says agentic sessions save far less than chat, because most tokens are code and tool calls the skill never touches. Compare /usage and /context on similar tasks with and without the skill before you standardise it.
• karpathy-guidelines shows up in the diff. Track files changed and lines changed per pull request before and after adoption. The README’s own signals are fewer unrequested changes and clarifying questions asked before implementation, not after mistakes.

Who signs off. The developer who writes the handoff audits it before clearing the session. The reviewer approves the pull request on green CI and the evidence bundle. The tech lead owns the committed skill set and changes it through review.

What do context and token skills cost in context?

A skill’s name and description load into every session; the body loads when the skill fires. Sizes of SKILL.md on main, 2026-09-26:

What loads	When	Size
handoff	When you type /handoff	894 bytes
caveman	When activated, then it stays in the conversation	7,061 bytes
caveman-compress	When you compress a file	4,697 bytes
karpathy-guidelines	When the agent writes, reviews, or refactors code	2,518 bytes
context-degradation / context-compression	When the skill fires	19,180 / 18,214 bytes
mattpocock-skills plugin (25 skills)	Every session	about 1,609 tokens (claude plugin details, Claude Code 2.1.283)
planning-with-files plugin	Every session	about 1,124 tokens (same measurement)

At roughly four bytes per token, caveman costs about 1,800 tokens of input once it is active. It pays back only when the prose it removes exceeds that, which is why it suits long, chatty sessions and not short, code-heavy ones.

What breaks when you use context and token skills?

The handoff vanished. The temp directory was cleared between sessions or by a reboot. Recovery: copy the file into .handoffs/ as soon as it is written (step 4), and ask the agent for the absolute path every time.

The new session trusts a false “done”. The handoff recorded an assumption as a fact, and the next agent built on it. Recovery: run the audit prompt before /clear; in the resume prompt, require the test run and a stop on any mismatch.

caveman makes the answers unclear. At ultra, the order of steps in a multi-step instruction can blur. The skill tells the model to return to full sentences for security warnings, irreversible actions, and ambiguous multi-step sequences, but the model decides when a sequence counts as ambiguous. Recovery: use /caveman lite, or say stop caveman for design discussions and anything a human reads later.

A compressed CLAUDE.md lost a rule. caveman-compress keeps headings, code, paths, and commands, but rewrites the prose around them, and its backup lives outside the repository under $XDG_DATA_HOME/caveman-compress/backups/. Recovery: review the git diff before you commit, and restore from git, not from the backup folder.

Skills overlap and argue. caveman’s surgical-patch and karpathy-guidelines both govern edit scope; two procedures on one trigger make the agent drift between them. Recovery: keep one skill per concern and remove the other with npx skills remove.

Context still fills up fast. The skills address prose and session boundaries, not the big consumers: MCP tool schemas, large file reads, and long command output. Recovery: check /context, prune MCP servers and memory files as described in managing context windows, and delegate noisy searches to subagents.

Where to go next with context and token discipline

Managing context windows What fills the window, what survives compaction, and how to keep it lean in each tool.

Persistent memory plugins claude-mem, planning-with-files, and MCP memory servers for work that spans days.

Cost per context Turn context size into money, and decide where trimming pays.

Memory patterns Which facts belong in CLAUDE.md or AGENTS.md, and which belong in a handoff.

Installing and managing skills The skills CLI, plugins, pinning, and team-wide updates.

Agentic development frameworks Where karpathy-guidelines sits next to Superpowers, Spec Kit, and the other methods.