CLAUDE.md

1# skills/caveman-learn — the Caveman Learn editing skill (MIT, public)
2 
3The consent-gated half of `caveman learn`. The analyzer (the Go proxy) **measures**
4where an agent's tokens go and writes a ranked plan; this skill is what an agent
5loads to **act** on that plan — proposing each fix and applying it only with the
6user's per-edit yes. It is the loop-closer the learn spec §10
7describes, plus the new `cavemem_offload` move.
8 
9## Layout
10- `SKILL.md` — the canonical skill body (frontmatter `name: caveman-learn` + a
11  trigger-phrase `description`; body = the read-plan → per-class consent loop). This
12  file is the source of truth.
13- `tests/skill-file.test.mjs` — asserts the canonical file is well-formed and honest
14  (frontmatter present; the net-token-negative gate, the never-make-the-agent-dumber
15  guard, consent-per-edit, and reversibility are all stated; no imperative for
16  behavioral findings; no placeholders).
17 
18## Install path
19`caveman tools skills install caveman-learn` (in `../../cli/src/index.ts`) writes this file
20into a repo's `.claude/skills/caveman-learn/SKILL.md` (Claude Code) or
21`~/.codex/skills/caveman-learn/SKILL.md` (Codex). The CLI **embeds a byte-identical copy**
22(`CAVEMAN_LEARN_SKILL_MD`) because the published CLI ships no sibling assets;
23`../../cli/tests/skills.runtime.mjs` asserts the embedded copy equals this canonical
24file (the drift guard). **Change this file and that constant together.**
25 
26## Boundary (binding)
27The skill — using the agent's own file tools — is the ONLY thing that edits a user's
28config. `caveman learn apply` stays read-only (it materializes candidates), and
29`caveman mem *` are mechanical store ops. The offload move enforces a net-token-negative
30gate and the never-make-the-agent-dumber guard before any trim.
31 
32See ../../mem/CLAUDE.md (cavemem) · ../caveman-explore/SKILL.md (the packaging precedent)
33