# Conventional Branch

> Generate and validate Git branch names using the Conventional Branch specification (v1.1.0). Use when creating a branch, naming a branch, running git checkout -b / git switch -c, starting work on a feature/bugfix/hotfix/release/chore, or verifying whether a branch name is valid. Produces lowercase, prefixed names like feature/add-login-page, fix/header-bug, or release/v1.2.0.

- Skill: `open-sdr/conventional-branch` (Agent Skill)
- Install (CLI): `npx skillmds@latest add open-sdr/conventional-branch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/open-sdr/conventional-branch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: open-sdr (https://skillmd.com/u/open-sdr)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/open-sdr/conventional-branch

---


# Conventional Branch Naming

Produce Git branch names that follow the [Conventional Branch v1.1.0](https://conventionalbranch.org/) specification: a `<type>/<description>` structure that is human- and machine-readable.

## When to Use

- Creating a new branch (`git checkout -b`, `git switch -c`, `git branch`).
- Deciding what to call a branch before starting a feature, bug fix, hotfix, release, or chore.
- Validating or correcting an existing branch name against the specification.

Do **not** rename trunk branches (`main`, `master`, `develop`) — they carry no prefix.

## Format

```
<type>/<description>
```

## Procedure

1. **Pick the prefix** that matches the intent of the work (see Prefixes below).
2. **Write the description**: short, clear, lowercase, words separated by hyphens. Include a ticket number when one exists (e.g. `issue-123`).
3. **Apply the Basic Rules** and confirm the name matches the validation regex.
4. **Create the branch**, for example:
   ```bash
   git switch -c feature/add-login-page
   # or
   git checkout -b fix/issue-123-header-bug
   ```

## Prefixes

Purpose prefixes — describe the intent of the work:

| Prefix | Alias | Use for | Example |
|--------|-------|---------|---------|
| `feature/` | `feat/` | New features | `feature/add-login-page` |
| `bugfix/` | `fix/` | Bug fixes | `fix/header-bug` |
| `hotfix/` | — | Urgent production fixes | `hotfix/security-patch` |
| `release/` | — | Preparing a release (dots allowed for versions) | `release/v1.2.0` |
| `chore/` | — | Non-code tasks: deps, docs, tooling | `chore/update-dependencies` |

AI agent source prefixes — identify branches generated by AI coding agents:

| Prefix | Agent |
|--------|-------|
| `ai/` | Any AI agent (vendor-neutral) |
| `copilot/` | GitHub Copilot |
| `cursor/` | Cursor |
| `claude/` | Claude Code (Anthropic) |
| `codex/` | OpenAI Codex |

Teams may define additional custom types, but document them so tooling and teammates recognize them.

## Basic Rules

1. **Lowercase alphanumerics, hyphens, and dots only.** Use `a-z`, `0-9`, and `-` to separate words. No uppercase, spaces, underscores, or other special characters. Dots (`.`) are allowed in the description for version numbers (e.g. `release/v1.2.0`).
2. **No consecutive, leading, or trailing hyphens or dots.** Avoid `feature/new--login`, `feature/-new-login`, `feature/new-login-`, `release/v1.-2.0`.
3. **Clear and concise.** The name should describe the purpose without being verbose.
4. **Include ticket numbers when applicable**, e.g. `feature/issue-123-new-login`.

## Validation

A name is valid if it is a trunk branch or matches the specification. Practical regex (matches the ABNF grammar below):

```
^(main|master|develop)$
```
or
```
^(feature|feat|bugfix|fix|hotfix|release|chore|ai|copilot|cursor|claude|codex)/[a-z0-9]+(\.[a-z0-9]+)*(-[a-z0-9]+(\.[a-z0-9]+)*)*$
```

Quick shell check:
```bash
name="feature/add-login-page"
echo "$name" | grep -Eq '^(main|master|develop)$|^(feature|feat|bugfix|fix|hotfix|release|chore|ai|copilot|cursor|claude|codex)/[a-z0-9]+(\.[a-z0-9]+)*(-[a-z0-9]+(\.[a-z0-9]+)*)*$' \
  && echo "valid" || echo "invalid"
```

## Examples

| Branch | Valid | Reason |
|--------|:-----:|--------|
| `main` / `master` / `develop` | ✅ | Trunk branches (no prefix) |
| `feature/add-login-page` | ✅ | New feature |
| `feat/add-login-page` | ✅ | Short alias for feature |
| `bugfix/fix-header-bug` | ✅ | Bug fix |
| `fix/header-bug` | ✅ | Short alias for bugfix |
| `hotfix/security-patch` | ✅ | Urgent fix |
| `release/v1.2.0` | ✅ | Release with version |
| `chore/update-dependencies` | ✅ | Non-code task |
| `feature/issue-123-new-login` | ✅ | Feature with ticket number |
| `copilot/add-login-page` | ✅ | GitHub Copilot |
| `ai/refactor-auth-flow` | ✅ | Generic AI agent prefix |
| `Feature/Add-Login` | ❌ | Uppercase not allowed |
| `feature/new--login` | ❌ | Consecutive hyphens |
| `feature/-new-login` | ❌ | Leading hyphen |
| `feature/new-login-` | ❌ | Trailing hyphen |
| `release/v1.-2.0` | ❌ | Hyphen adjacent to dot |
| `fix/header bug` | ❌ | Spaces not allowed |
| `fix/header_bug` | ❌ | Underscores not allowed |
| `unknown/some-task` | ❌ | Unknown prefix type |

## Formal Grammar (ABNF)

```
branch-name     = trunk-branch / prefixed-branch
trunk-branch    = "main" / "master" / "develop"
prefixed-branch = type "/" description
type            = "feature" / "feat" / "bugfix" / "fix"
                / "hotfix" / "release" / "chore"
                / "ai" / "copilot" / "cursor"
                / "claude" / "codex"
description     = desc-segment *("-" desc-segment)
desc-segment    = 1*(ALPHA / DIGIT) *("." 1*(ALPHA / DIGIT))
ALPHA           = %x61-7A   ; lowercase a-z
DIGIT           = %x30-39   ; 0-9
```

Consecutive hyphens or dots, and hyphens or dots at the start or end of the description, are not permitted.