# How the Caveman Project Structures Its Skills: A Modular Guide to SKILL.md and README.md Contracts > Discover how the Caveman project structures skills using SKILL.md and README.md for modularity and automatic registration. Learn about clear contracts and documentation. - Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman) - Tags: architecture - Published: 2026-07-03 --- **The Caveman project structures each capability as a self-contained skill using paired [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) and [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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: ```text /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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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: ```python # 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`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md), **procedural** concerns (how it does it) remain in `scripts/` or command modules, and **documentation** (why it exists) remains in [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md). ## Skill Implementation Examples The `caveman-compress` skill demonstrates the complete implementation pattern. Its [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) defines the compression workflow and safety rules, while the actual Python implementation resides in [`skills/caveman-compress/scripts/__main__.py`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/SKILL.md) 2. Routes the command through the Opencode plugin infrastructure 3. Executes [`scripts/__main__.py`](https://github.com/JuliusBrussee/caveman/blob/main/scripts/__main__.py) to process the file 4. Creates [`README.original.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) and [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) (declaring the trigger and contract) and [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) and register the trigger on the next startup.