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

> Learn to load Caveman skills into AI agents. Our guide explains session-start hooks and `bin/install.js` for seamless integration with Claude Code, Opencode, and more.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-07-07

---

**Caveman skills load into AI agents via session-start hooks that read [`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md), strip the YAML front-matter, and inject the ruleset as a system prompt, with installation handled by [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md)** – The canonical prompt file containing the YAML front-matter and intensity table
- **[`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js)** – Session-start hook that resolves file locations and emits the prompt
- **[`caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-mode-tracker.js)** – Runtime command parser for switching intensity levels

According to the source code in [`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/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:

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

```

This command executes [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), which detects Claude's configuration directory, copies [`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js) and [`caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/plugins/caveman/.codex-plugin/plugin.json). The installer handles the specific requirements for Opencode's skill store:

```bash
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`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) files in this location.

### Hermes and Other Agents

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

```bash
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:

```bash

# 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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js) hook runs on every **SessionStart** event. As implemented in [`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js), it implements a cascade search pattern:

```javascript
// 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:

```javascript
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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```bash

# 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`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md).

### Installing for Multiple Agents

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

```bash
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:

```bash
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`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) files read by session-start hooks, specifically [`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js).
- The **universal installer** ([`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.