# How to Use `/caveman-commit` to Generate Conventional Commit Messages Under 50 Characters

> Learn how to use caveman-commit to generate conventional commit messages. This tool analyzes staged diffs for concise, effective commit messages under 50 characters.

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

---

**`/caveman-commit`** is a Caveman skill that analyzes staged diffs and outputs Conventional Commit messages with subject lines strictly capped at 50 characters whenever possible.

The `caveman-commit` skill in the **JuliusBrussee/caveman** repository provides a minimalist, LLM-driven approach to generating standardized commit messages. By enforcing strict character limits and Conventional Commit specifications defined in its [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) configuration, it ensures your git history remains readable, scannable, and automation-friendly.

## What Is `/caveman-commit`?

`/caveman-commit` is a **skill**—not a standalone executable—that integrates with the Caveman CLI. When invoked, it reads the current staged diff (or a user-supplied diff), passes it to an LLM with a strict rule set, and returns a formatted commit message as a code block. **Crucially**, the skill outputs only the message text; it does not execute `git commit`, stage files, or amend your repository.

According to the implementation in [`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md), the skill triggers when:
- You type `/caveman-commit` explicitly
- You use phrases like "write a commit"
- Files are staged and Caveman detects the change automatically

## How the 50-Character Limit Is Enforced

The character constraints are hardcoded in the skill's instruction set within [`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md). The LLM follows these non-negotiable rules:

- **Subject line**: Must follow `<type>(<scope>): <imperative summary>`
- **Allowed types**: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`, `build`, `ci`, `style`, `revert`
- **Length**: ≤ 50 characters preferred; 72 characters hard maximum
- **Formatting**: No trailing period; imperative mood; scope is optional

The body section is optional and only included when the "why" is not obvious, for breaking changes, security fixes, data migrations, or reverts. When present, body text wraps at 72 characters.

## Three Ways to Invoke the Skill

### Manual Invocation

Run the skill explicitly when you need a message preview:

```bash
$ caveman /caveman-commit

```

Typical output (≤ 50 characters in the subject line):

```text
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

```

### Automatic Trigger

Caveman detects staged changes and automatically suggests a commit message:

```bash
$ git add src/api/userProfile.ts
$ caveman  # Automatically runs /caveman-commit

```

### CI Pipeline Integration

Capture the output for use in automated workflows:

```bash
MESSAGE=$(caveman /caveman-commit)
echo "$MESSAGE" > .git/COMMIT_MSG
git commit -F .git/COMMIT_MSG

```

## Source Files and Configuration

The skill is wired into the Caveman CLI through TOML metadata and markdown documentation. These files control the behavior and registration of `/caveman-commit`:

- **[`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md)** – Contains the LLM-facing instruction set, type definitions, and character limit rules
- **[`skills/caveman-commit/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/README.md)** – High-level documentation describing the skill's purpose
- **[`commands/caveman-commit.md`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman-commit.md)** – Command-line description displayed by `caveman help`
- **[`commands/caveman-commit.toml`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman-commit.toml)** – TOML metadata that registers the command with the Caveman binary

## Summary

- **`/caveman-commit`** generates Conventional Commit messages by analyzing staged diffs through an LLM constrained by [`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md)
- Subject lines are strictly limited to **50 characters** (hard cap 72) with no trailing periods
- The skill supports **11 commit types**: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`, `build`, `ci`, `style`, and `revert`
- Output is **read-only**—the skill never modifies your repository or executes git commands
- Invocation methods include manual commands, automatic detection on staged changes, and shell scripting for CI pipelines

## Frequently Asked Questions

### Does `/caveman-commit` automatically commit my changes?

No. The skill is deliberately output-only. It prints the formatted commit message to your terminal as a code block and does not run `git commit`, stage files, or perform any repository modifications. You must manually copy the message or redirect it to `git commit -F`.

### What if my changes cannot be summarized in 50 characters?

The skill attempts to keep the subject line under 50 characters but enforces a hard maximum of 72 characters. If the scope and description cannot fit within 50 characters, the LLM will truncate or rephrase while maintaining the imperative mood and Conventional Commit structure.

### Can I customize the commit types or character limits?

Yes, but you must modify the source. The allowed types and length constraints are defined in [`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md). Edit this file to add custom types like `security` or adjust the character caps, then restart the Caveman CLI to load the updated skill instructions.

### How does Caveman know when to run this skill automatically?

The automatic trigger is configured in the skill metadata. When you run the bare `caveman` command and the system detects staged files in your git repository, the CLI invokes the `caveman-commit` skill automatically. This behavior is governed by the command registration in [`commands/caveman-commit.toml`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman-commit.toml) and the detection logic in the main Caveman binary.