Caveman Skills Examples: How to Use the JuliusBrussee/caveman Plugin

The JuliusBrussee/caveman repository provides several caveman skills—including /caveman-commit, /caveman-review, /caveman-compress, and /caveman-stats—that reduce AI output tokens by approximately 65% through terse, filler-free communication while preserving code accuracy.

Caveman is a skill/plugin system designed for AI-coding agents that strips filler words from natural language responses. By activating specific caveman skills, developers can significantly lower token costs during extended coding sessions. The repository implements this through a combination of flag files, Node.js hooks, and skill definitions stored in the skills/ directory.

Core Caveman Skills Examples

The repository exposes multiple specialized skills that handle different development workflows. Each skill lives in its own subdirectory under skills/ and defines specific behavior through a SKILL.md file.

Generate Terse Commit Messages with /caveman-commit

The commit skill produces Conventional Commit-style messages limited to 50 characters or fewer. When invoked, the agent outputs a compact summary without descriptive paragraphs.

/caveman-commit

# → "feat: add token-saving filter"

According to the source code, this behavior is defined in [skills/caveman-commit/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md). The skill instructs the agent to analyze staged changes and respond with only the commit subject line.

Create One-Line PR Reviews with /caveman-review

The review skill generates ultra-concise pull request feedback using a line-reference format. This caveman skill outputs single-line observations that point to specific code locations.

/caveman-review

# → "L42: guard null user → add early return"

The implementation resides in [skills/caveman-review/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-review/SKILL.md), which directs the agent to examine file diffs and emit only critical observations prefixed with line numbers.

Compress Documentation with /caveman-compress

The compress skill rewrites markdown files into caveman prose, achieving approximately 46% input-token reduction for future sessions. This utility operates on existing documentation to permanently reduce token costs.

/caveman-compress docs/README.md

The underlying logic appears in [src/tools/caveman-init.js](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js) alongside the skill definition at [skills/caveman-compress/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/SKILL.md).

Monitor Token Savings with /caveman-stats

The stats skill calculates cumulative token savings by reading session logs and computing efficiency metrics. It also updates the status-line suffix to display real-time savings.

/caveman-stats

This functionality combines the hook logic in [src/hooks/caveman-stats.js](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js) with the mode-tracker system to persist statistics across sessions.

Activation and Mode Control

Before using specific skills, you must activate the caveman system through the core controller. The plugin supports multiple compression levels and natural-language toggles.

Switching Compression Levels

Use slash commands to set the desired verbosity level. The flag file (.caveman-active) stores the current mode in the agent's config directory, handled by [src/hooks/caveman-config.js](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js).

# Full compression (default)

/caveman

# Light compression with partial context

/caveman lite

# Maximum compression

/caveman ultra

# Classical Chinese style (wenyan)

/caveman wenyan

The parseModeChange function in [src/plugins/opencode/plugin.js](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/plugin.js) processes these commands and writes the appropriate flag value.

Disabling Caveman Mode

To return to normal output, remove the flag file using either the explicit command or natural language.

/caveman off

# Or simply state: "stop caveman"

The mode-tracker hook at [src/hooks/caveman-mode-tracker.js](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js) intercepts these prompts and updates the flag file accordingly, ensuring immediate effect without restarting the agent.

Installation and Setup

Install the complete skill suite for Claude Code, Cursor, Gemini, or other supported agents using the unified installer.

# Via curl

/usr/bin/curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

# Via npm for specific agents

npx -y github:JuliusBrussee/caveman -- --only claude

# Or using the skills CLI

npx skills add JuliusBrussee/caveman -a <agent>

The installer script at [bin/install.js](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) copies all skill definitions from the skills/ folder into the agent's skill directory and configures the necessary hooks.

How It Works Under the Hood

The caveman skills architecture relies on three interconnected components:

1. Flag File System: The hidden .caveman-active file persists the current mode across sessions, managed by the config helper in src/hooks/caveman-config.js.
2. Hook Interception: Node hooks in src/hooks/caveman-mode-tracker.js intercept every user prompt to detect slash commands or natural-language triggers.
3. Skill Definitions: Individual capabilities reside in skills/<skill-name>/SKILL.md files that agents read to understand behavioral constraints.

For Opencode integration, the plugin at [src/plugins/opencode/plugin.js](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/plugin.js) wires the flag logic into the Opencode event system, ensuring mode persistence across chat sessions.

Summary

• Caveman skills reduce AI output tokens by ~65% through concise, filler-free communication.
• Four primary skills handle commits (/caveman-commit), reviews (/caveman-review), file compression (/caveman-compress), and statistics (/caveman-stats).
• Mode control uses slash commands (/caveman lite, /caveman ultra, /caveman off) parsed by the mode-tracker hook and stored in .caveman-active flag files.
• Installation deploys skill definitions to the agent's configuration directory via bin/install.js.
• Source files including src/hooks/caveman-config.js and src/plugins/opencode/plugin.js manage the underlying state persistence and event handling.

Frequently Asked Questions

How do I activate caveman mode in an existing session?

Type /caveman followed by your desired level (e.g., lite, full, ultra, or wenyan). The command is parsed by the mode-tracker hook in src/hooks/caveman-mode-tracker.js, which writes the level to the .caveman-active flag file in your config directory. Changes take effect immediately without restarting the agent.

What is the difference between caveman levels?

/caveman lite preserves some contextual filler for readability while still reducing tokens. /caveman full removes most non-essential words. /caveman ultra applies maximum compression. /caveman wenyan outputs classical Chinese-style terse prose. All levels maintain code syntax and technical accuracy while only compressing natural language.

Can I use caveman skills with any AI coding agent?

Yes, the repository supports multiple agents including Claude Code, Cursor, Gemini, and Opencode. The installer at bin/install.js adapts the skill files to each agent's specific format. For Opencode, the dedicated plugin at src/plugins/opencode/plugin.js handles event integration and session persistence automatically.

Where are the skill definitions stored?

Each skill's behavioral instructions reside in its respective SKILL.md file under the skills/ directory. For example, commit behavior is defined in skills/caveman-commit/SKILL.md, while compression logic is defined in skills/caveman-compress/SKILL.md. These files instruct the agent how to format responses when specific commands are invoked.

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