Caveman Skill System Components: A Technical Guide to Modular AI Compression

The Caveman skill system consists of self-contained metadata files stored in skills/ and supporting runtime hooks that enable token-efficient communication, automated commit messages, and sub-agent delegation.

The Caveman skill system is a modular architecture implemented in the JuliusBrussee/caveman repository that allows AI agents to compress language, generate terse commit messages, and delegate work through declarative skill definitions. Each skill is a self-contained unit comprising metadata files, trigger phrases, and behavioral rules that the core engine loads at runtime. This system enables users to activate specific compression modes and automation behaviors without modifying the underlying engine code.

Core Skill Definitions

The Caveman skill system includes seven primary skills located under the skills/ directory. Each skill contains a SKILL.md file defining its behavior, triggers, and constraints.

Base Compression Mode (caveman)

The caveman skill sets the default compression intensity—such as lite, full, or ultra—and drops filler words, articles, and hedging from model outputs. According to the source code in skills/caveman/SKILL.md, this skill establishes the foundational "caveman speak" behavior that other skills build upon.

Token Usage Statistics (caveman-stats)

The caveman-stats skill reports session token usage through the hook implemented in src/hooks/caveman-stats.js. When invoked via /caveman-stats, this skill injects a formatted statistics block showing current consumption metrics.

Code Review Compression (caveman-review)

The caveman-review skill produces ultra-compressed one-line PR review comments. As defined in skills/caveman-review/SKILL.md, it enforces a strict comment format such as L42: 🔴 bug: user may be null. Add guard. and filters out polite filler to minimize token usage.

Help Reference (caveman-help)

The caveman-help skill acts as a quick-reference card listing all available Caveman modes, skills, and commands. The definition in skills/caveman-help/SKILL.md specifies the display format triggered by /caveman-help.

File Compression (caveman-compress)

The caveman-compress skill compresses natural-language files like Markdown and TXT into caveman style. The implementation in skills/caveman-compress/SKILL.md references Python scripts in skills/caveman-compress/scripts/cli.py that detect file types, call Claude for compression, validate output, and write backups. Users invoke this via command line:

python3 -m scripts <file>

Commit Message Generation (caveman-commit)

The caveman-commit skill generates terse Conventional Commit messages. According to skills/caveman-commit/SKILL.md, it guarantees subject lines of 50 characters or less, omits fluff, and adds a body only when the rationale isn't obvious from the subject.

Sub-Agent Delegation (cavecrew)

The cavecrew skill provides a decision-guide that spawns three sub-agents: investigator, builder, and reviewer. As documented in skills/cavecrew/SKILL.md, this skill reduces main-thread token consumption by approximately 60 percent when delegating tasks to sub-agents, with all outputs remaining caveman-compressed.

Runtime Hooks and Infrastructure

The Caveman skill system relies on JavaScript modules in src/hooks/ to implement dynamic skill behaviors at runtime.

• src/hooks/caveman-mode-tracker.js: Watches for mode changes and applies the active compression level.
• src/hooks/caveman-stats.js: Generates the formatted statistics output for the caveman-stats skill.
• src/hooks/caveman-config.js: Reads environment variables and configuration files to determine default modes.
• src/hooks/caveman-activate.js: Auto-activates caveman mode on session start based on configuration.

These hooks interact with the skill definitions to route user commands to the appropriate implementation without requiring core engine modifications.

Command Interface and Configuration

Each skill exposes commands through dual-format definitions stored in commands/:

• TOML files (e.g., commands/caveman.toml) provide machine-readable command specifications.
• Markdown files (e.g., commands/caveman.md) provide human-readable documentation.

The CLI entry point at src/tools/caveman-init.js registers all skills at startup, parsing the TOML definitions and binding them to the corresponding runtime hooks.

Practical Usage Examples

Activate the base compression mode with intensity specification:

/caveman ultra

Display current session token statistics:

/caveman-stats

Generate a terse Conventional Commit message:

/caveman-commit

Produce a one-line code review comment:

/caveman-review

Compress a Markdown file using the compression CLI:

caveman-compress README.md

Delegate investigation to a sub-agent:

/cavecrew-investigator find function foo

Summary

• The Caveman skill system uses self-contained skill definitions in skills/ to declare compression behaviors and automation rules.
• Seven core skills handle compression modes, statistics, code reviews, help text, file processing, commits, and sub-agent delegation.
• Runtime hooks in src/hooks/ implement the dynamic behavior, while command definitions in commands/ expose skills to users via TOML and Markdown files.
• The system supports token-efficient communication through strict formatting rules, such as the L42: 🔴 bug: ... review format and 50-character commit subjects.
• File compression utilizes Python scripts in skills/caveman-compress/scripts/ to process documents while maintaining backups.

Frequently Asked Questions

What files define a Caveman skill?

Each skill is defined by a SKILL.md file located in its respective subdirectory under skills/. For example, the base compression mode is defined in skills/caveman/SKILL.md, while the commit generation skill uses skills/caveman-commit/SKILL.md. These metadata files specify the skill's name, description, trigger phrases, and behavioral rules.

How does the Caveman skill system reduce token usage?

The system reduces token usage through aggressive compression rules that remove filler words, articles, and hedging. Specific skills like caveman-review enforce strict one-line formats, while the cavecrew skill delegates work to sub-agents to reduce main-thread consumption by approximately 60 percent. All outputs follow "caveman speak" conventions to minimize character count.

Where are the runtime hooks implemented?

Runtime hooks are implemented as JavaScript modules in the src/hooks/ directory. Key files include caveman-mode-tracker.js for monitoring compression levels, caveman-stats.js for generating usage reports, and caveman-activate.js for auto-starting modes. The CLI entry point at src/tools/caveman-init.js registers these hooks at startup.

How do I add a new skill to the Caveman system?

To add a new skill, create a subdirectory under skills/ containing a SKILL.md metadata file that defines the skill's triggers and behavior. Add corresponding command definitions in commands/ as both TOML and Markdown files. If the skill requires dynamic behavior, implement the logic in a new JavaScript file under src/hooks/ following the pattern of existing hooks like caveman-stats.js.

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