speckit-git-feature — Claude Code skill: auto-numbered feature branches
speckit-git-feature is a Claude Code skill that creates a Git branch from a task description within a Spec Kit project and reads its configuration.
MIT ★ 110 updated 2026-10-19
npx skills add alfredoperez/speckit-companion --skill speckit-git-feature -a claude-codeWhat speckit-git-feature does
This skill generates branch names from task descriptions, determines the next number or timestamp, and runs git checkout -b. It reads the numbering strategy from .specify/extensions/git/git-config.yml, supporting sequential or timestamp modes. For monorepos, it handles templates like {author}/{app}/{number}-{slug} so each project maintains its own counter.
Before creating the branch, the skill verifies Git is available and the current directory is a repository. If Git is not found, it logs a warning and continues; branch creation is skipped but output still contains the branch name and feature number. The skill only creates branches—spec files are generated by the separate /speckit-specify workflow.
What it helps with
- Create feature branches with automatic sequential or timestamp numbering
- Keep branch names in sync with Spec Kit configuration
- Format branches for monorepos with author and app prefixes
- Switch to a new branch immediately after creation
Example prompts for the agent
- Create a branch for adding OAuth authentication flow
- New timestamp-based branch for an urgent payment bug fix
- Make a feature branch to integrate the third-party API
How to install speckit-git-feature
1Skills CLI (Vercel)
npx skills add alfredoperez/speckit-companion --skill speckit-git-feature -a claude-code2Manually: put the files in place
~/.claude/skills/speckit-git-feature/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/speckit-git-feature/
1Skills CLI (Vercel)
npx skills add alfredoperez/speckit-companion --skill speckit-git-feature -a codex2Manually: put the files in place
.agents/skills/speckit-git-feature/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add alfredoperez/speckit-companion --skill speckit-git-feature -a cursor2Manually: put the files in place
.cursor/skills/speckit-git-feature/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install alfredoperez/speckit-companion .claude/skills/speckit-git-feature2Manually: put the files in place
.github/skills/speckit-git-feature/SKILL.md1Skills CLI (Vercel)
npx skills add alfredoperez/speckit-companion --skill speckit-git-feature -a gemini-cli2Platform CLI
gemini skills install https://github.com/alfredoperez/speckit-companion --path .claude/skills/speckit-git-featureManually: put the files in place
.devin/skills/speckit-git-feature/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about speckit-git-feature
How do I install speckit-git-feature for Claude Code?
Run npx skills add alfredoperez/speckit-companion --skill speckit-git-feature -a claude-code, then check ~/.claude/skills/speckit-git-feature/SKILL.md.
What does speckit-git-feature do?
Creates and checks out a new Git branch with an auto-incremented number or timestamp. The branch name is derived from your task description and may include author or app prefixes if configured in Spec Kit.
What setup does my project need?
Your project must have the Spec Kit structure with a .specify/ directory and be a Git repository. Branch numbering strategy is read from .specify/extensions/git/git-config.yml or defaults to sequential.
Source text
SKILL.md · MIT
---
name: speckit-git-feature
description: Create a feature branch with sequential or timestamp numbering
compatibility: Requires spec-kit project structure with .specify/ directory
metadata:
author: spec-kit-core
source: extension:git
user-invocable: true
disable-model-invocation: false
---
# Git Feature Skill
# Create Feature Branch
Create and switch to a new git feature branch for the given specification. This command handles **branch creation only** — the spec directory and files are created by the core `/speckit-specify` workflow.
## User Input
```text
$ARGUMENTS
```
You **MUST** consider the user input before proceeding (if not empty).
## Environment Variable Override
If the user explicitly provided `GIT_BRANCH_NAME` (e.g., via environment variable, argument, or in their request), pass it through to the script by setting the `GIT_BRANCH_NAME` environment variable before invoking the script. When `GIT_BRANCH_NAME` is set:
- The script uses the exact value as the branch name, bypassing all prefix/suffix generation
- `--short-name`, `--number`, and `--timestamp` flags are ignored
- `FEATURE_NUM` is extracted when the final path segment starts with a numeric or timestamp feature marker (for example `042-name`, `feat/042-name`, or `jdoe/app/042-name`), otherwise set to the full branch name
## Prerequisites
- Verify Git is available by running `git rev-parse --is-inside-work-tree 2>/dev/null`
- If Git is not available, warn the user and skip branch creation
## Branch Numbering Mode
Determine the branch numbering strategy by checking configuration in this order:
1. Check `.specify/extensions/git/git-config.yml` for `branch_numbering` value
2. Check `.specify/init-options.json` for `feature_numbering` value (inherit from core)
3. Check `.specify/init-options.json` for `branch_numbering` value (deprecated, backward compatibility — will be removed in a future release)
4. Default to `sequential` if none of the above exist
## Branch Name Template
Check `.specify/extensions/git/git-config.yml` for an optional `branch_template` value. If it is empty or missing, use the default branch shape `{number}-{slug}`. If it is set, `{slug}` must not appear before `{number}`, its final path segment must start with `{number}-`, and the script expands these tokens:
- `{author}`: sanitized Git config author (`user.name`, falling back to the email local part)
- `{app}`: sanitized Spec Kit init directory name
- `{number}`: sequential number or timestamp
- `{slug}`: generated short branch slug
For monorepos, a template such as `{author}/{app}/{number}-{slug}` creates names like `jdoe/web/008-guided-tour` while preserving per-project feature numbering.
The script also accepts `branch_prefix` as a shorthand for simple namespaces; it expands to `<branch_prefix>/{number}-{slug}`.
## Execution
Generate a concise short name (2-4 words) for the branch:
- Analyze the feature description and extract the most meaningful keywords
- Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
- Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
Run the appropriate script based on your platform:
- **Bash**: `.specify/extensions/git/scripts/bash/create-new-feature-branch.sh --json --short-name "<short-name>" "<feature description>"`
- **Bash (timestamp)**: `.specify/extensions/git/scripts/bash/create-new-feature-branch.sh --json --timestamp --short-name "<short-name>" "<feature description>"`
- **PowerShell**: `.specify/extensions/git/scripts/powershell/create-new-feature-branch.ps1 -Json -ShortName "<short-name>" "<feature description>"`
- **PowerShell (timestamp)**: `.specify/extensions/git/scripts/powershell/create-new-feature-branch.ps1 -Json -Timestamp -ShortName "<short-name>" "<feature description>"`
**IMPORTANT**:
- Do NOT pass `--number` — the script determines the correct next number automatically
- Always include the JSON flag (`--json` for Bash, `-Json` for PowerShell) so the output can be parsed reliably
- You must only ever run this script once per feature
- The JSON output will contain `BRANCH_NAME` and `FEATURE_NUM`
- Do not manually expand `branch_template`; the script reads the git extension config and applies it consistently
## Graceful Degradation
If Git is not installed or the current directory is not a Git repository:
- Branch creation is skipped with a warning: `[specify] Warning: Git repository not detected; skipped branch creation`
- The script still outputs `BRANCH_NAME` and `FEATURE_NUM` so the caller can reference them
## Output
The script outputs JSON with:
- `BRANCH_NAME`: The branch name (e.g., `003-user-auth`, `20260319-143022-user-auth`, or `jdoe/web/003-user-auth`)
- `FEATURE_NUM`: The numeric or timestamp prefix used
© spec-kit-core · MIT · alfredoperez/speckit-companion