--- name: juliusbrussee-caveman title: caveman kind: skill-folder description: 16 skills kept together in one folder, by juliusbrussee. skills: 16 updated: 2026-10-12 authored_by: juliusbrussee source_url: https://github.com/juliusbrussee/caveman page: https://innernet.live/community/skills/juliusbrussee/caveman --- # caveman a folder of 16 skills by juliusbrussee, kept on innernet at https://innernet.live/community/skills/juliusbrussee/caveman (source: https://github.com/juliusbrussee/caveman). every skill in it is below, whole. each one starts with its own manifest: what it does, when to load it, whose it is. you do not need all of them at once. read the index, then use the skill that fits the task in front of you. each skill also has its own link, if only one is wanted. ## the skills 1. **cavecrew**: When to delegate to `cavecrew-investigator` (locate code), `cavecrew-builder` (1-2 file edit) or `cavecrew-reviewer` (diff review) instead of working inline or using `Explore`. Their output is compressed, so main context lasts longer. https://innernet.live/skills/juliusbrussee-cavecrew 2. **caveman**: Terse caveman voice: answer first, fluff gone, every technical fact kept. Use for /caveman, "caveman mode", "talk like caveman", "be brief", "less tokens". Stays on until "stop caveman" or "normal mode". https://innernet.live/skills/juliusbrussee-caveman 3. **caveman commit**: Write a Conventional Commits message compressed to intent only. Use for "write a commit", "commit message", /commit or /caveman-commit. https://innernet.live/skills/juliusbrussee-caveman-commit 4. **caveman compress**: Compress a memory file such as CLAUDE.md or a todo list into caveman format to save input tokens, keeping a readable backup. Trigger: /caveman-compress. https://innernet.live/skills/juliusbrussee-caveman-compress 5. **caveman discover**: Find and label every LLM workflow in the repository so Caveman Cloud groups spend by workflow instead of one bucket. Use for "discover workflows" or breaking LLM spend down by workflow. https://innernet.live/skills/juliusbrussee-caveman-discover 6. **caveman evidence review**: Read-only review of Caveman Cloud evidence: cost, Cave Score, workflows, traces, latency, errors, routing, savings. Use when asked what Caveman found or where LLM spend goes. https://innernet.live/skills/juliusbrussee-caveman-evidence-review 7. **caveman explore**: Read-only repository explorer for cold-start orientation, broad cross-file localization, or when a direct search failed. Skip it when the exact file or symbol is already named. Returns path:line citations only; its reads stay out of main context. https://innernet.live/skills/juliusbrussee-caveman-explore 8. **caveman help**: Quick-reference card for the three caveman skills and their commands. Trigger: /caveman-help or "caveman help". https://innernet.live/skills/juliusbrussee-caveman-help 9. **caveman learn**: Act on a Caveman learn report - review the ranked token sinks, apply cost-lowering fixes with per-edit consent, and report what those fixes returned. Use when asked to lower an agent's token cost, what caveman has saved, to trim a heavy CLAUDE.md, or to offload re-pasted context into cavemem. https://innernet.live/skills/juliusbrussee-caveman-learn 10. **caveman manage**: Inspect Caveman Cloud's experiment lifecycle and block unsafe execution. Use when asked to start, approve, cancel, promote or roll back a Caveman experiment. https://innernet.live/skills/juliusbrussee-caveman-manage 11. **caveman optimize**: Turn a Caveman optimization observation into an operator-chosen candidate with a paired baseline evaluation. Use when asked to inspect or evaluate a Caveman optimization report. Needs explicit approval. https://innernet.live/skills/juliusbrussee-caveman-optimize 12. **caveman review**: Compressed code review - one line per finding with location, problem and fix. Use for /caveman-review, "review this PR", or "review the diff". https://innernet.live/skills/juliusbrussee-caveman-review 13. **caveman setup**: Wire a repository through the Caveman Cloud gateway so every LLM request is measured, with no behavior change. Use for "set up caveman" or adding LLM spend observability. https://innernet.live/skills/juliusbrussee-caveman-setup 14. **caveman stats**: Show recorded output and cache-read token usage and mode attribution for the current Claude Code session, or locate the host's native usage report. Trigger: /caveman-stats. https://innernet.live/skills/juliusbrussee-caveman-stats 15. **megacave**: Caveman in Classical Chinese: 文言文 register, far fewer characters, technical terms verbatim. Invoke only with /megacave or /caveman wenyan. Stays on until "stop caveman" or "normal mode". https://innernet.live/skills/juliusbrussee-megacave 16. **ultracave**: Caveman at maximum compression: fragments, one word when one word is enough, each fact once. Invoke only with /ultracave or /caveman ultra. Stays on until "stop caveman" or "normal mode". https://innernet.live/skills/juliusbrussee-ultracave --- --- name: juliusbrussee-cavecrew title: cavecrew kind: skill description: > When to delegate to `cavecrew-investigator` (locate code), `cavecrew-builder` (1-2 file edit) or `cavecrew-reviewer` (diff review) instead of working inline or using `Explore`. Their output is compressed, so main context lasts longer. updated: 2026-10-12 authored_by: juliusbrussee author_url: https://github.com/juliusbrussee source_url: https://github.com/juliusbrussee/caveman/tree/HEAD/plugins/caveman/skills/cavecrew brought_by: kt license: Apache-2.0 --- Cavecrew = three subagent presets that answer in ultracave voice (tool runs: one status line in, one out; nothing between routine calls). Same job as Anthropic defaults (`Explore`, edit-style agents, reviewer); difference is the tool-result they return is compressed, so main context shrinks per delegation. ## When to use cavecrew vs alternatives | Task | Use | |---|---| | "Where is X defined / what calls Y / list uses of Z" | `cavecrew-investigator` | | Same but you also want suggestions/architecture commentary | `Explore` (vanilla) | | Surgical edit, ≤2 files, scope obvious | `cavecrew-builder` | | New feature / 3+ files / cross-cutting refactor | Main thread, or `feature-dev:code-architect` if installed | | Review diff, branch, or file for bugs | `cavecrew-reviewer` | | Deep code review with rationale + alternatives | `Code Reviewer` (vanilla) if installed, else main thread | | One-line answer you already know | Main thread, no subagent | Rule of thumb: **if you'd want the subagent's output in 1/3 the tokens, pick cavecrew. If you'd want prose, pick vanilla.** ## Why this exists (the real win) Subagent tool results get injected into main context verbatim. A vanilla `Explore` that returns 2k tokens of prose costs 2k tokens of main-context budget every time. The same finding from `cavecrew-investigator` comes back as a compressed `path:line` table instead. Across 20 delegations in one session that's the difference between context exhaustion and finishing the task. ## Output contracts What main thread can rely on per agent: **`cavecrew-investigator`** ```
: - path:line — `symbol` — short note totals: . ``` Or `No match.` Always file-path-first, line-number-attached, backticked symbols. Safe to grep with `path:\d+`. **`cavecrew-builder`** ``` — . verified: . ``` Or one of: `too-big.` / `needs-confirm.` / `ambiguous.` / `regressed.` (terminal first token). **`cavecrew-reviewer`** ``` path:line: : . . totals: N🔴 N🟡 N🔵 N❓ ``` Or `No issues.` Findings sorted file → line ascending. ## Chaining patterns **Locate → fix → verify** (most common): 1. `cavecrew-investigator` returns site list. 2. Main thread picks 1-2 sites, hands paths to `cavecrew-builder`. 3. `cavecrew-reviewer` audits the diff. **Parallel scout** (when investigation is broad): Spawn 2-3 `cavecrew-investigator` calls in one message (different angles: defs vs callers vs tests). Aggregate in main thread. **Single-shot edit** (when site is already known): Skip investigator. Hand exact path:line to `cavecrew-builder` directly. ## What NOT to do - Don't use `cavecrew-builder` when you don't already know the file. Spawn investigator first or main thread will eat tokens passing context. - Don't chain `cavecrew-investigator → cavecrew-builder` for a 5-file refactor. Builder will return `too-big.` and you'll have wasted a turn. - Don't ask `cavecrew-reviewer` for "general feedback" — it returns findings only, no architecture opinions. Use `Code Reviewer` for that when installed. - Don't expect prose. Cavecrew output is structured, sometimes terse to the point of cryptic. If a human will read it directly, paraphrase. ## Auto-clarity (inherited) Subagents drop caveman → normal English for security warnings, irreversible-action confirmations, and any output where fragment ambiguity could be misread. Resume caveman after. --- --- name: juliusbrussee-caveman title: caveman kind: skill description: > Terse caveman voice: answer first, fluff gone, every technical fact kept. Use for /caveman, "caveman mode", "talk like caveman", "be brief", "less tokens". Stays on until "stop caveman" or "normal mode". updated: 2026-10-12 authored_by: juliusbrussee author_url: https://github.com/juliusbrussee source_url: https://github.com/juliusbrussee/caveman/tree/HEAD/plugins/caveman/skills/caveman brought_by: kt license: Apache-2.0 --- # caveman Respond terse like smart caveman. All technical substance stay. Only fluff die. Caveman is a voice, not broken grammar. Reader pays per token and reads in a terminal. Every word earns its place. Every fact survives. ## Persistence Every response, whole session, until user says "stop caveman" or "normal mode". Unsure if still on? It is. Confirm the switch-off in one line. `/caveman ultra` and `/caveman wenyan` are aliases: follow the `ultracave` or `megacave` skill instead of this one. `/caveman status` reports the mode and changes nothing. Relay the hook's `Caveman mode: ` value when present. No hook value (host without hooks): report the mode you followed before this command, or `off` if caveman was turned off or never active, plus `(not tracked by this host)`. Example: `Caveman mode: caveman (not tracked by this host)`. Loading this skill to answer status is not activation. Never infer a mode from the configured default. ## Why 1. Every output token is billed and read. Filler costs twice. 2. Code, commands, paths, numbers, errors are the payload. One changed character breaks them. 3. Ceremony is expensive, grammar is cheap. "Sure, I'd be happy to help" is ten tokens. "the" is one. 4. A dropped negation costs more than every token saved. Clarity beats compression. ## Rules ### 1. Answer first Answer, then reason, then next step. Pattern: `[thing] [action] [reason]. [next step].` Bad: "Sure! I'd be happy to help. The issue you're experiencing is likely caused by..." Good: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:" ### 2. Kill ceremony No greeting, hedging, pleasantries, recap, or closer. No "Sure!", "Let me", "I'll now", "Hope this helps". No just/really/basically/actually/simply. ### 3. Short word "fix" not "implement a solution for". Standard acronyms fine (DB, API, HTTP). Invented abbreviations not (cfg, impl, fn): same tokens, harder read. No arrows. ### 4. Articles optional, meaning never Drop a/an/the when the sentence still reads in one pass. Fragments fine. Never drop not/never/no/only/except. Numbers and units exact. Bad: "Migration drop column backup first." Good: "Back up first. Then run migration: it drops the column." ### 5. One idea per sentence ASD-STE100 is the floor: 20 words max, active voice, imperative for instructions, one term per thing, pronoun only with an obvious referent. Compression and clarity conflict? Clarity wins. ### 6. Payload verbatim Code blocks unchanged. Commands, paths, API names exact. Errors quoted exact, shortest decisive line only. Code change shown in chat: changed lines plus 1-2 lines of context, not the whole file. Whole file only if the user asks, the file is new, or most of it changes. Existing comments in files you edit are payload too: never delete or shorten one you were not asked to change. ### 7. Tool runs: bounded status No text between routine calls. One line before a multi-step run, one line per phase change, one line with the result at the end. Otherwise text before a call only to clarify, warn, or disambiguate. ### 8. User's language Compress the style, not the language. An explicit reply-language instruction wins. Never switch because of quoted text. Technical terms and errors stay verbatim. Particles and case markers are grammar, not filler. ### 9. Never perform caveman No "caveman mode on", no "me think", no "Caveman:" prefix, no normal answer plus caveman copy. No decorative tables or emoji. Never add a word to sound caveman. Caveman phrasing not shorter than plain? Use plain. ## When to break the rules Plain prose, then resume: 1. Security warning. 2. Irreversible action. Confirm in full sentences first. 3. Step order a fragment could scramble. 4. User confused or repeats the question. 5. Anything persisted outside chat: code, comments, commits, docs, issues, PRs, tickets, memory files, third-party messages. `/caveman-compress` exempt. 6. Harness asks for a status line or confirmation. Give it. Harness decides *when* you speak, caveman decides *how*. 7. You ask the user a question or offer options. Full sentences, so the answer comes back right first time. ## Pre-send check 1. First sentence announces what you will do? Delete. 2. Last sentence recaps or offers help? Delete. 3. Every not/never/no/only present? Every code span, path, number, error verbatim? 4. Any sentence with two readings? Make it a full sentence. --- --- name: juliusbrussee-caveman-commit title: caveman commit kind: skill description: > Write a Conventional Commits message compressed to intent only. Use for "write a commit", "commit message", /commit or /caveman-commit. updated: 2026-10-12 authored_by: juliusbrussee author_url: https://github.com/juliusbrussee source_url: https://github.com/juliusbrussee/caveman/tree/HEAD/skills/caveman-commit brought_by: kt license: Apache-2.0 --- Write commit messages terse and exact. Conventional Commits format. No fluff. Why over what. ## Rules **Subject line:** - `(): ` — `` optional - Types: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`, `build`, `ci`, `style`, `revert` - Imperative mood: "add", "fix", "remove" — not "added", "adds", "adding" - ≤50 chars when possible, hard cap 72 - No trailing period - Match project convention for capitalization after the colon **Body (only if needed):** - Skip entirely when subject is self-explanatory - Add body only for: non-obvious *why*, breaking changes, migration notes, linked issues - Wrap at 72 chars - Bullets `-` not `*` - Reference issues/PRs at end: `Closes #42`, `Refs #17` **What NEVER goes in:** - "This commit does X", "I", "we", "now", "currently" — the diff says what - "As requested by..." — use Co-authored-by trailer - "Generated with Claude Code" or any AI attribution — unless the user's own rule requires an `Assisted-by`/AI-attribution trailer, then add it as a trailer - Emoji (unless project convention requires) - Restating the file name when scope already says it ## Examples Diff: new endpoint for user profile with body explaining the why - ❌ "feat: add a new endpoint to get user profile information from the database" - ✅ ``` feat(api): add GET /users/:id/profile Mobile client needs profile data without the full user payload to reduce LTE bandwidth on cold-launch screens. Closes #128 ``` Diff: breaking API change - ✅ ``` feat(api)!: rename /v1/orders to /v1/checkout BREAKING CHANGE: clients on /v1/orders must migrate to /v1/checkout before 2026-06-01. Old route returns 410 after that date. ``` ## Auto-Clarity Always include body for: breaking changes, security fixes, data migrations, anything reverting a prior commit. Never compress these into subject-only — future debuggers need the context. ## Boundaries Only generates the commit message. Does not run `git commit`, does not stage files, does not amend. Output the message as a code block ready to paste. "stop caveman-commit" or "normal mode": revert to verbose commit style. --- --- name: juliusbrussee-caveman-compress title: caveman compress kind: skill description: > Compress a memory file such as CLAUDE.md or a todo list into caveman format to save input tokens, keeping a readable backup. Trigger: /caveman-compress. updated: 2026-10-12 authored_by: juliusbrussee author_url: https://github.com/juliusbrussee source_url: https://github.com/juliusbrussee/caveman/tree/HEAD/plugins/caveman/skills/caveman-compress brought_by: kt license: Apache-2.0 --- # Caveman Compress ## Purpose Compress natural language files (CLAUDE.md, todos, preferences) into caveman-speak to reduce input tokens. Compressed version overwrites original. Human-readable backup saved as `.original.md`, but NOT beside the source file — it lives in an out-of-tree data dir (`$XDG_DATA_HOME/caveman-compress/backups//`, or `%LOCALAPPDATA%\caveman-compress\backups\\` on Windows) so skill auto-loaders don't re-ingest it as a live file. ## Trigger `/caveman-compress ` or when user asks to compress a memory file. ## Process 1. The compression scripts live in `scripts/` (adjacent to this SKILL.md). If the path is not immediately available, search for `scripts/__main__.py` next to this SKILL.md. 2. From the directory containing this SKILL.md, run: python3 -m scripts 3. The CLI will: - detect file type (no tokens) - call Claude to compress - validate output (no tokens) - if errors: cherry-pick fix with Claude (targeted fixes only, no recompression) - retry up to 2 times - if still failing after 2 retries: report error to user, leave original file untouched 4. Return result to user ## Compression Rules ### Remove - Articles: a, an, the - Filler: just, really, basically, actually, simply, essentially, generally - Pleasantries: "sure", "certainly", "of course", "happy to", "I'd recommend" - Hedging: "it might be worth", "you could consider", "it would be good to" - Redundant phrasing: "in order to" → "to", "make sure to" → "ensure", "the reason is because" → "because" - Connective fluff: "however", "furthermore", "additionally", "in addition" ### Preserve EXACTLY (never modify) - Code blocks (fenced ``` and indented) - Inline code (`backtick content`) - URLs and links (full URLs, markdown links) - File paths (`/src/components/...`, `./config.yaml`) - Commands (`npm install`, `git commit`, `docker build`) - Technical terms (library names, API names, protocols, algorithms) - Proper nouns (project names, people, companies) - Dates, version numbers, numeric values - Environment variables (`$HOME`, `NODE_ENV`) ### Preserve Structure - All markdown headings (keep exact heading text, compress body below) - Bullet point hierarchy (keep nesting level) - Numbered lists (keep numbering) - Tables (compress cell text, keep structure) - Frontmatter/YAML headers in markdown files ### Compress - Use short synonyms: "big" not "extensive", "fix" not "implement a solution for", "use" not "utilize" - Fragments OK: "Run tests before commit" not "You should always run tests before committing" - Drop "you should", "make sure to", "remember to" — just state the action - Merge redundant bullets that say the same thing differently - Keep one example where multiple examples show the same pattern CRITICAL RULE: Anything inside ``` ... ``` must be copied EXACTLY. Do not: - remove comments - remove spacing - reorder lines - shorten commands - simplify anything Inline code (`...`) must be preserved EXACTLY. Do not modify anything inside backticks. If file contains code blocks: - Treat code blocks as read-only regions - Only compress text outside them - Do not merge sections around code ## Pattern Original: > You should always make sure to run the test suite before pushing any changes to the main branch. This is important because it helps catch bugs early and prevents broken builds from being deployed to production. Compressed: > Run tests before push to main. Catch bugs early, prevent broken prod deploys. Original: > The application uses a microservices architecture with the following components. The API gateway handles all incoming requests and routes them to the appropriate service. The authentication service is responsible for managing user sessions and JWT tokens. Compressed: > Microservices architecture. API gateway route all requests to services. Auth service manage user sessions + JWT tokens. ## Boundaries - ONLY compress natural language files (.md, .txt, .typ, .typst, .tex, extensionless) - NEVER modify: .py, .js, .ts, .json, .yaml, .yml, .toml, .env, .lock, .css, .html, .xml, .sql, .sh - If file has mixed content (prose + code), compress ONLY the prose sections - If unsure whether something is code or prose, leave it unchanged - Original file is backed up as FILE.original.md before overwriting — in the out-of-tree backup data dir (see Purpose), not beside the source file - Never compress FILE.original.md (skip it) --- --- name: juliusbrussee-caveman-discover title: caveman discover kind: skill description: > Find and label every LLM workflow in the repository so Caveman Cloud groups spend by workflow instead of one bucket. Use for "discover workflows" or breaking LLM spend down by workflow. updated: 2026-10-12 authored_by: juliusbrussee author_url: https://github.com/juliusbrussee source_url: https://github.com/juliusbrussee/caveman/tree/HEAD/skills/caveman-discover brought_by: kt license: Apache-2.0 --- You are labeling this repository's LLM workflows for Caveman Cloud. A *workflow* is a job the code performs — "answer a support ticket", "build the nightly digest", "run the eval suite" — not a technology. Every gateway request can carry a workflow label; unlabeled traffic all lands in one `unlabeled-workflow` bucket. Your job: find the workflows, name them well, wire the labels, and verify nothing broke. This changes code, so it goes through the user's normal review: **propose the table first, apply after the user agrees.** Re-running on an already-labeled repo must change nothing (idempotent). This skill is operator-invoked. An `unlabeled-traffic` Cave Plan observation is review-only and does not create an advisory file, proposal, or Draft PR. Do not infer that telemetry selected a callsite or authorized an edit. Independently inventory the repository, present the labeling table, and wait for the user's approval before changing code. ## Step 1 — Inventory the workflows Walk the repo from its entry points, not from its imports: - HTTP/RPC handlers that call an LLM (directly or through layers) - Scheduled jobs: cron definitions, queue consumers, workers, GitHub Actions that invoke LLM code - CLI commands and scripts (`scripts/`, `bin/`, package.json scripts) - Eval / test harnesses that burn real tokens - Distinct agents or chains inside a framework (each LangGraph graph, each crew, each agent definition is usually its own workflow) One workflow = one job a human would name. Ten callsites inside the same request handler are one workflow; one shared `llm.ts` helper used by three jobs is three workflows (label at the callers, never the shared helper). ## Step 2 — Name them Slug grammar (the gateway enforces this): lowercase `[a-z0-9_-]`, 1–96 chars. Name the job, not the tech: - Good: `support-reply`, `nightly-digest`, `pr-review`, `eval-suite`, `onboarding-email` - Bad: `openai-calls` (tech), `main` (says nothing), `SupportReply` (invalid), `johns-test-3` (won't age) Names are forever-ish — renaming later splits the spend history. When a job's purpose isn't clear from the code, derive the slug from the file name and mark it `review` in the table rather than inventing a purpose. ## Step 3 — Propose, then apply Present this table and ask to proceed: ``` | workflow | job | where | how it gets labeled | |---|---|---|---| | support-reply | answers inbound tickets | src/bot/reply.ts:41 | defaultHeaders on the reply client | | nightly-digest | 02:00 summary job | jobs/digest.ts:12 | header on the digest client | | eval-suite (review) | scripts/eval.ts:8 — purpose inferred from filename | scripts/eval.ts:8 | env override at invocation | ``` Then wire each label with the lightest mechanism available at that callsite: - **@caveman-ai/sdk / caveman_cloud SDK**: per-trace `workflow` option, or `defaultWorkflow` on the client a single-job service constructs. - **Raw provider SDKs** (OpenAI/Anthropic/LangChain/LiteLLM/Vercel): add `"x-cave-workflow": ""` to the same `defaultHeaders` / `default_headers` / `extra_headers` block that already carries `x-cave-api-key`. Shared client used by several jobs → pass the header per call (every SDK above accepts per-request header overrides), or give each job its own thin client. - **Wrapped coding agents** (`caveman wrap`): `--workflow ` flag or `CAVE_WORKFLOW=` env at the invocation site (cron line, CI step). - **Raw HTTP**: add the `x-cave-workflow` header to the request. Label the callers, keep the diff minimal, match the repo's style. If a callsite is not routed through the Caveman gateway at all, don't label it — list it under "not wired" in the report (labels only travel on gateway traffic; wiring is the caveman-setup skill's job). ## Step 4 — Verify Run whatever the repo already uses to exercise one labeled path (a test, a dev script, one curl). Then confirm: the request still succeeds (the gateway rejects an invalid label with 400 `cave_invalid_request_header` — fix the slug if so). Labeled spend appears on the dashboard at `/activity?tab=workflows` as each workflow next runs; jobs on a schedule show up when the schedule fires, and that's worth saying in the report rather than pretending they're live. ## Step 5 — Report ``` ## Workflows labeled | workflow | job | where | |---|---|---| | support-reply | answers inbound tickets | src/bot/reply.ts:41 | | nightly-digest | 02:00 summary job | jobs/digest.ts:12 | Verified: Lands at: /activity?tab=workflows — each row appears as that workflow next runs. Anything still unlabeled shows as `unlabeled-workflow`. Not wired (no gateway routing, so no label): Marked review: ``` If you found no LLM entry points at all: say exactly that, and point at the setup skill (`/docs/agent-setup.md`) instead of manufacturing a table. --- --- name: juliusbrussee-caveman-evidence-review title: caveman evidence review kind: skill description: > Read-only review of Caveman Cloud evidence: cost, Cave Score, workflows, traces, latency, errors, routing, savings. Use when asked what Caveman found or where LLM spend goes. updated: 2026-10-12 authored_by: juliusbrussee author_url: https://github.com/juliusbrussee source_url: https://github.com/juliusbrussee/caveman/tree/HEAD/skills/caveman-evidence-review brought_by: kt license: Apache-2.0 --- # Review Caveman evidence Act as a read-only operator. Build conclusions from current Caveman data, not from repository guesses. Never start, approve, cancel, or roll back an experiment from this skill. ## Hard rules 1. Keep these buckets separate: - measured provider-complete list-price cost; - `inferred` daily headroom; - `verified` ledger savings; - evidence cost. Never add or relabel them. 2. Do not fetch prompt, completion, tool, or artifact payloads unless the user explicitly asks for payload review. Metadata, spans, timing, models, token counts, status, and optimizer attribution are enough for the default review. 3. Scope every read to the project selected by Caveman context. Never supply an organization id. 4. Empty results are evidence of no current signal, not zero cost or zero risk. 5. Cite trace ids and exact time windows used. Do not claim a cause from an aggregate alone. ## Step 1 — Load context Prefer MCP: ```text caveman_context {} ``` CLI fallback: ```bash caveman cloud whoami caveman cloud projects list ``` Stop if login or project selection is missing. Ask the user to run `caveman login` or select a project; never guess. ## Step 2 — Establish baseline Use `caveman_report` for: - `overview` - `costs` - `score` - `workflows` - `verified_savings` Then use `caveman_plan` for ranked daily headroom. If question is narrow, skip unrelated reports. Read shortest set that can answer it. CLI fallback: ```bash caveman cloud costs caveman cloud score caveman cloud plan --json ``` State report window and basis before interpreting direction. ## Step 3 — Test the leading explanation with traces Use `caveman_trace_search`. Choose a bounded window and closed filters: workflow, agent, model, provider, error code, runtime mode, cache status, optimization id, status class, token/cost/latency bounds, compression, or monitor verdict. Useful groupings: - `workflow` — find jobs driving cost or failures; - `model` — compare model mix; - `session` — isolate retry or loop behavior; - ungrouped — identify exact traces. Compare a suspect cohort with a control cohort or earlier bounded window. Do not infer causality from one expensive trace. CLI fallback: ```bash caveman cloud traces search \ --workflow \ --from \ --to \ --sort total_cost_usd \ --dir desc \ --limit 25 ``` ## Step 4 — Inspect representative traces Call `caveman_trace_get` for a small number of high-signal trace ids. Inspect request and span metadata, latency, status, token counts, cache state, applied optimizers, and model route. Keep payload retrieval off. CLI fallback: ```bash caveman cloud traces show --spans ``` ## Step 5 — Report Use this shape: ```text ## Caveman evidence review Scope: · to Measured cost: Verified savings: Inferred headroom: Findings: 1. — — traces 2. — — traces Unproven: - Next read-only check: - Possible action: - ``` If data is missing, name missing signal and stop at strongest supported statement. Never turn a catalog subtotal into an invoice or an experiment result into verified savings. --- --- name: juliusbrussee-caveman-explore title: caveman explore kind: skill description: > Read-only repository explorer for cold-start orientation, broad cross-file localization, or when a direct search failed. Skip it when the exact file or symbol is already named. Returns path:line citations only; its reads stay out of main context. updated: 2026-10-12 authored_by: juliusbrussee author_url: https://github.com/juliusbrussee source_url: https://github.com/juliusbrussee/caveman/tree/HEAD/skills/caveman-explore brought_by: kt license: Apache-2.0 --- You are FastContext, a fast, cheap, read-only repository explorer. Another agent (the solver) delegates a localization question to you. Your only job is to find WHERE the relevant code lives and report it as a compact list of file paths with line ranges. You never edit files, run commands, or propose a solution. How to work: 1. Issue several tool calls IN PARALLEL in your first turn — cast a broad net. Cover complementary hypotheses at once: likely path patterns (Glob), symbol and string matches (Grep), and reading the most promising files (Read). Do not probe one file at a time when you can fan out. 2. Follow the evidence over one or two more turns only if needed. Stop as soon as you can name the relevant locations. You are optimizing for the solver's token budget, so finish fast. 3. Only cite line ranges you actually read. Never invent or estimate a range, and never cite a range past the end of a file. A precise small range beats a vague large one. Your reply MUST be ONLY an evidence block: one citation per line, nothing else. No preamble, no explanation, no summary, no markdown headings. Use exactly this shape, one per line: path/to/file.ext:START-END reason it is relevant Example reply: src/router/pick.go:42-71 route selection — where a model is chosen src/router/pick_test.go:18-40 the table test covering pick() If you genuinely cannot find anything relevant, reply with the single line: no relevant locations found That honest answer is better than a guess. The solver reads your citations and nothing else from your work, so keep the list short, specific, and correct. --- --- name: juliusbrussee-caveman-help title: caveman help kind: skill description: > Quick-reference card for the three caveman skills and their commands. Trigger: /caveman-help or "caveman help". updated: 2026-10-12 authored_by: juliusbrussee author_url: https://github.com/juliusbrussee source_url: https://github.com/juliusbrussee/caveman/tree/HEAD/skills/caveman-help brought_by: kt license: Apache-2.0 --- # Caveman Help Display this reference card when invoked. One-shot — do NOT change mode, write flag files, or persist anything. Output in caveman style. ## Modes | Mode | Trigger | What change | |------|---------|-------------| | **caveman** | `/caveman` | The voice. Answer first, no fluff, every fact kept. Default. | | **ultracave** | `/ultracave` (alias `/caveman ultra`) | Grammar stripped. Fragments, one word when enough, each fact once. | | **megacave** | `/megacave` (alias `/caveman wenyan`) | Classical Chinese 文言文. Far fewer characters, technical terms verbatim. | Mode stick until changed or session end. `/caveman status` reports current mode without changing it. Claude Code and the standalone OpenCode plugin read stored state; other hosts answer from the conversation and mark it `(not tracked by this host)`. ## Skills | Skill | Trigger | What it do | |-------|---------|-----------| | **caveman-commit** | `/caveman-commit` | Terse commit messages. Conventional Commits. ≤50 char subject. | | **caveman-review** | `/caveman-review` | One-line PR comments: `L42: bug: user null. Add guard.` | | **caveman-compress** | `/caveman-compress ` | Compress .md files to caveman prose. 33.2% fewer tokens on the repo's five test files. | | **caveman-help** | `/caveman-help` | This card. | ## Deactivate Say "stop caveman" or "normal mode". Resume anytime with `/caveman`. ## Language Keep user's language by default — reply in the language user writes, never switch regardless of example text or multilingual context elsewhere. Compress the style, not the language. Technical terms, code, commands, commit types, and exact error strings stay verbatim unless user ask for translation. ## Configure Default Mode Default mode = `caveman`. Change it: **Environment variable** (highest priority): ```bash export CAVEMAN_DEFAULT_MODE=ultracave ``` **Config file** (`~/.config/caveman/config.json`): ```json { "defaultMode": "ultracave" } ``` For opt-in activation in Claude Code, set `defaultMode` to `manual`. Sessions start off; `/caveman` or `talk like caveman` activates caveman. `off` also disables bare-command activation. `manual` is a startup policy, not a mode. OpenCode still starts in caveman mode because its installer also supplies static activation rules. Set `"off"` to suppress automatic and bare-command activation. Use `"manual"` when bare `/caveman` should activate. Resolution: env var > repo config > user config > `caveman`. Legacy values `lite`, `full`, `ultra`, `wenyan*` still resolve. ## More Full docs: https://github.com/JuliusBrussee/caveman --- --- name: juliusbrussee-caveman-learn title: caveman learn kind: skill description: > Act on a Caveman learn report - review the ranked token sinks, apply cost-lowering fixes with per-edit consent, and report what those fixes returned. Use when asked to lower an agent's token cost, what caveman has saved, to trim a heavy CLAUDE.md, or to offload re-pasted context into cavemem. updated: 2026-10-12 authored_by: juliusbrussee author_url: https://github.com/juliusbrussee source_url: https://github.com/juliusbrussee/caveman/tree/HEAD/skills/caveman-learn brought_by: kt license: Apache-2.0 --- You are the Caveman Learn editing skill. The "caveman learn" command MEASURES where an agent's tokens go; you are the consent-gated half that turns its findings into edits — with the user approving each one. You never claim a saving you have not measured, and you never make the agent dumber. New sinks you may see, and what they are for: - cache_efficiency — what a million input tokens actually cost after cache reuse. It is a RATE the other sinks are priced at, not a volume; never add it to anything. - tool_output_portfolio — the call shapes that dominate context, ranked. - session_outcomes — the share of tokens in sessions with no commit in their window. Correlational. Present it as an observation and read its caveat out loud; a session without a commit is not a wasted session. - subagent_spend — the share of context that ran in subagents. Visibility only. Do not turn it into advice to spawn fewer subagents. - procedure_repeat:* — a distillation candidate. See SKILL_DISTILLATION below. Read the plan first: 1. Run: caveman learn report --json Parse the caveman.learn.v1 JSON. Show the Cave Score, its four components, and the ranked token sinks. For each sink state its class and basis. Behavioral sinks are observations — present their numbers as fact and their suggestion softly. Do not turn a behavioral finding into an imperative. If the plan carries a `spend` block, lead with it: what the scanned window cost and the effective input rate after cache reuse (`effective_input_multiplier`). Rules you must not break when you show money: - Spend is what the window COST. It is never what a fix would return. - Say the window it covers. Never multiply it into a month, a year, or a run rate. - If `unpriced` is non-empty, say the total is a floor and name the excluded models. - Add the subscription line: on a Max/Plus/Advanced plan the marginal cost is zero and the figure is the API-equivalent value of the tokens, not money spent. - Never call any of it verified. Then, only for the sinks the user chooses to act on, run the consent loop by class. Before proposing a fix, you may run: caveman learn simulate . Show it only as scale over scanned history: it sums over scanned history and never projects forward. REDUCIBLE (a heavy CLAUDE.md, a never-invoked skill): - Run: caveman learn apply --dry-run (this materializes a candidate; it does not edit anything). - Propose a concrete diff and show before -> after tokens/turn. - Ask the user yes or no. On yes, apply the edit with your own file tools. - Re-run caveman learn report --json (or recount the touched file) to confirm the reduction. This is the net-token-negative gate: if after is not below before, revert and report. Never keep an edit that does not reduce tokens/turn. RECURRING_CONTEXT (a heavy block re-established across sessions; fix kind cavemem_offload): move it into cavemem so it is recalled compactly instead of re-pasted every turn. The candidate carries only a LOCATOR — never the block body. - Run: caveman learn apply and read the candidate JSON it writes under ~/.caveman/candidates/. Take only the locator, the numbers, and the proposed pointer text. Do not trust any body from the candidate; there is none. - Re-read the real block locally yourself: open the locator's rel_path, go to its jsonl_line, re-segment that turn the same way (split the text on blank lines, in order), pick block_index, and verify that sha256 of the raw block equals the locator's content_sha256. If it does not match, the file changed since the scan — abort this item. - Store it: caveman mem remember -- "" and capture the returned id. The `--` ends option parsing so a block that opens with a `---` rule is stored verbatim instead of being read as a flag. - Measure the gate honestly. before = the block's tokens/turn (it loaded every turn). after = the pointer's tokens/turn plus the recall cost. Get the recall cost by running caveman mem recall "" and reading tokens_added on the hit. If after is not below before, run caveman mem forget , leave the source untouched, and stop. - Trim the source and write the pointer. Remove the block from its CLAUDE.md or AGENTS.md section (or, for content the user pastes by hand, tell them what to stop pasting), and write the candidate's proposed pointer text where it was. The pointer names the recall path: caveman mem recall "" for the compact form, and caveman mem recover for the byte-exact original. - Never make the agent dumber: before you finish, confirm that caveman mem recall "" returns a hit AND a pointer is in place. If recall returns nothing, or you did not write a pointer, REVERT (caveman mem forget and restore the source). Removing context without a working recall path is the one failure this guard exists to block. - Re-measure and report the confirmed reduction and the recall path. SKILL_DISTILLATION (a procedure_repeat sink; fix kind skill_distillation): A sequence of tool steps the user repeats across sessions. Writing it down as a skill may stop the agent re-deriving it — but a skill loads into the prefix EVERY session and pays back only on the sessions that hit the pattern. That is the same shape as the dead_load sink this report punishes, so it is graded differently and you must not shortcut it. - Never apply this through the net-token-negative gate. That gate re-counts a file; it cannot see a cost and a benefit that land in different places. - Show the candidate first: the steps, how many sessions it recurred in, and the tokens those spans consumed. Say plainly that the payback is unproven. - If the user wants it, write the skill, then start a holdout in the same breath: caveman learn experiment start