How to use the Caveman Learn Editor agent skill

What is an agent skill, and what does caveman-learn make the agent do?

An agent skill is a folder with a SKILL.md file that an agent such as Claude Code loads when a request matches the skill's description. The skill tells the agent how to carry out a specific task.

caveman-learn does not measure anything itself. The caveman learn command measures where tokens go and writes a ranked plan. The skill is the second half: it walks through that plan with you and turns findings into edits, one approved change at a time. After a change it re-measures and reverts the change if tokens per turn did not actually go down.

• Shows the Cave Score, its four components, and the ranked token sinks (the parts of context that cost the most).
• Proposes a concrete fix, such as trimming a heavy CLAUDE.md or moving repeated context into cavemem.
• Asks yes or no before each edit.
• Re-measures after an edit and reverts it if tokens per turn did not drop.

Install the caveman-learn skill

You can install the skill in one of two ways. The first is to download the ZIP from this page and unzip it into a skills folder. Use ~/.claude/skills/ to make it available to all of your projects, or a project's .claude/skills/ folder to limit it to one repository.

The second is to upload the ZIP in the Claude apps. Open Settings, go to Capabilities, then Skills, and upload the file there.

• Personal install: unzip into ~/.claude/skills/ so the caveman-learn folder sits inside it.
• Project install: unzip into the project's .claude/skills/ folder.
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP.
• Start a new agent session after installing so the skill is picked up.

Install the caveman CLI before you use the skill

The skill depends on the caveman command-line tool. It calls caveman learn and caveman mem subcommands, and it will not work without them. The source also lists a caveman tools skills install route and a caveman skills install route in the project's documentation; check the README for the form that matches your setup.

Offload fixes also need a cavemem memory store. Without it, the skill can still propose trims to a CLAUDE.md, but it cannot move repeated context into memory.

• caveman CLI with learn and mem subcommands.
• cavemem memory store, required only for offload fixes.
• Agent file tools that can edit CLAUDE.md and write temp files.

Trigger the skill with natural requests

You do not need a special command to use the skill. Ask for what you want in plain language and the agent will load it when the request matches the skill's description. The description names these triggers: asking to lower an agent's token cost, asking what caveman has saved, asking to trim a heavy CLAUDE.md, or asking to offload re-pasted context into cavemem.

• "Lower my agent's token cost."
• "What has caveman saved so far?"
• "My CLAUDE.md is huge. Trim it."
• "I keep pasting the same context every session. Move it into cavemem."

What a typical session looks like

The agent first runs caveman learn report --json and shows you the findings. It states each sink's class and basis. Behavioral findings are presented as observations with a soft suggestion, not as orders.

For each sink you choose to act on, the agent prepares a candidate with a dry run and shows a before and after figure in tokens per turn. It edits a file only after you say yes, then checks the reduction. If the after figure is not lower than the before figure, it reverts and reports that.

• Spend figures show what the scanned window cost. They are not what a fix would return, and they are not projected into a month or year.
• Cache efficiency is a rate used to price other sinks, not a volume of tokens to add up.
• Session outcomes are correlational. A session without a commit is not automatically a wasted session.

Safety notes: scripts and network

The skill runs scripts. It also writes files: it edits CLAUDE.md or AGENTS.md when you approve a change, and for offload fixes it writes the block to a temp file and deletes that file once the memory id is returned. Each edit needs your yes.

The skill does not use the network, according to its listing. Memory content is never deleted without your yes. When offloading, the skill passes block text to the memory store through standard input, not on the command line, so shell characters in the text are not interpreted.

• Runs scripts: yes.
• Uses network: no.
• Edits to memory or rules files need your explicit approval for each one.
• If the source text changed since the scan, the skill aborts that item instead of guessing.