playbooks

home / skills / pplmx / husky-rs / conventional-commits

conventional-commits skill

/.agent/skills/conventional-commits

This skill enforces conventional commits and PR titles in Rust projects, ensuring readable history and machine-parseable metadata.

npx playbooks add skill pplmx/husky-rs --skill conventional-commits

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.3 KB
---
name: Conventional Commits
description: Ensures all commit messages and PR titles follow the Conventional Commits specification.
---

# Conventional Commits Standard

This skill ensures that project history is clean, readable, and machine-parseable.

## Format Structure

Messages should follow this structure:

```text
<type>(<scope>): <subject>
<空行>
[body]
<空行>
[footer]
```

**Subject Regex**: `^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9-]+\))?!?: .+$`

## Types

- **feat**: A new feature (correlates with MINOR in SemVer).
- **fix**: A bug fix (correlates with PATCH in SemVer).
- **docs**: Documentation only changes.
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
- **refactor**: A code change that neither fixes a bug nor adds a feature.
- **perf**: A code change that improves performance.
- **test**: Adding missing tests or correcting existing tests.
- **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm).
- **ci**: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs).
- **chore**: Other changes that don't modify src or test files.
- **revert**: Reverts a previous commit.

## Extended Content Guidelines

### 1. Body (Optional)

The body provides a place to explain the **why** and **how** of the change. Use it for:

- Explaining the motivation for the change.
- Describing the technical approach or trade-offs.
- Listing multiple related changes in a single commit.

**Rules for Body**:

- Separate from the subject with a blank line.
- Use a blank line between paragraphs.
- Keep lines wrapped at ~72 characters for readability in CLI tools.

### 2. Footer (Optional)

The footer is used for metadata and tracking.

- **Breaking Changes**: Must start with `BREAKING CHANGE:` followed by a description.
- **Issue Tracking**: Reference issues (e.g., `Fixes #123`, `Closes #456`).

## Rules

1. **Imperative Mood**: Use "add feature" instead of "added feature" in the subject.
2. **No Period**: Do not end the subject line with a period.
3. **Lowercase Subject**: Keep the subject line lowercase (except for proper nouns).
4. **Separation**: Always use blank lines between Subject, Body, and Footer.

Overview

This skill enforces the Conventional Commits specification to keep commit messages and PR titles consistent, machine-parseable, and semver-friendly. It runs as a git hook to validate format, types, scopes, and optional body/footer rules so repository history stays clean and automatable. Use it to prevent invalid commit messages from entering the main branch and to standardize metadata for changelogs and CI tooling.

How this skill works

The hook inspects each commit message or proposed PR title against the Conventional Commits regex and rules, verifying type, optional scope, subject formatting, and the presence and structure of optional body and footer sections. It rejects commits that violate imperative mood, trailing periods, uppercase subjects, missing blank-line separation, or incorrect breaking-change and issue-tracking footers. The check runs locally during commit/PR creation, providing actionable error messages and examples to fix violations.

When to use it

  • Enforce consistent commit messages across a team
  • Automate changelog generation and semantic versioning
  • Prevent malformed commits from reaching CI or main branches
  • Ensure PR titles align with commit history and release tooling
  • Adopt Conventional Commits in new or existing projects

Best practices

  • Require atomic commits that clearly describe one change per message
  • Use the provided list of allowed types (feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert)
  • Keep subject concise, in imperative mood, lowercase, and without a trailing period
  • Add an optional body to explain why and how; wrap lines around 72 characters
  • Use footer for BREAKING CHANGE: and issue references like Fixes #123

Example use cases

  • Block commits that don’t match the subject regex before pushing
  • Fail PR title checks in CI if the title isn’t a valid Conventional Commit
  • Enforce breaking-change notation so release tooling bumps major versions correctly
  • Standardize commit history before a big release or open-source migration
  • Prevent noisy or ambiguous changelog entries by mandating scopes and types

FAQ

What exact subject format is required?

Subjects must match the Conventional Commits pattern: type(scope)?: subject using allowed types. Optional scope uses lowercase letters, numbers, and hyphens. The subject must be imperative, lowercase (except proper nouns), and not end with a period.

How are breaking changes represented?

Include a footer starting with BREAKING CHANGE: followed by a clear description. This triggers major-version bumps in semantic-release and similar tools.

Can I combine multiple changes in one commit?

Prefer atomic commits. If you must combine, use the body to list related changes and ensure the subject reflects the dominant change type.