mcpField
P
pr-branch-naming

pr-branch-naming

github.com/thedesignprojectDevelopment97143 installsUpdated 9w ago
Repository

About pr-branch-naming

pr-branch-naming is a development skill that turns a change description into a convention-based branch name and matching PR title. It can also guide checkout or draft PR creation, but only after explicit confirmation and prerequisite checks.

Key features

  1. 01Branch type and scope selection
  2. 02Convention-based branch naming
  3. 03Matching PR title generation
  4. 04Optional checkout and draft PR steps
  5. 05Git and GitHub CLI precondition checks

Use cases

  1. 01Naming a branch for a described feature or fix
  2. 02Preparing a matching PR title
  3. 03Checking branch and authentication status before applying changes

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/thedesignproject/agent-skills --skill pr-branch-naming

After installing, type/pr-branch-namingin Claude Code to confirm it loaded.

Details

From the project README

PR & Branch Naming

You generate a conventionally-named branch and a matching PR title from a feature description, then optionally check out the branch and/or open a PR — but only with explicit user confirmation.

Step 1: Get the feature description

The user's input is in $ARGUMENTS. It can be:

  1. A description — use it directly
  2. Empty — try to infer the work from git status and the most recent commits (git log -n 5 --oneline). If you can infer it, propose it back to the user for confirmation. If not, ask: "What's the feature or change this branch is for?"

Don't fabricate a description. If there's nothing to go on, ask.

Step 2: Pick the type and scope

Type (one of)
TypeWhen to use
featNew feature or new UI work
fixBug fix to existing functionality
docsDocumentation changes only
refactorCode restructuring with no behavior change
perfPerformance improvement
choreTooling, config, dependency bumps
experimentalPrototype, spike, or exploration not intended to ship as-is

Pick the type that best matches the description. For designer-authored work, the common types are feat and experimental.

Scope

The area of the product affected — short, lowercase, single word if possible. Examples: playground, dashboard, auth, onboarding, billing.

Infer the scope from the description. If it's genuinely ambiguous, ask once: "What part of the product does this touch — dashboard, auth, etc.?" Don't pepper the user with questions.

Step 3: Pick the branch prefix

PrefixWhen to use
feature/New features or UI work (pairs with feat)
bugfix/Fixing existing functionality (pairs with fix)
hotfix/Urgent production fixes
docs/Documentation changes (pairs with docs)
experimental/Prototypes and explorations (pairs with experimental)

The prefix should align with the type. Use feature/ for feat, bugfix/ for fix, and so on.

Step 4: Generate the names

Branch name

Format: <prefix>/<kebab-description>

Rules:

  • Lowercase only
  • Hyphen-separated (no underscores, no spaces)
  • No trailing hyphen
  • Keep it concise — aim for 3–6 words in the description portion
  • Drop filler words (the, a, for, to, make)

Example: feature/patient-based-messaging

PR title

Format: <type>(<scope>): <short description>

Rules:

  • Description in plain language, sentence case, no trailing period
  • Concise — fits on one line
  • Mirrors what the branch is about, but reads naturally to a human reviewer

Example: feat(playground): v1 prototype — patient-based messaging flow

Step 5: Show the result

Present both names plus a one-line rationale, in this format:

Branch:    feature/patient-based-messaging
PR title:  feat(playground): v1 prototype — patient-based messaging flow

Type: feat (new UI work) · Scope: playground · Prefix: feature/

Step 6: Offer to apply

Ask the user whether to:

  1. Check out the branch — run git checkout -b <branch>
  2. Open a draft PR — run gh pr create --draft --title "<title>" --body "<one-line description>"
  3. Do both
  4. Neither — they'll copy the names themselves

Before running either command, check the preconditions and stop with a clear message if they fail:

  • For git checkout -b: run git status first. If the working tree is dirty, surface that and ask whether to proceed anyway, stash, or abort. If a branch with the same name already exists, suggest a numeric suffix (-2).
  • For gh pr create: run gh auth status first. If unauthenticated, tell the user to run gh auth login and stop. Don't open the PR from a branch with no commits ahead of base — check with git log <base>..HEAD --oneline and warn if empty.

Never run destructive git operations (reset --hard, branch -D, push --force) as part of this skill.

Notes

  • If the user is already on a non-default branch when invoking this skill, ask whether the new branch should be cut from main/master or from the current branch.
  • If multiple changes are described (e.g., "fix the login bug and add a new dashboard widget"), suggest splitting into two branches/PRs rather than smushing them into one.
  • The PR title's description can use an em dash (—) to add a qualifier, as in the example. Don't overuse it.

Comments

Markdown supported