How caveman-commit Generates Terse Conventional Commit Messages

The /caveman-commit skill in the JuliusBrussee/caveman repository constrains an LLM via a strict rule set in SKILL.md to produce compact Conventional Commits, enforcing 50-character subject lines and omitting superfluous body text.

The JuliusBrussee/caveman project implements an LLM-driven coding assistant that transforms git diffs into disciplined version control messages. Understanding how caveman-commit generates terse conventional commit messages reveals a deterministic pipeline where rigid prompt engineering in skills/caveman-commit/SKILL.md constrains the model to include only essential information. This approach eliminates verbose explanations while strictly adhering to the Conventional Commits specification through explicit exclusions and character limits.

Core Mechanics

The skill operates through a series of enforced constraints defined in skills/caveman-commit/SKILL.md. These rules act as a contract that guarantees consistency and brevity across all generated messages.

Triggering and Activation

The skill activates when a user invokes the slash command /caveman-commit or uses trigger phrases such as "write a commit", "commit message", or "generate commit" within the prompt. According to the documentation in skills/caveman-commit/README.md, the system detects these inputs and routes the request to the commit generation mode managed by the mode tracker.

Subject Line Constraints

The LLM must generate a subject line following the exact format <type>(<scope>): <imperative summary>, where type is one of feat, fix, docs, style, refactor, test, or chore. The SKILL.md file imposes strict length discipline:

• 50 characters is the recommended soft limit
• 72 characters is the absolute hard limit
• No trailing periods allowed
• Imperative mood required (e.g., "add" not "added")
• No fluff phrases like "This commit does..."

Body Handling Rules

The skill omits the body entirely unless the "why" behind the change is non-obvious, breaking changes exist, migration notes are required, or issue references need inclusion. When present, the body must follow exact formatting defined in the skill specification:

• Wrapped at 72 characters
• Uses dashes for bullet points
• Ends with issue trailers such as Closes #42

Explicit Exclusions

SKILL.md explicitly forbids several common LLM tendencies that add verbosity:

• First-person pronouns and phrases like "As requested by..."
• AI attribution comments (e.g., "Generated with Claude Code")
• Emoji unless project conventions specifically require them

Architectural Flow

The generation process follows a deterministic pipeline across four main components:

1. Command Parser (src/plugins/opencode/plugin.js) - Detects /caveman-commit and routes to commit mode
2. Mode Tracker (src/hooks/caveman-mode-tracker.js) - Maintains skill state during interaction to ensure the LLM is called only for this mode
3. Skill Engine (skills/caveman-commit/SKILL.md) - Supplies the LLM with the rule set and constraints
4. LLM Output - Returns only the formatted message as plain text ready to paste (no git commit execution)

The heavy lifting is performed by the LLM (Claude, Gemini, etc.), but the skill file acts as the deterministic contract ensuring consistency across different models and contexts.

Usage Examples

Command Line Invocation

Invoke the skill directly:

/caveman-commit

The skill automatically reads the staged diff and returns a compact message:

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

Natural Language Prompts

You can also trigger generation with descriptive prompts:

Please write a commit for the new endpoint that returns user profiles.

This produces the same terse output, demonstrating that the SKILL.md constraints apply regardless of input method.

Breaking Change Handling

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.

Key Implementation Files

The behavior is defined across these specific files in the repository:

• skills/caveman-commit/SKILL.md - Contains the full rule set governing LLM output format, length limits, and exclusions
• skills/caveman-commit/README.md - Documents triggering phrases and high-level behavior
• src/plugins/opencode/plugin.js - Implements command detection and routing to the commit mode
• src/hooks/caveman-mode-tracker.js - Manages the skill lifecycle during user sessions
• commands/caveman-commit.md - User-facing documentation for CLI usage

Summary

• /caveman-commit is an LLM-driven skill that transforms diffs into compact Conventional Commits
• Subject lines must follow <type>(<scope>): <imperative summary> with a 50-character soft limit and 72-character hard limit
• Body text is omitted unless necessary for context, breaking changes, or issue references, and wraps at 72 characters
• Exclusions prevent AI attribution, first-person pronouns, and unnecessary fluff
• Architecture relies on src/plugins/opencode/plugin.js for command parsing and skills/caveman-commit/SKILL.md for rule enforcement

Frequently Asked Questions

What is the maximum length for a caveman-commit subject line?

The skill enforces a 50-character soft limit with a 72-character hard limit for subject lines. This constraint is defined in skills/caveman-commit/SKILL.md and ensures the summary remains readable in standard git log outputs while following Conventional Commits best practices.

Does caveman-commit automatically execute git commit commands?

No. According to the README.md in skills/caveman-commit/, the skill returns only the formatted commit message as plain text ready to paste. It does not execute git commit or modify the repository. The user must manually paste the generated message into their commit workflow.

How does caveman-commit handle breaking changes?

When the diff or prompt indicates a breaking change, the skill automatically prepends a ! to the type-scope combination (e.g., feat(api)!:) and includes a BREAKING CHANGE: footer in the body. This follows the Conventional Commits specification for denoting incompatible API modifications.

Can I customize the commit message rules in caveman-commit?

The rules are defined in skills/caveman-commit/SKILL.md, which acts as the system prompt for the LLM. Modifying this file would change the constraints, though the default configuration is optimized for brevity and standard Conventional Commits compliance across most development workflows.

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