How to Use the caveman-commit Skill for Conventional Commit Generation

The caveman-commit skill generates Conventional Commit messages from staged diffs or natural language prompts via the /caveman-commit slash command, outputting formatted text without executing git commands.

The caveman-commit skill is a self-contained commit message generator distributed within the JuliusBrussee/caveman repository. Located in the skills/caveman-commit directory, it transforms git diffs or descriptive text into standardized Conventional Commit messages. The skill operates entirely through LLM instructions defined in its source files, ensuring consistent formatting across projects without performing any actual git operations.

Activating the caveman-commit Skill

Slash Command Invocation

The primary interface is the /caveman-commit slash command registered in the global help table via skills/caveman-help/SKILL.md. When invoked, the skill reads the staged diff or provided context and returns a formatted message ready for manual commit.

/caveman-commit

Natural Language Triggers

The skill activates on conversational phrases without requiring the slash command. According to the instruction set in skills/caveman-commit/SKILL.md, trigger phrases include "write a commit", "commit message", or "generate commit".

Please write a commit for the new user-profile endpoint.

Architecture and Source Files

The skill's deterministic behavior is defined across three authoritative files:

• skills/caveman-commit/SKILL.md – Contains the front-matter (name, description) and the complete LLM-facing instruction set. This file defines trigger phrases, formatting rules, and the strict boundary that the skill only generates messages without running git commit.
• skills/caveman-commit/README.md – Provides human-readable documentation explaining the skill's purpose and usage examples.
• skills/caveman-help/SKILL.md – Registers the /caveman-commit command in the UI help table, enabling discoverability.

Conventional Commit Format Requirements

The skill enforces strict Conventional Commit standards as defined in its SKILL.md instruction set.

Subject Line Rules

The subject must follow the format <type>(<scope>): <imperative summary>. The implementation enforces a hard limit of 72 characters, with a strong preference for ≤50 characters when possible.

Body Content Logic

The body is intentionally omitted unless the change motivation is non-obvious, a breaking change exists, or additional context (such as security fixes or migration notes) is required. This keeps the output minimal and scannable.

Usage Examples

Standard Feature Commit

When processing a diff for a new API endpoint, the skill outputs:

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 output appears as a markdown code block for direct copy-paste into your terminal.

Breaking Change Detection

When the diff or prompt indicates a breaking change, the skill automatically appends the ! marker after the scope and includes a BREAKING CHANGE: trailer in the body.

Input:

Rename the old orders API to the new checkout API.

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.

Safety and Composability Design

The caveman-commit skill maintains strict no side effects boundaries. As implemented in skills/caveman-commit/SKILL.md, it only outputs markdown-formatted code blocks containing the commit message. It never stages files, executes git commit, or amends existing history. This design ensures the skill remains safe to run in any repository state and composable with other automation workflows.

Summary

• The caveman-commit skill generates Conventional Commit messages via /caveman-commit command or natural language triggers like "write a commit".
• Source instructions live in skills/caveman-commit/SKILL.md with UI integration through skills/caveman-help/SKILL.md.
• Enforces strict 72-character limits and standard <type>(<scope>) formatting per Conventional Commit specifications.
• Automatically handles breaking changes with ! notation and BREAKING CHANGE trailers when detected.
• Produces only text output without executing git commands, ensuring safe, composable operation.

Frequently Asked Questions

How do I trigger the caveman-commit skill?

You can invoke the skill using the /caveman-commit slash command or by using natural language phrases like "write a commit" or "generate commit message" in your prompt. The skill detects these triggers via the instruction set defined in skills/caveman-commit/SKILL.md, processing either staged diffs or your provided description.

What commit format does caveman-commit use?

The skill generates messages following the Conventional Commit specification with the format <type>(<scope>): <imperative summary>. It enforces a hard limit of 72 characters for the subject line and automatically adds breaking change indicators when detected in the diff or description, ensuring consistent project history.

Does caveman-commit execute git commands?

No. The skill is designed with a strict no-side-effects policy as defined in its source code at skills/caveman-commit/SKILL.md. It only generates and outputs the commit message text within a markdown code block. You must manually copy the output and run git commit yourself, ensuring full control over the commit process.

Where is the caveman-commit skill configuration stored?

The behavioral configuration and LLM instructions reside in skills/caveman-commit/SKILL.md within the JuliusBrussee/caveman repository. This file contains the complete instruction set including trigger phrases, formatting rules, and the explicit restriction against executing git commands, making the skill self-contained and portable.

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