OpenClaw Conventional Commits: Generate Perfect Commit Messages with AI

Conventional Commits (#10 with 450 stars) generates properly formatted commit messages from your staged git changes, ensuring consistency across your team’s commit history. Well-structured commit messages enable automated changelog generation, semantic versioning, and easier code review. Instead of writing vague messages like “fix stuff” or “update code”, OpenClaw analyzes your changes and generates precise, descriptive commits that follow the Conventional Commits specification.

This guide covers installation, commit message generation, team workflow integration, and changelog automation.

Why Conventional Commits Matter

Conventional Commits is a lightweight specification for commit messages that provides a structured format for describing changes. When followed consistently, it enables powerful automation:

Automated changelog generation: Tools like standard-version and semantic-release read commit messages and generate changelogs automatically by grouping features, bug fixes, and breaking changes.

Semantic versioning automation: Based on commit types (feat, fix, BREAKING CHANGE), version numbers increment automatically following SemVer rules.

Easier code review: Reviewers immediately understand the nature of each commit (bug fix, new feature, refactor) without reading the diff.

Better git history: Structured messages create a scannable, searchable history that helps with debugging and understanding code evolution.

The Conventional Commits format has become the de facto standard for open-source projects and is increasingly adopted by teams looking to improve their Git workflows.

Commit Message Format

Conventional Commits follow this structure:

<type>(<scope>): <subject>

[optional body]

[optional footer(s)]

Components:

• type (required): Describes the category of change

  • feat: New feature
  • fix: Bug fix
  • refactor: Code change that neither fixes a bug nor adds a feature
  • docs: Documentation changes
  • test: Adding or updating tests
  • chore: Maintenance tasks (dependencies, build config)
  • perf: Performance improvements
  • style: Code style changes (formatting, semicolons)

• scope (optional): Component or module affected (e.g., auth, api, ui)

• subject (required): Short description in imperative mood (“add feature” not “added feature”)

• body (optional): Detailed explanation of the change and motivation

• footer (optional): Breaking changes, issue references

Examples:

feat(auth): add OAuth2 login support

fix(api): handle null user session in /profile endpoint

refactor(ui): extract validation logic to separate module

docs(readme): update installation steps for Windows

test(auth): add edge cases for password reset flow

chore(deps): upgrade react from 17.0.2 to 18.2.0

Installation

Install Conventional Commits skill:

openclaw skill install conventional-commits

No additional configuration required. The skill works with any Git repository.

Verify installation:

# Stage some changes
git add .

# In your chat interface:
"Generate commit message"

# Expected: OpenClaw analyzes diff and returns formatted message

Basic Usage

Generating Commit Messages

Standard workflow:

# 1. Make changes to your code
# 2. Stage changes
git add src/auth/login.ts

# 3. Ask OpenClaw to generate message

In chat:

"Generate commit message for my staged changes"

# OpenClaw response:
# feat(auth): add remember-me functionality to login form
#
# Adds checkbox and cookie handling for persistent sessions.
# Expires after 30 days for security.
#
# Closes #234

Review and use:

git commit -m "feat(auth): add remember-me functionality to login form"

Or use the full message with body:

git commit -F - <<EOF
feat(auth): add remember-me functionality to login form

Adds checkbox and cookie handling for persistent sessions.
Expires after 30 days for security.

Closes #234
EOF

How It Works (Technical)

OpenClaw’s commit message generation process:

1. Read git diff: Retrieves staged changes using git diff --cached
2. Analyze changes: LLM examines:
   • Changed files and paths (determines scope)
   • Added/removed/modified code (determines type)
   • Function and variable names (extracts context)
   • Comments and documentation (understands intent)
3. Classify change type: Determines if feat, fix, refactor, etc.
4. Extract scope: Identifies affected component from file paths
5. Generate subject: Creates concise, imperative description
6. Add body/footer: Includes details for complex changes

The LLM is context-aware and learns from your repository’s existing commit history to match your team’s style.

Advanced Features

Breaking Change Detection

OpenClaw automatically detects breaking changes:

Changed: Removed deprecated `getUserById()` method
Replaced with: `getUser()` which requires authentication

# Generated message:
feat(api)!: replace getUserById with authenticated getUser

BREAKING CHANGE: getUserById() has been removed. Use getUser() with auth token instead.

Migration guide:
- Old: getUserById(123)
- New: getUser(123, { authToken: token })

The ! after type signals a breaking change, and the footer provides migration details.

Multi-Scope Commits

When changes affect multiple components:

Staged changes:
- src/auth/login.ts (authentication logic)
- src/ui/LoginForm.tsx (UI component)
- docs/auth.md (documentation)

# Generated message:
feat(auth,ui): add OAuth2 login support

Implements OAuth2 flow for Google and GitHub providers.
Updates UI with provider selection buttons.
Documents setup process in auth.md.

Custom Type Definitions

Configure additional commit types for your team:

skills:
  conventional-commits:
    types:
      - type: "feat"
        description: "New feature"
      - type: "fix"
        description: "Bug fix"
      - type: "security"
        description: "Security patch"
        emoji: "🔒"
      - type: "deps"
        description: "Dependency update"
        emoji: "⬆️"

Then:

"Generate commit for dependency update"
→ deps(package): upgrade express from 4.17 to 4.18

Message Refinement

Refine generated messages through conversation:

Initial: "Generate commit message"
→ feat(api): add user endpoint

You: "Make it more specific, mention the GET method"
→ feat(api): add GET /users endpoint for user listing

You: "Add that it supports pagination"
→ feat(api): add paginated GET /users endpoint

Supports page and limit query parameters.

Rewriting Existing Messages

Fix old commit messages:

"Rewrite this commit message following Conventional Commits:
'fixed the thing where users couldnt login'"

# OpenClaw response:
fix(auth): resolve login failure for users with special characters in passwords

Escapes special characters in password field before validation.

Team Workflow Integration

Pre-Commit Hooks

Automate message generation with Git hooks:

# .git/hooks/prepare-commit-msg
#!/bin/bash

# Only for regular commits (not merges, rebases)
if [ "$2" != "message" ]; then
  # Generate message via OpenClaw
  openclaw-cli commit-message > "$1"
fi

Make executable:

chmod +x .git/hooks/prepare-commit-msg

Now every git commit automatically generates a Conventional Commit message.

CI/CD Integration for Validation

Validate commit messages in CI:

# .github/workflows/commit-lint.yml
name: Lint Commits

on: [push, pull_request]

jobs:
  commitlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: wagoid/commitlint-github-action@v5
        with:
          configFile: .commitlintrc.json

Configure commitlint:

{
  "extends": ["@commitlint/config-conventional"],
  "rules": {
    "type-enum": [2, "always", [
      "feat", "fix", "docs", "style", "refactor",
      "test", "chore", "perf", "security", "deps"
    ]],
    "scope-case": [2, "always", "kebab-case"],
    "subject-case": [2, "always", "lower-case"]
  }
}

Team Conventions and Custom Types

Define team-specific rules:

skills:
  conventional-commits:
    # Enforce scopes for certain types
    scope_required_for: ["feat", "fix", "perf"]

    # Valid scopes for this project
    allowed_scopes:
      - "auth"
      - "api"
      - "ui"
      - "db"
      - "infra"

    # Custom templates
    templates:
      security:
        type: "security"
        footer: "Security-Impact: {impact}"
        body_required: true

Changelog Automation

Using standard-version

Generate changelogs automatically:

npm install -D standard-version

# package.json
{
  "scripts": {
    "release": "standard-version"
  }
}

Run release:

npm run release

# Output:
# - Bumps version based on commits (feat = minor, fix = patch)
# - Generates CHANGELOG.md from commits
# - Creates git tag
# - Commits changes

Example changelog (auto-generated):

# Changelog

## [1.2.0] - 2026-02-25

### Features
- **auth**: add OAuth2 login support ([abc123])
- **api**: add paginated GET /users endpoint ([def456])

### Bug Fixes
- **ui**: resolve layout shift on mobile devices ([ghi789])

### Performance
- **db**: optimize user query with index ([jkl012])

Using semantic-release

For fully automated releases:

npm install -D semantic-release

# .releaserc.json
{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github"
  ]
}

