Caveman Project Skills Documentation: Complete Guide to Claude Agent Modes

Yes, the JuliusBrussee/caveman repository maintains comprehensive documentation for every skill through dedicated SKILL.md files located in the skills/ directory, each defining triggers, rules, and technical boundaries for ultra‑compressed Claude interactions.

The caveman project skills documentation is embedded directly in the codebase rather than external wikis. Each skill is a self‑contained interaction mode that reduces token usage by approximately 65% while preserving technical accuracy. The documentation lives in structured markdown files paired with JavaScript hooks and agent definitions that govern how Claude processes slash commands like /caveman or /caveman‑review.

What Are Caveman Skills?

Caveman skills are ultra‑compressed interaction modes designed for Claude‑based agents. Each skill is defined by a SKILL.md file residing under skills/<skill‑name>/SKILL.md. These files follow a front‑matter format enclosed in triple dashes (---) that declares the skill’s name, description, and operational constraints.

According to the caveman source code, skills implement specific boundaries—declaring explicitly what they do not do—to prevent side effects. For example, the caveman‑commit skill formats commit messages but never executes git commit.

Available Skills and Documentation Locations

The repository ships seven core skills, each with dedicated documentation:

• caveman – The core compression mode that switches Claude to a terse speaking style. Documentation: skills/caveman/SKILL.md.
• caveman‑commit – Generates Conventional‑Commit messages from diffs. Documentation: skills/caveman-commit/SKILL.md.
• caveman‑review – Produces one‑line, actionable code‑review comments. Documentation: skills/caveman-review/SKILL.md.
• caveman‑stats – Displays token‑usage statistics for the current session. Documentation: skills/caveman-stats/SKILL.md (core) and plugins/caveman/skills/caveman-stats/SKILL.md (plugin version).
• caveman‑help – Provides quick help about caveman modes. Documentation: skills/caveman-help/SKILL.md.
• caveman‑compress – Handles markdown‑compression tasks such as todo‑list compression. Documentation: skills/caveman-compress/SKILL.md.
• cavecrew – A collection of auxiliary skills for internal agent use (builder, reviewer, investigator). Documentation: skills/cavecrew/SKILL.md.

How Skill Documentation Is Structured

The caveman project skills documentation follows a strict architecture that separates definitions from execution logic.

SKILL.md Front‑Matter Format

Each skill file begins with YAML front‑matter declaring metadata:

---
name: caveman
description: Ultra‑compressed speaking mode
---

The remaining content describes triggers, rules, and boundaries in human‑readable markdown.

Trigger Handling and Agents

Slash commands like /caveman lite|full|ultra are processed by the opencode runtime. The agents/ folder contains markdown agent files—such as agents/cavecrew‑reviewer.md and agents/cavecrew‑builder.md—that reference these skills and map user inputs to specific skill executions.

Hooks for Computation

Certain skills require JavaScript computation rather than pure prompt engineering. These are implemented in the hooks/ directory:

• hooks/caveman‑mode‑tracker.js – Tracks the active state of the caveman mode and manages persistence.
• hooks/caveman‑stats.js – Calculates token usage and returns a decision: "block" containing formatted statistics.

Persistence Mechanisms

The core caveman skill marks itself ACTIVE EVERY RESPONSE according to its persistence section. Once enabled via /caveman ultra, the compression style persists across every subsequent response until the user explicitly disables it with /caveman stop.

Practical Usage Examples

Enabling Ultra Compression Mode

To activate the terse speaking style:

/caveman ultra

The model now replies using the compressed pattern defined in skills/caveman/SKILL.md, reducing token consumption by approximately 65%.

Generating Conventional Commit Messages

Invoke the commit skill with a diff:

/caveman‑commit
<diff snippet>

The agent outputs a properly formatted message:

feat(api): add GET /users/:id/profile

Mobile client needs profile data without the full payload.

Closes #128

Production Code Review Comments

For concise pull request reviews:

/caveman‑review
<PR diff>

The response follows the one‑line format specified in skills/caveman-review/SKILL.md:

L42: 🔴 bug: user can be null after .find(). Add guard before .email.

Checking Token Statistics

To view session metrics without AI computation:

/caveman‑stats

The hooks/caveman‑stats.js hook injects a table showing total tokens used, saved, and projected savings.

Summary

• Documentation location: Every skill is documented in skills/<name>/SKILL.md with YAML front‑matter and markdown rules.
• Architecture: Skills combine markdown definitions, agent triggers in agents/, and JavaScript hooks in hooks/ for stateful operations.
• Token efficiency: The core caveman skill reduces token usage by ~65% through ultra‑compressed output patterns.
• Persistence: The caveman mode stays active across responses until explicitly stopped, managed by hooks/caveman‑mode‑tracker.js.
• Boundaries: Each skill explicitly declares prohibited actions (e.g., caveman‑commit never executes git commands) to prevent side effects.

Frequently Asked Questions

Where is the caveman project skills documentation located?

The documentation resides in the skills/ directory of the JuliusBrussee/caveman repository. Each skill has its own subdirectory containing a SKILL.md file that defines triggers, rules, and boundaries. Additional implementation details appear in hooks/ for JavaScript logic and agents/ for trigger handling.

How do I enable a specific skill in the caveman project?

You enable skills by typing slash commands recognized by the opencode runtime. For example, use /caveman ultra to activate maximum compression, /caveman‑review for code review mode, or /caveman‑stats to see token usage. The commands are parsed and mapped to the corresponding SKILL.md definitions.

What is the difference between a skill and an agent in the caveman repository?

A skill is a documented interaction mode defined in SKILL.md files under skills/, specifying how Claude should behave and respond. An agent is a higher‑level construct in the agents/ directory that references one or more skills to handle specific workflows, such as the cavecrew‑reviewer agent that utilizes the caveman‑review skill.

Can I create custom skills for the caveman project?

Yes. Create a new directory under skills/ with a SKILL.md file following the front‑matter format (--- name and description ---). Define your triggers, rules, and explicit boundaries. If your skill requires computation (like token counting), implement a corresponding hook in hooks/ and reference it in your agent definitions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}