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

Contributing to the caveman project requires editing top-level source files such as skills/*/SKILL.md or 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.

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
• Commit-message format: skills/caveman-commit/SKILL.md
• Code-review format: skills/caveman-review/SKILL.md
• Compression logic: skills/caveman-compress/SKILL.md and its scripts/ folder
• Quick-reference card: skills/caveman-help/SKILL.md
• New skills: Create skills/<name>/SKILL.md and optional 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
• Adding new agent support: Edit the PROVIDERS array in bin/install.js (see lines 75-90)
• Per-repo initialization: src/tools/caveman-init.js
• Claude Code hooks: src/hooks/*.js, *.sh, and *.ps1
• Settings utilities: 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

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

3. Create a Feature Branch

git checkout -b my-new-feature

4. Make the Change

For prose edits, open the relevant SKILL.md file and update the markdown front-matter and description.

For new agents, append a provider object to 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.

5. Run the Test Suite

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 and 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:

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

code skills/caveman-commit/SKILL.md

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

# Your updated text here

Run the verification suite:

npm test

Adding a New Agent to the Installer

Edit bin/install.js and append a provider entry to the PROVIDERS array:

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

Verify detection logic:

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

Update the documentation tables in README.md and INSTALL.md to include the new agent.

Creating a New Skill from Scratch

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.

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 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, and src/ files; never touch plugins/ or dist/ directly
• Agent additions: Append to the PROVIDERS array in 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 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
• CI awareness: Note that the 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 or bin/install.js), and the 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 and append a provider object to the PROVIDERS array (refer to lines 75-90 for the schema). You must also update the README.md and INSTALL.md tables to document the new support. If the agent requires auto-activation rules, modify 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.

Where is the commit message format defined for this repository?

The Conventional Commits format is defined in 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.

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