Conventional Commits Skill for OpenClaw

OpenClaw Conventional Commits Skill Overview

The Conventional Commits skill brings structured, spec-compliant commit messaging to your OpenClaw workflow. Instead of writing commit messages from scratch or trying to remember the Conventional Commits specification, you simply ask your OpenClaw agent to generate or validate messages based on your staged changes.

Conventional Commits is a lightweight convention on top of commit messages that provides a clear, machine-readable history. It powers automated changelogs, semantic versioning, and release tooling across thousands of open-source and enterprise projects. With this OpenClaw skill, you get all those benefits without the cognitive overhead.

Typical workflow:

1. Stage your changes with git add.
2. Ask OpenClaw to write a commit message.
3. The agent analyzes the diff, determines the correct type (feat, fix, docs, etc.), and proposes a properly formatted message — ready to commit.

Prerequisites for Conventional Commits Skill

Before installing the Conventional Commits skill, make sure you have:

• OpenClaw installed and running (v1.0+)
• Git installed (v2.20+) — official download
• A project repository initialized with git init
• clawhub CLI installed for skill management

Verify your setup:

# Check OpenClaw version
openclaw --version

# Check Git version
git --version

# Confirm you are inside a Git repository
git status

How to Install the Conventional Commits Skill

Install the Conventional Commits skill with a single command:

npx clawhub@latest install conventional-commits

To verify the installation:

clawhub list

You should see conventional-commits in the list of installed skills. The skill works immediately — no API keys or external services required.

Conventional Commits Skill Configuration

This skill requires minimal configuration. It reads your staged Git changes and formats messages according to the Conventional Commits spec. However, you can customize its behavior to match your team's conventions.

Commit Types

The skill recognizes the standard Conventional Commits types:

| Type | When to Use | |------|------------| | feat | A new feature for the user | | fix | A bug fix | | docs | Documentation-only changes | | style | Formatting, missing semicolons (no logic change) | | refactor | Code restructuring without feature or fix | | perf | Performance improvements | | test | Adding or updating tests | | chore | Build process, dependency updates, tooling | | ci | CI/CD configuration changes |

Scoped Commits

The skill supports scoped commit messages for monorepos and larger projects:

feat(auth): add OAuth2 login flow
fix(api): handle null response from payment endpoint
docs(readme): update installation instructions

You can define allowed scopes in your project's configuration to keep them consistent across contributors.

Conventional Commits Skill Usage Examples

1. Generate a Commit Message from Staged Changes

You: "Write a commit message for my staged changes."

The agent inspects git diff --staged, identifies that you added a new API endpoint, and returns:

feat(api): add user profile endpoint

Implement GET /api/users/:id/profile with authentication
middleware and response caching.

You can accept, edit, or ask the agent to regenerate with a different tone or scope.

2. Validate an Existing Commit Message

You: "Check if this commit message follows the convention: 'Updated the login page'"

The agent analyzes the message and responds with specific feedback:

• Missing type prefix — should start with feat:, fix:, or another valid type
• Uses past tense ("Updated") — the convention recommends imperative mood ("update")
• Suggested fix: fix(auth): update login page layout

3. Batch-Validate Recent Commits

You: "Validate the last 10 commit messages on this branch."

The agent runs through your recent history and flags any commits that do not follow the convention, providing corrected alternatives for each. This is useful before merging a feature branch into main.

4. Generate a Breaking Change Commit

You: "Commit this as a breaking change — we removed the v1 API."

The agent formats a proper breaking change commit:

feat(api)!: remove deprecated v1 endpoints

BREAKING CHANGE: All /api/v1/* routes have been removed.
Consumers must migrate to /api/v2/* before upgrading.

The ! suffix and BREAKING CHANGE footer are both included, ensuring compatibility with tools like semantic-release and standard-version.

Security & Best Practices

The Conventional Commits skill is one of the safest skills in the OpenClaw ecosystem — it operates purely on text formatting and validation with no external API calls or write operations beyond your local Git repository.

Follow these guidelines for the best experience:

• Review before committing. Always read the generated message before accepting it. The agent infers intent from diffs, but you know the context best.
• Use consistent scopes. Define a list of allowed scopes for your project and share it with your team to prevent scope drift.
• Pair with CI validation. Tools like commitlint can enforce Conventional Commits in your CI pipeline, catching any manual commits that skip the skill.
• Enable pre-commit hooks. Use husky or lefthook to run commit message validation automatically.

Troubleshooting Common Errors

"Not a git repository"

The skill requires you to be inside a Git-initialized directory.

# Initialize a new repository
git init

# Or navigate to your existing project
cd /path/to/your/project

"No staged changes found"

The skill needs staged changes to generate a meaningful commit message.

# Stage specific files
git add src/feature.ts

# Or stage all changes
git add -A

"Unable to determine commit type"

This can happen when the diff is very large or touches many unrelated files. Try staging smaller, focused changesets or specify the type manually:

You: "Write a refactor commit message for these changes."