Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add alfredoperez/speckit-companion --skill speckit-git-feature -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/speckit-git-feature/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/speckit-git-feature/

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

Similar skills

All skills for Git and GitHub →

From the same set83

The whole set →
publish The publish command guides a VS Code extension release, from QA checks and changelog updates to versioning and pushing a tagged commit. A separate file is available for Codex. CX Codex +1 ★ 110repo stars release-loop release-loop is a command for Claude Code and Codex that moves a batch of changes through fixes, QA, and release. It prepares a report and waits for approval before publishing. CX Codex +1 ★ 110repo stars bench-wave bench-wave runs an end-to-end benchmark round for a pipeline-diet wave across two Companion cells and logs the metrics into a markdown plan. Useful for measuring speed, token counts, and driver feedback. CX Codex +1 ★ 110repo stars speckit.git.feature The speckit.git.feature command creates and checks out a Git feature branch from a specification. Configure sequential or timestamp numbering and shape branch names with a template. CX Codex +1 ★ 110repo stars speckit.companion.living-move speckit.companion.living-move relocates Speckit living specs between central storage and colocated code folders while updating the project registry. CX Codex +1 ★ 110repo stars publish-mod publish-mod releases the Claude Code mod through the repository marketplace and prepares the Anthropic directory handoff for the user. CX Codex +1 ★ 110repo stars speckit.companion.mark-complete speckit.companion.mark-complete marks the active spec as completed via write-context.py. Handy when you want to close a spec by hand instead of running a full converge. CX Codex +1 ★ 110repo stars speckit.constitution speckit.constitution updates the project constitution template in .specify/memory/constitution.md and aligns dependent specification templates. CX Codex GP ChatGPT ★ 110repo stars

Project sponsors

Companies that keep this analytics open