How the Caveman-Commit Command Generates Short Conventional Commit Messages

The /caveman-commit command generates terse Conventional Commit messages by routing diffs through an LLM constrained by strict formatting rules defined in skills/caveman-commit/SKILL.md.

The caveman-commit command in the JuliusBrussee/caveman repository transforms staged diffs into compact, conventional commit messages through a deterministic LLM-driven pipeline. Unlike generic commit generators, this skill enforces brevity and strict formatting via an explicit rule set rather than relying on model temperature settings. Understanding how the caveman-commit command generates short conventional commit messages reveals a pattern of using structured prompts to constrain LLM outputs for developer tooling.

Triggering the Caveman-Commit Skill

The skill activates when a user types /caveman-commit or includes trigger phrases like "write a commit", "commit message", or "generate commit" in their prompt. According to skills/caveman-commit/README.md, this invocation signals the system to enter "commit" mode and prepare the diff context for processing.

The Rule-Based LLM Prompt Architecture

The core generation logic resides in skills/caveman-commit/SKILL.md, which acts as a contract between the user and the LLM. This file supplies the model with explicit constraints that override default verbose tendencies.

Subject Line Constraints

As specified in lines 14-20 of SKILL.md, the subject line must follow the format <type>(<scope>): <imperative summary>, where type is one of the standard Conventional Commits types such as feat or fix. The rules enforce:

• Length limits: 50 characters preferred, with a hard limit of 72 characters (line 18)
• Style requirements: No trailing periods, no filler phrases like "This commit does...", and strict imperative mood (lines 15-18)

Body Omission and Formatting Rules

The skill aggressively omits the body section unless the change requires explanation. Per lines 22-25 of SKILL.md, the body is included only when the "why" is not obvious, there are breaking changes, migration notes, or issue references. When present, the body must:

• Wrap at 72 characters
• Use dashes for bullet points
• End with issue trailers such as Closes #42 (lines 26-28)

Explicit Exclusions

To maintain professionalism and neutrality, SKILL.md explicitly forbids specific patterns. Lines 30-31 prohibit phrases like "This commit does X", first-person pronouns, and "As requested by...". Line 32 forbids AI attribution (e.g., "Generated with Claude Code"), while line 33 excludes emojis unless project conventions specifically require them.

The Execution Pipeline

The command flows through four distinct architectural components before returning the final message.

Command Parsing and Routing

The src/plugins/opencode/plugin.js file detects the /caveman-commit invocation and routes the request to the "commit" mode handler. This component extracts the diff context and prepares it for the skill engine.

Mode Tracking and Skill Lifecycle

The src/hooks/caveman-mode-tracker.js manages the skill's activation state, ensuring the LLM is called only when the user is explicitly in commit mode. This prevents accidental commit message generation during unrelated conversations.

LLM Generation and Output Formatting

The LLM (Claude, Gemini, etc.) receives the diff alongside the rule set from SKILL.md. As noted in lines 9-10 of the skill documentation, the system returns only the formatted commit message as plain text within a code block, without executing git commit or adding conversational filler.

Practical Usage Examples

Basic Commit Generation

/caveman-commit

When executed with staged changes, the command returns a compact message like:

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

Handling Breaking Changes

For breaking changes, the skill automatically includes the ! marker and BREAKING CHANGE footer:

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.

Summary

• The caveman-commit command uses skills/caveman-commit/SKILL.md to enforce strict formatting rules on LLM outputs
• Subject lines follow <type>(<scope>): <imperative summary> with a 50-character soft limit and 72-character hard limit
• Body text is omitted by default unless breaking changes, migration notes, or issue references are present
• The pipeline routes through src/plugins/opencode/plugin.js and src/hooks/caveman-mode-tracker.js before LLM processing
• Output excludes AI attribution, emojis, and first-person pronouns to maintain professional standards

Frequently Asked Questions

What is the maximum length for commit messages generated by caveman-commit?

The subject line prefers 50 characters with a hard limit of 72 characters as defined in skills/caveman-commit/SKILL.md line 18. When included, the body wraps at 72 characters per line.

Does caveman-commit automatically execute git commit?

No. According to lines 9-10 of the skill specification, the command returns only the formatted message as plain text in a code block. The user must manually paste and execute the commit.

How does caveman-commit handle breaking changes?

The skill detects breaking changes and prepends the ! indicator to the type/scope (e.g., feat(api)!:). It also includes a BREAKING CHANGE: footer in the body when migration notes or compatibility warnings are required, following the Conventional Commits specification.

Can I customize the excluded phrases or allowed emojis in caveman-commit?

The current rule set in SKILL.md hardcodes exclusions for first-person pronouns (lines 30-31), AI attribution (line 32), and emojis (line 33). Customization would require modifying the skill file in skills/caveman-commit/SKILL.md to adjust the constraint parameters for your specific project conventions.

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