conventional-commits

Files (1)

• SKILL.md

SKILL.md (first lines)

# Conventional Commits

Use this skill to draft or review one commit message. Apply Conventional Commits v1.0.0 first, then report repository-specific style concerns separately.

## When to Use

Use this skill when you need to:

- draft a commit message from a change description;
- classify a change by its primary purpose;
- review a proposed commit message;
- explain a type, scope, footer, or breaking-change marker;
- suggest a corrected message without inventing technical details.

Do not use this skill for commit-history intervals, churn metrics, architectural convergence, release automation, or changelog generation. Use `git-history-interval-study` for history analysis and `adr-distillation` for enduring architectural decisions.

## Message Format

```text
<type>[optional scope][!]: <description>

[optional body]

[optional footer(s)]
```

The header requires a type, the `: ` separator, and a non-empty description. A scope is optional and normally names the affected area. A body and footers are optional and follow a blank line.

Examples:

```text
feat(export): add GeoJSON output

fix(auth)!: reject expired sessions

docs: clarify installation steps

fix(parser): handle empty input

Refs: #123
Reviewed-by: Example User
Change-Id: Iabc123
BREAKING CHANGE: callers must pass an explicit format
```

Do not require a scope, body, or footer when the message is otherwise valid.

## Default Type Taxonomy

Use the change's primary purpose. Recommend separate commits when independent changes can be separated.

| Type | Use for |
|---|---|
| `feat` | A new user- or system-facing capability |
| `fix` | Incorrect, unintended, or failing behavior |
| `perf` | A performance or resource-use improvement |
| `refactor` | Behavior-preserving restructuring |
| `docs` | Documentation-only changes |
| `test` | Test-only changes |
| `build` | Build tools, dependencies, or packaging |
| `ci` | Continuous-integration or delivery configuration |
| `style` | Non-functional formatting or style |
| `chore` | Maintenance not covered by a more specific type |
| `revert` | Reversal of an earlier commit |

Conventional Commits gives normative meaning to `feat` and `fix`. The remaining types are an allowed project taxonomy and may be overridden by repository guidance.

When categories overlap, choose the primary purpose:

- use `perf` when performance is the main objective, otherwise `refactor`;
- use `fix` when correcting runtime behavior is the main objective, otherwise `build` for dependency or packaging work;
- use `ci` for delivery automation and `test` for tests or test behavior;
- use `docs` for documentation content and `build` or `ci` when documentation automation is the main change.

## Breaking Changes

A breaking change may be marked in the header:

```text
refactor(api)!: replace the response contract
```

or in a footer:

```text
refactor(api): replace the response contract

BREAKING CHANGE: clients must use the new response fields
```

Both forms may be used together. Recognize `BREAKING CHANGE:` and `BREAKING-CHANGE:`. A breaking change may accompany any type.

Treat the breaking-change token as the uppercase special footer form. General type casing may be accepted by a standards-oriented review, but lowercase types remain the repository style recommendation.

## Bodies and Footers

Use a body when context, motivation, or consequences need explanation. Use footers for issue references, acknowledgments, metadata, or breaking-change details.

Valid footer shapes include:

```text
Token: value
Token #value
```

Ordinary footer tokens must not contain whitespace. Use a hyphen for multiword tokens, such as `Reviewed-by`. `BREAKING CHANGE` is the special exception.

Do not claim that `Fixes`, `Refs`, `Closes`, or other issue-reference tokens are required by Conventional Commits. Preserve repository-specific footer conventions when they exist.

## Drafting Workflow

1. Identify the change's primary purpose.
2. Select the most specific applicable type.
3. Add a useful scope when the affected area is known.
4. Mark a breaking change with `!`, a breaking footer, or both.
5. Write a concise description after `: `.
6. Add a body or footer only when it adds necessary context.
7. Ask for clarification instead of inventing technical details.

From AndrewBrown-USDA/aigb-skills-usda, MIT.

More from AndrewBrown-USDA/aigb-skills-usda