AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

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.

Original source
github
License
MIT
Pinned revision
5269f7ea2d6c3a9bfda5ed878b6726cf509121fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read github--conventional-branch at revision 5269f7ea2d6c3a9bfda5ed878b6726cf509121fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 1

SKILL.md

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 feature when 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).