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

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 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 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) defines the baseline compression skill, while [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#L75-L80), the loadFilteredRuleset function:

• Reads the target SKILL.md
• Strips YAML front-matter
• Filters the intensity table to the active mode
• Returns only matching rules and examples

// 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) 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

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

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 and stores a byte-identical copy in the local skill registry.

Preview Skill Output

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

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)	Baseline compression skill with core intensity levels
[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)	File-rewriting skill with backup handling for CLAUDE.md
[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)	Request interceptor that injects filtered rulesets
[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 filters rules by active mode (lite, full, ultra)
• 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 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.

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 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 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 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.

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