conventional-branch
Create Git branches following the Conventional Branch specification (feature/, bugfix/, hotfix/, release/, chore/, plus AI agent prefixes ai/, copilot/, cursor/, claude/, codex/). Use when creating a new branch, naming a branch, or checking whether a branch name complies with the spec.
How do I install this agent skill?
npx skills add https://github.com/github/awesome-copilot --skill conventional-branchIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides guidelines and commands for creating Git branches using a standardized naming convention. It includes input validation to ensure branch names are safe and consistent.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Conventional Branch
Create Git branches that follow the Conventional Branch specification — a simple, consistent convention for naming Git branches.
Branch Name Format
<type>/<description>
Branch Types
Purpose prefixes — describe the intent of the work:
| Type | Alias | Purpose |
|---|---|---|
feature/ | feat/ | New features or enhancements |
bugfix/ | fix/ | Bug fixes |
hotfix/ | — | Urgent production fixes |
release/ | — | Release preparation (dots allowed in version: release/v1.2.0) |
chore/ | — | Non-code tasks (deps, docs, config) |
AI agent source prefixes — identify branches generated by AI coding agents:
| Type | Alias | Purpose |
|---|---|---|
ai/ | — | Generic prefix for any AI coding agent |
copilot/ | — | GitHub Copilot |
cursor/ | — | Cursor |
claude/ | — | Claude Code by Anthropic |
codex/ | — | OpenAI Codex |
Use a vendor-specific prefix when you know which agent is producing the branch; use ai/ as a vendor-neutral fallback.
Trunk Branches
main, master, and develop are trunk branches — they do not use a prefix. Never create new branches with the same names as trunk branches; branch off them instead.
Naming Rules
- Lowercase only — no uppercase letters anywhere
- Alphanumerics, hyphens, and dots —
a-z,0-9,-,. - Dots are allowed in any description, typically for version numbers (e.g.,
release/v1.2.0,chore/upgrade-node-v20.11) - No underscores, spaces, or special characters
- No consecutive hyphens (
--), dots (..), or hyphen-dot adjacency (-.or.-) - No leading or trailing hyphens or dots in the description
Valid Examples
main
master
develop
feature/add-login-page
feat/add-login-page
bugfix/fix-header-bug
fix/header-bug
hotfix/security-patch
release/v1.2.0
chore/update-dependencies
feature/issue-123-new-login
ai/refactor-auth-flow
copilot/add-login-page
cursor/fix-header-bug
claude/security-patch
codex/optimize-query
Invalid Examples
| Branch | Problem |
|---|---|
Feature/Add-Login | Uppercase letters |
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 | Space |
fix/header_bug | Underscore |
unknown/some-task | Unknown prefix type |
Description Guidelines
- Use kebab-case with 2-5 words
- Be descriptive but concise (~50 chars total)
- Good:
add-oauth-login,fix-header-overflow,update-ci-config - Bad:
fix-bug,new-feature
Workflow
Follow these steps:
Step 1 — Determine Branch Type
Ask the user (if not already clear):
- Branch type — default to
featurewhen uncertain - Brief description — what the branch is for
If the user mentions a ticket or issue number, include it in the description (e.g., feature/issue-123-add-oauth).
Step 2 — Validate the Name
Check the assembled name against the Naming Rules above. If any rule fails, fix it:
- Lowercase everything
- Replace underscores and spaces with hyphens
- Collapse consecutive hyphens
- Strip leading/trailing hyphens
Step 3 — Detect the Base Branch
Different repos use different trunk branches. Detect which one this repo uses:
# Prefer the remote's default branch
git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'
If that returns nothing, check which trunk branch exists locally (priority order: develop, main, master):
for b in develop main master; do
git show-ref --verify --quiet "refs/heads/$b" && echo "$b" && break
done
Step 4 — Create and Checkout
git checkout <base>
git pull origin <base>
git checkout -b <type>/<description>
Step 5 — Confirm
Tell the user:
- The branch name that was created
- That they are now on the new branch
- Remind them:
git push -u origin <branch-name>when ready
Validation
commit-check validates branch names against the specification. Run commit-check --branch, use its check-branch pre-commit hook, or commit-check-action in GitHub Actions. Configuration for GitHub rulesets, GitLab, Bitbucket and Git hooks is at https://conventionalbranch.org/enforce/.
Relationship with Conventional Commits
Conventional Branch complements Conventional Commits:
| Conventional Branch | Typical Conventional Commit |
|---|---|
feature/add-login | feat: add login page |
bugfix/fix-header | fix: header overflow on mobile |
chore/update-deps | chore: bump lodash to 5.0 |
release/v1.2.0 | chore: release v1.2.0 |
Align the branch type with commit types where possible (e.g., feature/* branches with feat: commits).
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/github/awesome-copilot/conventional-branch">View conventional-branch on skillZs</a>