Caveman's Skill File Injection System for AI Agents: A Three-Layer Architecture

Caveman implements a three-layer injection pipeline—static skill definition, OpenClaw workspace bootstrap, and per-turn hook reinforcement—that injects terse prose rules into AI agents via Project Context manipulation and JSON payload emission.

The JuliusBrussee/caveman repository provides an "always-on" AI agent behavior system built on a sophisticated skill file injection system for AI agents. Unlike manual prompt injection, Caveman's architecture decouples static rule delivery from dynamic mode control, enabling persistent Caveman mode across sessions without polluting the model's context window with repetitive instructions.

Architecture Overview: The Three-Layer Pipeline

Caveman's injection system bridges three distinct layers: the canonical skill definition, the OpenClaw workspace gateway, and the per-turn reinforcement hook. This separation allows the model to load comprehensive rules once while receiving lightweight mode reminders on every turn.

Layer 1: Static Skill Definition in SKILL.md

The foundation of the system resides in skills/caveman/SKILL.md. This markdown file contains the complete rule set—including description, intensity levels, persistence rules, and stylistic constraints—that the model must obey when Caveman mode is active. The file serves as the single source of truth for the behavior definition.

Layer 2: OpenClaw Workspace Injection

When a user runs caveman init, the OpenClaw helper (bin/lib/openclaw.js) performs two idempotent writes to prepare the workspace. First, the installOpenclaw function triggers mergeOpenclawFrontmatter to copy the skill file into <workspace>/skills/caveman/ with the required Frontmatter (name, version, always: true). This makes the skill discoverable by OpenClaw’s skill-loader.

Second, the functions loadBootstrapSnippet and appendBootstrapToSoul append a marker-fenced bootstrap block to the workspace’s SOUL.md. The block uses <!-- caveman-begin --> and <!-- caveman-end --> delimiters and contains a sentinel instruction that points the model at the skill. OpenClaw automatically injects the entire SOUL.md into the model’s Project Context on every turn (subject to a 12 KB per-file cap), ensuring the bootstrap is always present without manual invocation.

Layer 3: Per-Turn Hook Reinforcement

The src/hooks/caveman-mode-tracker.js hook runs on the UserPromptSubmit event. It parses user prompts for /caveman commands, updates a hidden flag file at $HOME/.claude/.caveman-active, and, if a mode is active, emits a hookSpecificOutput JSON payload that merges into the model’s context for that specific turn. This reinforcement guarantees that the mode survives competing style injections from other plugins.

The hook logic (lines 63-100 and 120-190) also handles "independent" one-shot modes—such as commit, review, and compress—by temporarily saving the previous prose mode and restoring it after the turn completes.

Practical Usage: Installing and Activating Caveman Mode

The following examples demonstrate how the injection system operates in practice.

Install the skill into your workspace (equivalent to running caveman init):

node bin/lib/openclaw.js install

This copies skills/caveman/SKILL.md into the OpenClaw workspace and appends the bootstrap block to SOUL.md.

Activate Caveman mode for a session:

/caveman full

The caveman-mode-tracker hook writes full to $HOME/.claude/.caveman-active. From the next turn onward, the model receives:

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "CAVEMAN MODE ACTIVE (full). Drop articles/filler/pleasantries/hedging..."
  }
}

Deactivate the mode:

stop caveman

The hook removes the flag file, and subsequent turns no longer contain the reinforcement JSON.

Trigger a one-shot independent mode:

/caveman-compress

The hook temporarily saves the current prose mode, activates compress for that turn only, then restores the previous mode automatically.

Summary

• Three-layer decoupling: Static rules live in SKILL.md, OpenClaw handles workspace injection via SOUL.md, and the hook provides dynamic reinforcement.
• Persistent availability: The always: true Frontmatter and Project Context injection ensure Caveman rules are available without per-session activation.
• State management: The flag file at $HOME/.claude/.caveman-active and hookSpecificOutput JSON enable mode persistence across turns while minimizing token usage.
• One-shot support: The mode tracker handles temporary modes by saving and restoring state, allowing isolated use of specific styles without affecting the active session mode.

Frequently Asked Questions

How does Caveman ensure the skill persists across chat sessions?

OpenClaw injects the SOUL.md bootstrap into the Project Context on every turn (up to 12 KB), and the mode tracker hook writes to $HOME/.claude/.caveman-active to maintain state. This combination ensures the model always sees the skill definition and remembers the active mode without user intervention.

What is the purpose of the hookSpecificOutput JSON payload?

The payload serves as per-turn reinforcement that merges into the model's context for that specific turn only. It ensures Caveman mode overrides competing style instructions from other plugins or system prompts, guaranteeing the terse prose style is applied consistently.

Where is the Caveman skill file actually stored?

The canonical definition lives in skills/caveman/SKILL.md in the repository. When caveman init runs, bin/lib/openclaw.js copies it to <workspace>/skills/caveman/SKILL.md with merged Frontmatter containing always: true, making it discoverable by the OpenClaw skill-loader.

How does the system handle temporary modes like /caveman-compress?

The mode tracker hook in src/hooks/caveman-mode-tracker.js saves the current prose mode to a temporary variable, activates the requested mode for that turn via hookSpecificOutput, then automatically restores the previous mode after the turn completes (lines 63-100, 120-190).

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