# Caveman Skills Explained: Structure, Configuration, and Usage in the Caveman LLM Proxy

> Learn how to structure, configure, and use Caveman skills. These modular plug-ins transform LLM responses and expose new commands via markdown files with YAML front-matter and plain-text rules.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: deep-dive
- Published: 2026-09-06

---

**Caveman skills are modular, declarative plug-ins stored in `skills/<skill-name>/SKILL.md` files that instruct the Caveman LLM proxy how to transform model responses or expose new commands through YAML front-matter, plain-text rules, and intensity-based filtering.**

In the [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman) repository, Caveman skills provide a clean separation between LLM behavior definitions and the engine that executes them. Each skill is a self-contained directory with a standardized structure, enabling version control, easy distribution, and runtime intensity filtering.

## What Are Caveman Skills?

Caveman skills are **declarative configuration files** that modify how the Caveman proxy interacts with language models. Rather than hardcoding prompt engineering logic, the system externalizes these behaviors into readable, maintainable markdown files.

A skill defines:

- **Identity metadata** (name, description via YAML front-matter)
- **Behavioral rules** (plain-text instructions injected into system prompts)
- **Intensity variations** (mode-specific rule subsets for `lite`, `full`, `ultra`, or custom modes)
- **Usage examples** (concrete input/output pairs per intensity level)

This architecture allows users to switch communication styles instantly—for example, from verbose explanations to ultra-compressed "caveman speak"—without reconfiguring the underlying model.

## How Caveman Skills Are Structured

### Directory Layout

Every skill resides in its own directory under `skills/`:

```

skills/
├─ <skill-name>/
│   ├─ SKILL.md          ← required: core definition
│   ├─ README.md?       ← optional: human-readable documentation
│   ├─ tests/…          ← optional: unit tests
│   └─ other files…     ← optional: helper scripts, assets

```

### The SKILL.md File Format

The [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) file in `skills/<skill-name>/SKILL.md` is the **single source of truth** for a skill's behavior. It follows a strict five-section layout:

1. **YAML front-matter** – `name` and `description` fields
2. **Human-readable description** – explains the skill's purpose
3. **Rules** – plain-text behavioral specifications
4. **Intensity table** – markdown table mapping modes to rule variations
5. **Examples** – concrete snippets for each intensity level

For example, [[`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md)](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) defines the baseline compression skill, while [[`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md)](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md) specifies Conventional Commit message generation.

## Runtime Loading and Intensity Filtering

The Caveman engine processes skills through a three-stage pipeline:

### Stage 1: Discovery

The CLI scans multiple skill stores:

- `~/.agents/skills` – user-level agent skills
- `~/.codex/skills` – Codex-specific skills
- Repository `skills/` – bundled skills

### Stage 2: Loading and Filtering

In [[`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js)](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js#L75-L80), the `loadFilteredRuleset` function:

- Reads the target [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md)
- Strips YAML front-matter
- Filters the intensity table to the active mode
- Returns only matching rules and examples

```javascript
// From src/hooks/caveman-config.js#L75-L80
// Pseudocode representation of loadFilteredRuleset behavior
function loadFilteredRuleset(skillPath, mode) {
  const raw = readFile(skillPath + '/SKILL.md');
  const { frontMatter, content } = parseFrontMatter(raw);
  const ruleset = extractIntensityTable(content, mode); // ← filters to active mode
  return { ...frontMatter, rules: ruleset };
}

```

### Stage 3: Injection

[[`src/plugins/opencode/plugin.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/plugin.js)](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/plugin.js) injects the filtered ruleset into every model request, ensuring the skill's instructions are always present in the system prompt.

## CLI Commands for Skill Management

### List Available Skills

```bash
caveman tools skills list

```

Sample output:

```

caveman          – Ultra-compressed communication mode
caveman-commit   – Conventional-commit message generator
caveman-compress – Compress natural-language files into caveman-speak
caveman-setup    – Wire repository through Caveman gateway

```

### Install a Skill from Remote Source

```bash
caveman tools skills add \
  https://github.com/JuliusBrussee/caveman/tree/main/skills/caveman-discover \
  --skill caveman-discover \
  --agent codex \
  -y

```

This fetches the remote [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) and stores a byte-identical copy in the local skill registry.

### Preview Skill Output

```bash
caveman tools skills preview caveman-commit

```

Excerpt showing full-intensity output:

```

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

Mobile client needs profile data without full user payload to reduce LTE bandwidth on cold-launch screens.

Closes #128

```

### Switch Intensity Mode

```bash
caveman tools mode set ultra

```

After execution, all skills inject only `ultra`-intensity rules, drastically reducing token consumption.

## Key Implementation Files

| File | Role |
|------|------|
| [[`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md)](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) | Baseline compression skill with core intensity levels |
| [[`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md)](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md) | Conventional Commit generation with formatted output rules |
| [[`skills/caveman-compress/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/SKILL.md)](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/SKILL.md) | File-rewriting skill with backup handling for [`CLAUDE.md`](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md) |
| [[`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js)](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js) | Loader implementing `loadFilteredRuleset` intensity filtering |
| [[`src/plugins/opencode/plugin.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/plugin.js)](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/plugin.js) | Request interceptor that injects filtered rulesets |
| [[`packages/cli/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/packages/cli/README.md)](https://github.com/JuliusBrussee/caveman/blob/main/packages/cli/README.md) | CLI command documentation for skill lifecycle management |

## Summary

- **Caveman skills** are modular LLM behavior definitions stored in `skills/<skill-name>/SKILL.md`
- Each **SKILL.md** contains YAML front-matter, rules, an intensity table, and examples
- The **`loadFilteredRuleset`** function in [`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js) filters rules by active mode (`lite`, `full`, `ultra`)
- **[`src/plugins/opencode/plugin.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/plugin.js)** injects filtered rulesets into every model request
- Skills are managed through CLI commands: `list`, `add`, `preview`, and mode switching

## Frequently Asked Questions

### What format does a Caveman SKILL.md file use?

A [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) file uses YAML front-matter for metadata followed by standard markdown sections. The front-matter contains `name` and `description` fields. The body includes a human-readable description, rules, an intensity table mapping modes to variations, and usage examples. This format is parsed by `loadFilteredRuleset` in [`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js).

### How does intensity filtering work in Caveman?

Intensity filtering selects rule subsets based on the active mode. When you run `caveman tools mode set ultra`, the loader in [`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js) extracts only the `ultra` row from each skill's intensity table. This ensures the model receives minimal, high-compression instructions rather than the full ruleset.

### Where are Caveman skills stored after installation?

Installed skills are copied to `~/.agents/skills` or `~/.codex/skills` depending on the `--agent` flag. The CLI preserves byte-exact copies of [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) files. The system also checks the repository's local `skills/` directory for bundled skills.

### Can I create custom Caveman skills?

Yes. Create a directory under `skills/` with a [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) file containing the five required sections. Include an intensity table with at least one mode, then install locally with `caveman tools skills add <path>`. The skill becomes available immediately for preview and activation.