How the Caveman Project Main Skill Is Implemented: A Technical Deep Dive

The caveman project main skill is implemented as a stateless, text-only skill that reads markdown rules from SKILL.md and injects them into Claude’s hidden session context via Node.js activation hooks, using a hierarchical configuration system and safe flag-file persistence to maintain mode across conversation turns.

The caveman project provides a unique Claude plugin that transforms AI interactions into a specific stylistic format through declarative configuration. Understanding how the caveman project main skill is implemented reveals an elegant architecture combining markdown-based rulesets with lightweight Node.js hooks that require no separate runtime component beyond the Claude environment itself.

Core Architecture of the Caveman Skill

The caveman project main skill follows a three-layer architecture that keeps logic declarative and state minimal:

• Declarative rules: Living in plugins/caveman/skills/caveman/SKILL.md
• Session hooks: Handling activation and mode tracking
• Configuration module: Managing defaults and safe state persistence

This design ensures the skill remains completely text-based, with the ruleset living only in markdown while the hooks manage session-wide persistence and status-line integration.

The SKILL.md Ruleset Definition

The heart of the caveman project main skill resides in plugins/caveman/skills/caveman/SKILL.md. This markdown file contains the complete ruleset, intensity levels (full, ultra, lite), examples, and boundaries that define the caveman communication style.

Unlike compiled skills, this is a text-only skill that the activation hook reads dynamically. The hook extracts the intensity-specific portion of the rules table and filters the content before injection, allowing the same source file to serve multiple modes of operation.

Activation Hook Implementation

The src/hooks/caveman-activate.js file serves as the entry point for the caveman project main skill. When a Claude session starts, this hook performs four critical operations:

1. Reads the active mode flag from the filesystem
2. Loads the content of SKILL.md
3. Extracts the intensity-specific rules from the markdown table
4. Injects the filtered text as hidden SessionStart context

If the skill file is unavailable, the hook outputs a fallback ruleset to ensure graceful degradation rather than silent failure.

Runtime Mode Tracking and Commands

Once activated, src/hooks/caveman-mode-tracker.js handles dynamic mode switching through slash commands. This hook monitors every user prompt for /caveman commands, supporting operations like:

• /caveman — Toggle with default intensity
• /caveman ultra — Switch to maximum compression mode
• /caveman off — Disable the skill entirely

The hook updates a per-user flag file at .caveman-active in the Claude config directory and emits a JSON payload that reminds the model to maintain the caveman style on each subsequent turn. It also handles independent one-shot modes such as commit, review, and compress.

Configuration and State Management

The src/hooks/caveman-config.js module provides shared utilities for the caveman project main skill, handling both default resolution and safe state persistence.

Configuration Resolution Order

The module resolves the default mode through a hierarchical cascade:

1. CAVEMAN_DEFAULT_MODE environment variable
2. Repository-local .caveman/config.json or .caveman.json
3. User-level ~/.config/caveman/config.json
4. Built-in fallback to full mode

Safe Flag File Implementation

State persistence uses a size-capped, user-owned flag file that explicitly rejects symlinks to prevent secret leakage or tampering. The file read/write operations validate file ownership and size before processing, ensuring the caveman project main skill maintains security even when storing session state on disk.

Usage Examples

Activate caveman mode with the default intensity:

$ claude /caveman

Switch to ultra-terse mode for the current session:

$ claude /caveman ultra

Disable caveman mode and return to normal output:

$ claude /caveman off

Query the current mode programmatically in a custom hook:

const { readFlag } = require('./caveman-config');
const path = require('path');

const mode = readFlag(path.join(process.env.CLAUDE_CONFIG_DIR, '.caveman-active'));
console.log('Current caveman mode:', mode);   // → "full", "ultra", etc.

Set a repository-wide default mode:

# Checked in to the repo

echo '{"defaultMode":"lite"}' > .caveman/config.json

# Or via environment variable for the current user

export CAVEMAN_DEFAULT_MODE=ultra

Summary

• The caveman project main skill is defined in plugins/caveman/skills/caveman/SKILL.md as a declarative markdown ruleset with intensity-specific tables
• src/hooks/caveman-activate.js reads and filters SKILL.md on session start, injecting the appropriate rules as hidden context
• src/hooks/caveman-mode-tracker.js processes /caveman commands, updates the flag file, and emits per-turn JSON reminders to maintain style consistency
• src/hooks/caveman-config.js resolves configuration hierarchically from environment variables to local files with safe fallback to full mode
• State persists through a securely implemented flag file system (.caveman-active) in the Claude config directory with symlink protection and size limits

Frequently Asked Questions

What file defines the caveman project main skill behavior?

The behavior is defined in plugins/caveman/skills/caveman/SKILL.md, which contains the intensity-specific rules, examples, and boundaries that the activation hook injects into Claude's context at the start of each session.

How does the caveman skill persist across conversation turns?

The skill persists through a combination of the activation hook's initial context injection and the mode-tracker hook's per-turn JSON reminders. The hooks read from a safely implemented flag file stored at .caveman-active in the Claude config directory, which is validated for user ownership and size before each access.

Can I set a default caveman mode for my entire repository?

Yes. Create a .caveman/config.json or .caveman.json file in your repository root with {"defaultMode":"lite"} (or your preferred intensity). According to the configuration resolution order in caveman-config.js, this repository-local setting takes precedence over user-level configuration but yields to the CAVEMAN_DEFAULT_MODE environment variable.

What happens if the SKILL.md file is missing?

If SKILL.md is unavailable, the activation hook in src/hooks/caveman-activate.js outputs a fallback ruleset, ensuring the caveman project main skill degrades gracefully rather than failing silently or breaking the Claude session.

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