# How the caveman-commit Skill Works in JuliusBrussee/caveman

> Discover how the caveman-commit skill generates terse Conventional Commit messages using LLMs and strict formatting rules from SKILL.md without Git operations.

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

---

**The caveman-commit skill generates terse Conventional Commit messages by switching the session into commit mode via the Opencode plugin and feeding the LLM strict formatting rules from SKILL.md, without performing any Git operations.**

The caveman-commit skill in the JuliusBrussee/caveman repository is an independent mode that produces ready-to-paste commit messages following the Conventional Commits specification. Unlike automated Git hooks, this skill operates entirely on the language-model side, parsing slash commands to trigger a specialized prompt template that enforces brevity and clarity. When active, the skill returns only the formatted commit text, leaving all repository operations to the user.

## Mode Detection in the Opencode Plugin

The Opencode plugin ([`src/plugins/opencode/plugin.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/plugin.js)) monitors every user message to detect mode changes. When a message starts with `/caveman-commit`, the `parseModeChange` function returns the string `"commit"`, which `applyModeChange` writes to a per-session flag file.

```javascript
// src/plugins/opencode/plugin.js – lines that map the slash command
if (cmd === '/caveman-commit')   return 'commit';

```

Because *commit* is classified as an **independent mode**, it cannot be selected via the generic `/caveman <level>` command and is treated specially through the `INDEPENDENT_MODES` set. The mode tracker ([`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js)) persists this flag across sessions, keeping the session in commit mode until explicitly disabled.

## Prompt Template and Formatting Rules

When the commit flag is active, the Caveman core loads the skill definition from [`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md). This file contains the system prompt that instructs the LLM on exactly how to format the output.

The rules enforced by the prompt include:

- **Subject line**: Must follow the format `<type>(<scope>): <imperative summary>` and stay under **50 characters** (with a hard cap of 72).
- **Imperative mood**: Use command-style language ("add", "fix", "remove").
- **Optional body**: Only include when the *why* is non-obvious, such as for breaking changes, migrations, or performance optimizations.
- **Prohibited content**: Phrases like "This commit does...", AI attribution, emojis, and redundant file names are forbidden.

The skill explicitly declares that it **does not** run `git commit` or stage files. The resulting message is wrapped in a code block for easy copying.

## Usage Examples

### Simple Feature Commit

Invoking the skill via the command line or chat interface:

```bash
$ caveman-commit

```

The model returns:

```

feat(api): add GET /users/:id/profile

Mobile client needs profile data without the full user payload
to reduce LTE bandwidth on cold‑launch screens.

Closes #128

```

The subject line stays under 50 characters, while the body explains the non-obvious justification regarding bandwidth optimization.

### Breaking Change Format

For changes that break backward compatibility:

```bash
$ /caveman-commit

```

Output:

```

feat(api)!: rename /v1/orders to /v1/checkout

BREAKING CHANGE: clients on /v1/orders must migrate to /v1/checkout
before 2026‑06‑01. Old route returns 410 after that date.

```

The exclamation mark (`!`) after the scope signals a breaking change, and the body contains the mandatory migration instructions.

### Disabling the Skill

To exit commit mode and return to the standard verbose style:

```bash
$ stop caveman-commit

```

This clears the session flag via the mode tracker, reverting subsequent prompts to the default behavior.

## Key Implementation Files

- **[`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md)**: Contains the system prompt and formatting rules.
- **[`skills/caveman-commit/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/README.md)**: User-facing documentation with invocation examples.
- **[`src/plugins/opencode/plugin.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/plugin.js)**: Detects slash commands and sets the mode flag.
- **[`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js)**: Persists the commit mode state across sessions.
- **[`commands/caveman-commit.toml`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman-commit.toml)**: CLI definition for the `caveman-commit` binary command.

## Summary

The caveman-commit skill operates through a four-step process:

- **Detection**: The Opencode plugin identifies `/caveman-commit` or natural language triggers like "write a commit".
- **Activation**: A per-session "commit" flag is set and persisted by the mode tracker.
- **Instruction**: The LLM receives strict formatting rules from [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md), including character limits and imperative mood requirements.
- **Output**: The model returns a ready-to-paste Conventional Commit message, performing no Git operations itself.

## Frequently Asked Questions

### Does the caveman-commit skill execute git commit or stage files?

No. The skill is completely self-contained and operates only on the language-model side. It generates the commit message text but does not interact with the Git repository, stage files, or execute any `git` commands.

### How do I disable the caveman-commit skill?

You can disable the skill by issuing the command `stop caveman-commit`. This clears the per-session flag via the mode tracker ([`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js)), reverting the session to the default Caveman mode.

### What are the character limits for commit messages generated by the skill?

The subject line must be **50 characters or fewer**, with a hard maximum of **72 characters**. The body is optional and should only be included when the reasoning behind the change is not obvious from the subject alone.

### Can I invoke the skill without using the slash command?

Yes. In addition to `/caveman-commit`, the skill recognizes natural language triggers such as "write a commit". These activations are defined in the skill's trigger configuration within [`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md).