| name | branch-namer |
| description | Generate descriptive git branch names that follow the project's naming convention. Use this skill whenever the user asks to create a branch, name a branch, start working on a feature or fix, checkout a new branch, or when you're about to run `git checkout -b` or `git switch -c`. Also trigger when you see a vague branch name like `fix/auth` or `feature/billing` that lacks a description of what's actually changing — the branch name should always tell you *what* the change does, not just its category.
|
Branch Namer
The Problem
Branch names like fix/dx or feature/billing are technically valid but practically useless. When you scan a list of branches, you should immediately understand what each one is about without having to look up the PR or commit history.
Exception: For investigation or exploratory tasks where the outcome isn't known upfront, it's fine to name the branch after the task/ticket (e.g., chore/investigate-memory-leak or chore/PROJ-123). The descriptive slug matters most for feature and fix branches where the intent is clear.
Branch Name Format
<type>/<scope>-<descriptive-slug>
Components:
-
type: One of the conventional commit types listed below. Use the same type you'd use in the commit message. Prefer feat over feature for consistency with commit conventions. Pick the type carefully — it controls CI/CD behavior:
| Type | Triggers Release? | Changelog | Auto-approve eligible |
|---|
feat | Yes (minor bump) | Visible | No |
fix | Yes (patch bump) | Visible | No |
refactor | Yes (patch bump) | Visible | No |
chore | No release | Hidden | Yes* |
test | No release | Hidden | Yes* |
docs | No release | Hidden | Yes* |
*Auto-approve requires experienced-contributor label, small PR size, and restricted file scope.
Use chore/test/docs for changes that don't affect the shipped artifact (CI config, .helm charts, package.json scripts, test-only changes, README updates). These don't trigger a release even though they may affect production deployments. Use refactor only when you're restructuring code that ends up in the built/deployed application — it triggers a patch release even though nothing user-facing changed.
-
scope: A category from the project's .commitlintrc.json scope-enum list. Read this file to get the current allowed scopes. If nothing fits, use a short reasonable name. For app-specific changes, you can use a sub-path like fix/provider-console/min-balance-issue.
-
descriptive-slug: 3–6 words in kebab-case that describe what the change does. This is the part that matters most.
How to Write the Slug
The slug should answer: "What does this branch do?" in a few words. Think of it like a compressed commit message subject.
Principles:
- Lead with a verb when natural:
add-, close-, remove-, update-, handle-, migrate-
- Drop articles (a, an, the) and filler words
- Use domain terms the team recognizes (e.g.,
sequelize, stripe, managed-wallet)
- Keep it under ~50 characters total (type + scope + slug)
- Don't repeat the type in the slug —
fix/auth-fix-login-redirect → fix/auth-login-redirect
Examples
| PR / Task Description | Bad Branch Name | Good Branch Name |
|---|
| Close Sequelize connection on container dispose | fix/dx | fix/dx-close-sequelize-on-dispose |
| Redirect unauthenticated users to login on /api-keys | fix/auth | fix/auth-redirect-unauthenticated-to-login |
| Add Stripe payment method to billing | feat/billing | feat/billing-add-stripe-payment-method |
| Handle MissingStateCookieError during auth | fix/auth | fix/auth-handle-missing-state-cookie |
| Granular skip labels for security scan workflow | chore/ci | chore/ci-granular-skip-labels-security |
| Use local instrumentation package in indexer | refactor/indexer | refactor/indexer-use-local-instrumentation |
| Migrate deploy-web from deprecated SDL class | refactor/sdl | refactor/sdl-migrate-deploy-web-generate-manifest |
| Switch notifications build from webpack to tsup | refactor/notifications | refactor/notifications-switch-webpack-to-tsup |
| Add ACT support for authorizations | feat/wallet | feat/wallet-add-act-authorization-support |
Workflow
- Read
.commitlintrc.json to get the allowed scopes for the current project
- Determine the type —
feat, fix, refactor, chore, docs, or test?
- Pick the scope — which area of the codebase does this touch?
- Write the slug — compress the task description into 3–6 kebab-case words
- Check the total length — aim for under 50 characters
- Suggest the branch name to the user before creating it
