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

/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 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, 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. 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:

$ caveman /caveman-commit

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

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:

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

CI Pipeline Integration

Capture the output for use in automated workflows:

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 – Contains the LLM-facing instruction set, type definitions, and character limit rules
• skills/caveman-commit/README.md – High-level documentation describing the skill's purpose
• commands/caveman-commit.md – Command-line description displayed by caveman help
• 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
• 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. 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 and the detection logic in the main Caveman binary.

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