# How to Contribute to the Caveman Project: A Complete Guide for Developers

> Learn how to contribute to the Caveman project. Follow our guide to edit files, run tests, and submit pull requests using Conventional Commits. Start contributing today

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-07-04

---

**Contributing to the caveman project requires editing top-level source files such as `skills/*/SKILL.md` or [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), running the verification suite with `npm test`, and submitting pull requests that follow the Conventional Commits format defined in [`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md).**

The caveman repository by JuliusBrussee provides a multi-agent "skill" that compresses AI-agent output into terse caveman-style prose. When you contribute to the caveman project, you work within a unique architecture where top-level source files serve as the source of truth, while CI automatically rebuilds mirrored copies under `plugins/` and `dist/`. This guide maps every contribution type to its specific source file and provides tested workflows for modifying skills, adding agents, and extending compression logic.

## Where to Edit Source Files

All contributions target the **top-level source tree**. The CI system mirrors copies under `plugins/` and `dist/`, so you must never edit those generated directories directly.

### Core Behavior and Skill Definitions

- **Caveman behavior** (intensity, voice, rules): [`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md)
- **Commit-message format**: [`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md)
- **Code-review format**: [`skills/caveman-review/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-review/SKILL.md)
- **Compression logic**: [`skills/caveman-compress/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/SKILL.md) and its `scripts/` folder
- **Quick-reference card**: [`skills/caveman-help/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-help/SKILL.md)
- **New skills**: Create `skills/<name>/SKILL.md` and optional [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md)

### Agent Integration and Automation

