caveman-learn

Applies consent-gated fixes to reduce an agent's token costs from Caveman learn reports.

1|Updated Apr 23, 2026
One-click install
npx skills add https://github.com/tkogut/agents-os-core --skill caveman-learn-tkogut
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: caveman-learn
Source: https://github.com/tkogut/agents-os-core/tree/main/vault/.agents/skills/caveman-learn
Command: npx skills add https://github.com/tkogut/agents-os-core --skill caveman-learn-tkogut

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? AI agents accumulate token waste through heavy CLAUDE.md files, never-invoked skills, and context that users re-paste every session. The caveman learn command measures where tokens go, but acting on its findings requires careful, reversible edits — this Skill closes that loop by proposing each fix and applying it only with explicit per-edit user consent. ## Core Features & Use Cases - Consent-gated cost reduction: Reviews ranked token sinks from caveman learn report --json, proposes concrete trims for reducible sinks, and applies edits only after a yes, with a net-token-negative re-measure gate that reverts any edit failing to reduce tokens per turn. - Context offloading to cavemem: Moves recurring context blocks into cavemem storage with a cheap pointer left behind, verifying content integrity via SHA-256 and confirming recall works before trimming the source. - Honest savings reporting: Presents measured outcomes grouped by evidence strength (deterministic re-measure, controlled holdout, counterfactual replay, interrupted time series) without summing across rungs or projecting savings forward. - Use Case: Your agent's CLAUDE.md has grown to thousands of tokens and you re-paste the same project conventions every session. Run the Skill to review the Cave Score, trim dead weight, offload recurring context to cavemem, and track whether each fix actually improved token usage over time. ## Quick Start Ask the agent to run the caveman learn report and walk you through fixing the top token sinks one approved edit at a time.

Frequently Asked Questions about caveman-learn

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I reduce my AI agent's token costs?▼

Run caveman learn report --json to get a Cave Score and ranked token sinks, then use this Skill to review each sink. It proposes concrete fixes like trimming heavy CLAUDE.md sections or offloading re-pasted context to cavemem, applying each only with your approval and re-measuring to confirm the reduction.

How to offload recurring context from CLAUDE.md to cavemem?▼

The Skill verifies the block via SHA-256 against the scan locator, stores it with caveman mem remember, and measures whether pointer plus recall cost beats the original tokens per turn. Only after a confirming recall succeeds does it trim the source and write the pointer text.

Does caveman learn edit my config files automatically?▼

No. The caveman learn analyzer is strictly read-only and only materializes candidates. This Skill is the only writer, and it applies each edit solely after you explicitly approve the individual diff — there is no apply-all mode.

What happens if a token-saving edit makes things worse?▼

Every edit passes a net-token-negative gate: if the re-measured tokens per turn are not lower than before, the edit is reverted automatically. Longitudinal verdicts of regressed are reported honestly with the exact revert path offered.

When should I not distill a repeated procedure into a skill?▼

Skill distillation is never applied through the standard re-measure gate because a skill loads every session but pays back only on matching sessions. It requires a controlled holdout experiment with at least 5 sessions per arm before any verdict, and a regressed verdict means deleting the skill.