How to Load Caveman Skills into AI Agents: Complete Setup Guide

Caveman skills load into AI agents via session-start hooks that read skills/caveman/SKILL.md, strip the YAML front-matter, and inject the ruleset as a system prompt, with installation handled by bin/install.js for Claude Code, Opencode, Hermes, and other supported agents.

The JuliusBrussee/caveman repository provides a minimal, portable system for enforcing terse "caveman" style communication in AI agents. Unlike complex plugin architectures, Caveman uses a single source-of-truth file combined with lightweight runtime hooks to modify agent behavior at the system level.

Understanding the Caveman Skill Architecture

Every Caveman installation revolves around SKILL.md files located in skills/<skill-name>/ directories. These files contain YAML front-matter followed by the terse ruleset that the LLM reads at session start.

The loading pipeline consists of three core components:

• SKILL.md – The canonical prompt file containing the YAML front-matter and intensity table
• caveman-activate.js – Session-start hook that resolves file locations and emits the prompt
• caveman-mode-tracker.js – Runtime command parser for switching intensity levels

According to the source code in src/hooks/caveman-activate.js, the loader searches for the skill file in a specific priority order: first checking the plugin root environment variable, then falling back to repository layout, then standalone configuration paths.

Installation Methods for Different AI Agents

Claude Code

For Claude Code, the installer copies the activation hooks and skill directory into ~/.claude/.

Run the universal installer with the --only claude flag:

curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/v1.9.1/bin/install.js | node - --only claude

This command executes bin/install.js, which detects Claude's configuration directory, copies caveman-activate.js and caveman-mode-tracker.js to the hooks location, and places the caveman skill under ~/.claude/skills/caveman/.

Opencode

Opencode uses a plugin manifest located at plugins/caveman/.codex-plugin/plugin.json. The installer handles the specific requirements for Opencode's skill store:

node bin/install.js --only opencode

The script copies the caveman skill folder into ~/.config/opencode/skills/caveman/ and injects activation rules into ~/.config/opencode/AGENTS.md. Opencode agents automatically discover SKILL.md files in this location.

Hermes and Other Agents

Hermes expects skills in $HOME/.hermes/skills/productivity/. The installer supports this via:

node bin/install.js --only hermes

For other CLI agents like Gemini or Cursor, the installer runs npx skills add <repo> --skill '*' -a <profile> to register the skill with the agent's native store.

Manual Installation Without the Installer

To load Caveman skills without running the installer, manually copy the skill directory and wire the hooks:

# Create the skill directory

mkdir -p ~/.claude/skills/caveman
cp -r /path/to/repo/skills/caveman/* ~/.claude/skills/caveman/

# Install only the hooks

node bin/install.js --only claude --with-hooks

The activate hook will then locate ~/.claude/skills/caveman/SKILL.md using the fallback resolution logic.

How the Loading Pipeline Works

The SKILL.md Source File

The file skills/caveman/SKILL.md serves as the single source of truth. It contains the YAML front-matter defining intensity levels and the prompt body that constrains the LLM's output style.

When the agent starts a session, the hook reads this file and processes it in two stages:

1. Front-matter stripping – Removes the YAML block between the --- delimiters
2. Intensity filtering – Selects the appropriate row from the intensity table based on the active mode

Session Start Hook Execution

The caveman-activate.js hook runs on every SessionStart event. As implemented in src/hooks/caveman-activate.js, it implements a cascade search pattern:

// Resolve SKILL.md location (plugin root → repo → user config)
const skillCandidates = [];
if (process.env.CLAUDE_PLUGIN_ROOT) {
    skillCandidates.push(path.join(process.env.CLAUDE_PLUGIN_ROOT, 'skills', 'caveman', 'SKILL.md'));
}
skillCandidates.push(
    path.join(__dirname, '..', '..', 'skills', 'caveman', 'SKILL.md'),   // repo layout
    path.join(__dirname, '..', 'skills', 'caveman', 'SKILL.md')        // standalone config
);

// Load the first file that exists
let skillContent = '';
for (const candidate of skillCandidates) {
    try {
        skillContent = fs.readFileSync(candidate, 'utf8');
        break;
    } catch (_) { /* try next candidate */ }
}

Once loaded, the hook strips the front-matter and filters the intensity table:

const body = skillContent.replace(/^---[\s\S]*?---\s*/, '');
// …filter intensity rows…
output = `CAVEMAN MODE ACTIVE — level: ${modeLabel}\n\n${filtered.join('\n')}`;
process.stdout.write(output);

Claude's runtime treats this stdout output as a hidden system prompt, forcing every subsequent response to follow the caveman style rules.

Runtime Mode Switching

The caveman-mode-tracker.js hook, wired as a UserPromptSubmit hook, monitors chat commands. When you type /caveman ultra or stop caveman, it updates the flag file at $CLAUDE_CONFIG_DIR/.caveman-active.

This persistence mechanism ensures that the next session start reads the updated intensity level from the flag file and applies the corresponding filter when emitting the prompt.

Practical Usage Examples

Switching Intensity at Runtime

After installation, control the compression level using slash commands:

# In a Claude chat

/caveman ultra   # Switch to ultra-terse mode

The mode tracker detects this command, updates the flag file, and subsequent outputs use the "ultra" row from the intensity table defined in SKILL.md.

Installing for Multiple Agents

To set up Caveman across all supported agents on your system:

node bin/install.js

Without the --only flag, the installer detects all available agents and copies the appropriate hook files and skill directories into each agent's configuration path.

Standalone Skill Deployment

For environments where you cannot run the installer, manually place the skill file:

cp skills/caveman/SKILL.md ~/.config/custom-agent/skills/caveman/

Ensure your agent's configuration points to this path for system prompt loading.

Summary

• Caveman skills load into AI agents through SKILL.md files read by session-start hooks, specifically caveman-activate.js.
• The universal installer (bin/install.js) handles agent detection and copies hooks to ~/.claude/, ~/.config/opencode/, or ~/.hermes/ depending on the target.
• Runtime commands like /caveman ultra trigger caveman-mode-tracker.js to update persistence files, changing the intensity filter for subsequent sessions.
• The resolution cascade checks plugin root, repository layout, and user config directories to locate skills/caveman/SKILL.md.
• Once loaded, the hook strips YAML front-matter and emits the filtered ruleset as a system prompt, enforcing terse output without modifying the underlying model.

Frequently Asked Questions

What file format does Caveman use for skill definitions?

Caveman uses Markdown with YAML front-matter stored in SKILL.md files. The YAML block defines metadata and intensity tables, while the markdown body contains the actual behavioral rules. The loader strips the front-matter (everything between --- delimiters) before injecting the content as a system prompt.

How do I switch between different Caveman intensity levels?

Use the runtime slash commands monitored by caveman-mode-tracker.js. Typing /caveman ultra activates the most terse mode, while stop caveman disables the filter entirely. These commands update the .caveman-active flag file, and the next session start applies the corresponding intensity filter from the YAML table.

Can I use Caveman skills without the installer?

Yes. Manual installation requires copying the skills/caveman/ directory to your agent's skill store (e.g., ~/.claude/skills/caveman/) and wiring the hook files from src/hooks/ into your agent's hook system. The activate hook implements fallback logic to locate SKILL.md in common repository and user config paths even without the installer's path resolution.

Which AI agents are currently supported?

The repository supports Claude Code, Opencode, and Hermes natively, with additional compatibility for Gemini, Cursor, and other CLI agents via the npx skills add command. The installer detects available agents by checking for their configuration directories and copies the appropriate hook files and plugin manifests for each platform.

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