- **Cavecrew sub-agent definitions**: `agents/cavecrew-*.md`
- **Auto-activation rules** (Cursor, Windsurf, Cline, Copilot): [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md)
- **Adding new agent support**: Edit the `PROVIDERS` array in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) (see lines 75-90)
- **Per-repo initialization**: [`src/tools/caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js)
- **Claude Code hooks**: `src/hooks/*.js`, `*.sh`, and `*.ps1`
- **Settings utilities**: [`bin/lib/settings.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/lib/settings.js)
- **MCP shrink server**: `src/mcp-servers/caveman-shrink/`

## Step-by-Step Contribution Process

### 1. Pick an Issue or Idea

Browse the repository's "good first issue" label at `https://github.com/JuliusBrussee/caveman/issues?q=label%3A%22good+first+issue%22`, or grep the codebase for `TODO` and `FIXME` markers in `src/hooks/`, `bin/`, and `src/tools/`.

### 2. Fork the Repo and Clone

```bash
git clone https://github.com/<your-username>/caveman.git
cd caveman

```

### 3. Create a Feature Branch

```bash
git checkout -b my-new-feature

```

### 4. Make the Change

**For prose edits**, open the relevant [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) file and update the markdown front-matter and description.

**For new agents**, append a provider object to [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) following the existing pattern at lines 75-90.

**For new skills**, create `skills/<name>/SKILL.md` and reference the "Adding a new skill" section in [`CONTRIBUTING.md`](https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md).

### 5. Run the Test Suite

```bash
npm test
python3 -m unittest tests/test_compress_safety.py
node tests/test_caveman_init.js

```

### 6. Update Documentation

Add rows for new agents in [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md) and [`INSTALL.md`](https://github.com/JuliusBrussee/caveman/blob/main/INSTALL.md), and add slash-command entries in the tables at the top of the README.

### 7. Commit with Conventional Commits

The repository's own skill defines the format in [`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md):

```text
feat(caveman-init): add openclaw detection

```

### 8. Open a Pull Request

- Title must follow Conventional Commit style
- Body must include a "what & why" summary
- Include a "before/after" diff of any [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) changes
- Note that CI will resync the `plugins/` mirrors

### 9. Verify CI Checks

The CI pipeline runs the full test matrix and the [`sync-skill.yml`](https://github.com/JuliusBrussee/caveman/blob/main/sync-skill.yml) workflow to rebuild mirrors. Ensure all checks pass before merging.

## Practical Contribution Examples

### Editing an Existing Skill's Prose

Open the skill definition and modify the markdown:

```bash
code skills/caveman-commit/SKILL.md

```

```yaml
---
name: caveman-commit
description: Generate Conventional Commit messages in caveman style
---

# Your updated text here

```

Run the verification suite:

```bash
npm test

```

### Adding a New Agent to the Installer

Edit [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) and append a provider entry to the `PROVIDERS` array:

```js
{
  id: "foobar",
  label: "Foobar",
  mech: "plugin",
  detect: "command:foobar||dir:$HOME/.foobar",
  profile: "vercel-labs/skills/foobar",
  soft: true,
},

```

Verify detection logic:

```bash
node bin/install.js --list | grep foobar

```

Update the documentation tables in [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md) and [`INSTALL.md`](https://github.com/JuliusBrussee/caveman/blob/main/INSTALL.md) to include the new agent.

### Creating a New Skill from Scratch

```bash
mkdir -p skills/awesome-tool
cat > skills/awesome-tool/SKILL.md <<'EOF'
---
name: awesome-tool
description: A brand-new caveman skill that shortens CLI output
---

# Usage

...
EOF

```

If the skill needs to appear in the Claude Code plugin, update the CI sync path in [`.github/workflows/sync-skill.yml`](https://github.com/JuliusBrussee/caveman/blob/main/.github/workflows/sync-skill.yml).

## Testing Requirements

Every contribution must pass the three-tier verification process:

- **JavaScript suite**: `npm test` covers installer unit and end-to-end tests
- **Python safety**: `python3 -m unittest tests/test_compress_safety.py` validates compression logic
- **Init scripts**: `node tests/test_caveman_init.js` verifies per-repo initialization behavior

The CI pipeline also runs the [`sync-skill.yml`](https://github.com/JuliusBrussee/caveman/blob/main/sync-skill.yml) workflow to ensure that changes to top-level sources correctly rebuild the `plugins/` and `dist/` mirrors.

## Summary

- **Edit top-level only**: Modify `skills/*/SKILL.md`, [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), and `src/` files; never touch `plugins/` or `dist/` directly
- **Agent additions**: Append to the `PROVIDERS` array in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) (lines 75-90) and update documentation tables
- **Skill creation**: Create `skills/<name>/SKILL.md` with proper front-matter, and update [`.github/workflows/sync-skill.yml`](https://github.com/JuliusBrussee/caveman/blob/main/.github/workflows/sync-skill.yml) if needed for Claude Code integration
- **Testing**: Run `npm test`, Python unit tests, and init tests before submitting
- **Commits**: Use Conventional Commits format as defined in [`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md)
- **CI awareness**: Note that the [`sync-skill.yml`](https://github.com/JuliusBrussee/caveman/blob/main/sync-skill.yml) workflow automatically rebuilds mirrors from your top-level changes

## Frequently Asked Questions

### What files should I avoid editing when contributing to the caveman project?

Never edit files under `plugins/` or `dist/` directories. According to the source architecture in JuliusBrussee/caveman, these are CI-generated mirrors. Always edit the top-level source files (such as [`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) or [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)), and the [`sync-skill.yml`](https://github.com/JuliusBrussee/caveman/blob/main/sync-skill.yml) workflow will automatically rebuild the mirrors.

### How do I add support for a new AI agent like Cursor or Windsurf?

To add a new agent, edit [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) and append a provider object to the `PROVIDERS` array (refer to lines 75-90 for the schema). You must also update the [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md) and [`INSTALL.md`](https://github.com/JuliusBrussee/caveman/blob/main/INSTALL.md) tables to document the new support. If the agent requires auto-activation rules, modify [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md) instead.

### What testing is required before submitting a pull request?

You must run the full verification suite: `npm test` for JavaScript components, `python3 -m unittest tests/test_compress_safety.py` for compression safety, and `node tests/test_caveman_init.js` for initialization logic. The CI pipeline will rerun these plus the mirror-sync validation via [`.github/workflows/sync-skill.yml`](https://github.com/JuliusBrussee/caveman/blob/main/.github/workflows/sync-skill.yml).

### Where is the commit message format defined for this repository?

The Conventional Commits format is defined in [`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md). This file specifies how to structure commit messages (e.g., `feat(caveman-init): add openclaw detection`), and the repository uses this definition to validate PR titles and commit history.