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

> Uncover how the caveman project main skill is implemented. This technical deep dive explores markdown rules, Node.js activation hooks, and stateless skill architecture for Claude.

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

---

**The caveman project main skill is implemented as a stateless, text-only skill that reads markdown rules from [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/.caveman/config.json)** or **[`.caveman.json`](https://github.com/JuliusBrussee/caveman/blob/main/.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:

```bash
$ claude /caveman

```

Switch to ultra-terse mode for the current session:

```bash
$ claude /caveman ultra

```

Disable caveman mode and return to normal output:

```bash
$ claude /caveman off

```

Query the current mode programmatically in a custom hook:

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

```bash

# 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`](https://github.com/JuliusBrussee/caveman/blob/main/plugins/caveman/skills/caveman/SKILL.md) as a declarative markdown ruleset with intensity-specific tables
- **[`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js)** reads and filters [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) on session start, injecting the appropriate rules as hidden context
- **[`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/.caveman/config.json)** or **[`.caveman.json`](https://github.com/JuliusBrussee/caveman/blob/main/.caveman.json)** file in your repository root with `{"defaultMode":"lite"}` (or your preferred intensity). According to the configuration resolution order in [`caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) is unavailable, the activation hook in **[`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/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.