Guide · Agent skill

How to use the Conventional Branch agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The conventional-branch skill teaches an AI coding agent to name and create Git branches using the Conventional Branch specification. It is useful for developers who want consistent branch names and for anyone who lets an agent open branches on their behalf. After this guide you will know what the skill changes, how to install it, how to ask for it, and what it needs to run.

Conventional Branch Naminggithub/awesome-copilot · MIT Download the skill

Quick start

1Install Git and open a repo. Make sure Git is installed and that your project has a remote named origin, since base-branch detection and pulling depend on it.
2Download and unzip the skill. Download the ZIP from this page and unzip it so the folder contains SKILL.md.
3Place the folder. Put the conventional-branch folder in ~/.claude/skills/ for all projects, or in the project's .claude/skills/ for one project. Alternatively upload it under Settings → Capabilities → Skills in the Claude apps.
4Ask for a branch in plain language. Say something like 'create a branch for adding OAuth login'. The agent should use the skill because the description covers branch creation and naming.
5Review the name and base branch. Check that the type prefix and description fit your work, and that the agent chose the correct trunk branch.
6Push when ready. The agent will remind you to push. Run git push -u origin with the branch name the agent gave you.

What the skill makes the agent do

Without the skill, an agent picks a branch name however it likes. With it, the agent builds every name as <type>/<description>, where the type is a purpose prefix such as feature/, bugfix/, hotfix/, release/ or chore/. The description is kebab-case, lowercase, and usually 2-5 words, for example feature/add-login-page.

The skill also knows AI agent prefixes (ai/, copilot/, cursor/, claude/, codex/) so branches created by agents are easy to spot. It checks each name against the naming rules, such as no spaces, underscores, uppercase letters, consecutive hyphens or dots. It then detects the base branch, creates the branch, and reminds you to push it.

Purpose prefixes: feature/ (alias feat/), bugfix/ (alias fix/), hotfix/, release/, chore/
AI agent prefixes: ai/ as a vendor-neutral fallback, plus copilot/, cursor/, claude/, codex/
Trunk branches main, master and develop never get a prefix and are never recreated as new branches

Install the skill from the ZIP

Download the ZIP for this skill from this page and unzip it. The package contains a single file, SKILL.md. Skills are folders that contain a SKILL.md file, so keep the conventional-branch folder intact after unzipping.

For a personal skill that works in all your projects, place the folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder instead.

If you use the Claude apps rather than a local setup, you can upload the skill under Settings → Capabilities → Skills.

~/.claude/skills/conventional-branch/SKILL.md

Trigger the skill with natural requests

You do not run the skill by hand. The skill description tells the agent when to use it: when creating a new branch, naming a branch, or checking whether a branch name complies with the spec. Ask in plain language and the agent should pick it up.

If the agent does not pick the skill up, name it directly in your request, for example by saying you want the conventional-branch rules applied.

Create a branch for adding OAuth login to this repo.
Name a branch for fixing the header overflow bug on mobile.
Is the branch name fix_header_bug valid under the Conventional Branch spec?
Make a release branch for version 1.2.0.
Create a branch for this change and use the Claude prefix because you are doing it.

Follow the workflow the skill sets out

The skill asks for the branch type (defaulting to feature when unclear) and a short description. If you mention a ticket or issue number, it goes into the description, such as feature/issue-123-add-oauth.

Next the agent validates the name and fixes common problems: lowercasing, replacing spaces and underscores with hyphens, collapsing repeated hyphens, and stripping leading or trailing hyphens. To find the base branch, it first reads the remote's default branch, then falls back to checking for develop, main or master locally. It then runs checkout, pull and branch creation, and tells you the new name and the push command to run next.

git checkout <base>
git pull origin <base>
git checkout -b <type>/<description>

Check branch names with commit-check (optional)

The skill can create compliant names, and the optional commit-check tool can check existing names. The source lists three ways to run it: the commit-check --branch command, its check-branch pre-commit hook, or commit-check-action in GitHub Actions. Configuration notes for GitHub rulesets, GitLab, Bitbucket and Git hooks are on the conventionalbranch.org enforcement page.

Align branch types with commit types where you can, such as feature/ branches with feat: commits.

commit-check --branch

What people use it for

Keeping branch names consistent across a team that reviews pull requests by name.
Labelling branches that an AI agent creates, using claude/ or copilot/ prefixes, so reviewers can see where they came from.
Checking whether an existing branch name such as fix_header_bug complies with the spec before opening a pull request.
Naming release branches with version numbers like release/v1.2.0, where dots are allowed.
Feeding branch naming into a CI check with commit-check-action.

Frequently asked questions

Is the conventional-branch skill free to use?

The skill is released under the MIT licence, as stated on this page. Check the licence file in the source repository for full terms.

What do I need before using this skill?

You need Git installed locally and a Git repository with a remote named origin. The skill assumes you already work with Git. It does not run scripts or use the network itself.

Where do I put the skill so Claude can find it?

Place the conventional-branch folder containing SKILL.md in ~/.claude/skills/ for all projects, or in a project's .claude/skills/ folder for one project. In the Claude apps you can upload it under Settings → Capabilities → Skills.

Does the skill work with repositories that have their own branch naming rules?

Not reliably. The source warns that this spec may conflict with a repository's own branch naming policy, and the agent will follow the skill rather than your house rules. Check your policy before using it there.

Which branch names does the skill reject?

The skill's rules reject uppercase letters, spaces, underscores, special characters, consecutive hyphens, consecutive dots, hyphen-dot adjacency, and leading or trailing hyphens or dots in the description. It also rejects unknown prefix types.

What is the difference between feature/ and feat/?

The specification lists feat/ as an alias for feature/, and fix/ as an alias for bugfix/. Both forms are valid under the spec.

Are there alternatives?

The source points to commit-check for validation, but it does not compare other naming skills or tools, so this guide cannot say how it compares with them.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you want consistent, readable branch names and clear labels for branches created by AI agents, and you already work with Git and an origin remote. Skip it if your repository has its own branch naming policy or you do not use Git workflows.

Download the skill