How the Caveman Project Structures Its Skills: A Modular Guide to SKILL.md and README.md Contracts

The Caveman project structures each capability as a self-contained skill using paired SKILL.md and README.md files under the skills/ directory, enabling automatic hook registration and clear separation between machine-readable contracts and human documentation.

The JuliusBrussee/caveman repository organizes its functionality into discrete, modular units called "skills." This architecture ensures that every feature—from token usage reporting to terse commit message generation—maintains a declarative interface for the bot's hook system while isolating implementation logic and documentation. Understanding how the Caveman project structures its different skills reveals a design pattern that prioritizes discoverability, maintainability, and clear separation of concerns.

The Two-File Skill Contract

Every skill in the Caveman project is defined by two core files located in its respective subdirectory under skills/. This dual-file approach creates a strict boundary between programmatic interfaces and human-readable guides.

• SKILL.md – Contains the machine-readable description consumed by the bot's hook system. This file declares the skill's name, trigger command (e.g., /caveman-stats), and brief contract parameters.
• README.md – Provides human-readable documentation, usage examples, design rationale, and implementation notes for developers and end users.

This separation ensures that the bot core can parse functional requirements without processing narrative documentation, while users can understand feature behavior without parsing configuration schemas.

Directory Layout and Organization

All skills reside under the top-level skills/ directory, with an identical structure mirrored under plugins/caveman/skills/ for the Opencode plugin implementation. This parallel hierarchy allows the same skill contracts to be referenced from both the core bot and the chat plugin without duplication.

The current skill structure includes:

/skills
├── caveman/               # "Talk like a smart caveman" compression mode

│   ├── SKILL.md
│   └── README.md
├── caveman-stats/         # Token usage reporting

│   ├── SKILL.md
│   └── README.md
├── caveman-review/        # One-line PR comments

│   ├── SKILL.md
│   └── README.md
├── caveman-help/          # Quick reference card

│   ├── SKILL.md
│   └── README.md
├── caveman-compress/      # Markdown file compression utility

│   ├── SKILL.md
│   ├── README.md
│   └── scripts/           # Implementation logic

│       └── __main__.py
├── caveman-commit/        # Terse commit message generation

│   ├── SKILL.md
│   └── README.md
└── cavecrew/              # Auxiliary crew helpers (builder, reviewer)

    ├── SKILL.md
    └── README.md

The plugins/caveman/skills/ directory replicates this exact hierarchy, ensuring that the Opencode plugin exposes identical commands to chat models while maintaining a single source of truth for skill contracts.

How Skills Are Loaded and Executed

The Caveman project employs a three-stage lifecycle for skill activation that bridges declarative configuration and procedural execution.

Hook Registration

At startup, the system parses each SKILL.md file through the hook engine located in hooks/*.js. This registration process reads the machine-readable contract and prepares the bot to recognize the skill's trigger patterns.

Trigger Mapping

The description field within SKILL.md defines the slash command that activates the skill. For example, the caveman-stats skill declares /caveman-stats as its trigger, which the hook system maps to the corresponding execution handler.

Execution Delegation

When a user invokes a trigger, the command implementation—typically found in src/plugins/opencode/commands/—executes the business logic. For skills requiring complex processing, such as caveman-compress, the command delegates to dedicated scripts in the skill's subdirectory:

# Example: skills/caveman-compress/scripts/__main__.py

# This script handles the actual compression workflow,

# backing up originals as .original.md files and

# rewriting content in caveman-style syntax.

This architecture ensures that declarative concerns (what the skill does) remain in SKILL.md, procedural concerns (how it does it) remain in scripts/ or command modules, and documentation (why it exists) remains in README.md.

Skill Implementation Examples

The caveman-compress skill demonstrates the complete implementation pattern. Its SKILL.md defines the compression workflow and safety rules, while the actual Python implementation resides in skills/caveman-compress/scripts/__main__.py. When users invoke /caveman-compress docs/README.md, the system:

1. Parses the trigger from skills/caveman-compress/SKILL.md
2. Routes the command through the Opencode plugin infrastructure
3. Executes scripts/__main__.py to process the file
4. Creates README.original.md as a backup before rewriting the compressed version

Similarly, the caveman-stats skill provides token usage reporting through a lightweight contract that requires no additional scripts—its logic is handled entirely within the command module in src/plugins/opencode/commands/.

Summary

• The Caveman project structures skills as paired SKILL.md and README.md bundles under skills/.
• Each skill is mirrored in plugins/caveman/skills/ to support both core bot and Opencode plugin usage.
• The hooks/*.js engine parses SKILL.md files at startup to register triggers and map slash commands.
• Implementation logic resides in scripts/ subdirectories (for complex skills) or src/plugins/opencode/commands/ (for simple handlers).
• This modular architecture separates declarative contracts, procedural code, and documentation into distinct, maintainable layers.

Frequently Asked Questions

What is the difference between SKILL.md and README.md in the Caveman project?

SKILL.md serves as the machine-readable contract that the bot's hook system consumes to register triggers and understand skill parameters, while README.md contains human-readable documentation, usage examples, and design notes. This separation allows the bot to parse functional requirements programmatically without processing narrative text.

How does the Caveman project automatically detect new skills?

The hook engine in hooks/*.js scans the skills/ directory at startup, parsing each SKILL.md file to extract the trigger command (such as /caveman-stats or /caveman-review) and registration metadata. This eliminates manual registration—adding a new skill directory with a properly formatted SKILL.md automatically makes it available to the bot.

Why are skills duplicated in both /skills and /plugins/caveman/skills?

The skills/ directory contains the canonical source of truth for skill contracts and implementations, while plugins/caveman/skills/ mirrors this structure to expose the same functionality through the Opencode chat interface. This parallel hierarchy allows the plugin to reference skill contracts without duplicating the actual logic or documentation.

How do I add a new skill to the Caveman project?

Create a new subdirectory under skills/ containing both SKILL.md (declaring the trigger and contract) and README.md (documenting usage). If the skill requires complex processing, add a scripts/ directory with the implementation entry point. The hook system will automatically detect the new SKILL.md and register the trigger on the next startup.

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