On merge to main:

1. Analyzes commits since last release
2. Determines new version number
3. Generates changelog
4. Publishes to npm
5. Creates GitHub release with notes

GitHub Releases Integration

Auto-generate release notes:

Commits since v1.1.0:
- feat(auth): add OAuth2 login
- fix(api): handle null sessions
- docs(readme): update examples

# OpenClaw generates:
## What's New in v1.2.0

### Features
- OAuth2 login support for Google and GitHub providers

### Bug Fixes
- Fixed null session handling in profile API

### Documentation
- Updated README with new installation examples

Full changelog: v1.1.0...v1.2.0

Common Patterns

Frontend Changes

Modified: src/components/Button.tsx
Added dark mode support

# Generated:
feat(ui): add dark mode toggle to button component

Supports light, dark, and auto modes based on system preference.

Backend API

Modified: src/api/users.ts
Fixed crash when user email is null

# Generated:
fix(api): handle null user email in GET /profile

Adds null check and returns 400 if email is missing.
Prevents server crash on malformed user data.

Documentation

Modified: README.md, docs/installation.md
Updated setup steps for Windows

# Generated:
docs(readme): update installation steps for Windows

Adds Windows-specific instructions for Node.js and npm setup.
Clarifies path requirements and common errors.

Refactoring

Modified: src/utils/validation.ts
Extracted email validation to separate function

# Generated:
refactor(utils): extract email validation logic

Moves email regex and validation to reusable validateEmail() function.
No behavior changes, improves testability.

FAQ

Can I customize the commit types?

Yes. Configure custom types in your OpenClaw settings:

skills:
  conventional-commits:
    types:
      - type: "feat"
      - type: "fix"
      - type: "wip"
        description: "Work in progress"
      - type: "release"
        description: "Release preparation"

Does this work with monorepos?

Yes. For monorepos, use package names as scopes:

feat(web-app): add dark mode
fix(api-server): handle auth errors
chore(shared-utils): upgrade lodash

Configure package-to-scope mapping:

skills:
  conventional-commits:
    monorepo:
      packages:
        apps/web: "web-app"
        apps/api: "api-server"
        packages/utils: "shared-utils"

How do I handle commits that touch multiple areas?

For commits affecting multiple unrelated areas, either:

1. Split into separate commits (preferred):

   git add src/auth/*.ts
   git commit -m "feat(auth): add OAuth2"
   
   git add src/ui/*.tsx
   git commit -m "feat(ui): add login button"

2. Use multiple scopes:

   feat(auth,ui): implement OAuth2 login flow
   
   Adds OAuth2 backend and updates UI with login button.

3. Omit scope for very broad changes:

   chore: upgrade all dependencies to latest versions

Next Steps

Once Conventional Commits is configured, explore these enhancements:

• Combine with GitHub Issue Triage for full DevOps workflow automation
• Use with Linear Project Manager to link commits to issues
• Review the Top 10 Skills guide for complete skills overview
• Check the Conventional Commits skill details for updates

Conventional Commits transforms git history from a cryptic log into a structured, searchable record of your project’s evolution. Combined with automated changelog generation, it saves hours of manual release note writing while ensuring consistency across your team.