Skip to main content
skill CX Codex

speckit-git-validate — Claude Code skill: install

speckit-git-validate is a Claude Code skill that checks the current Git branch name and searches specs/ for its matching spec folder in spec-kit projects.

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-validate -a claude-code
Open on GitHub

What speckit-git-validate does

This skill checks whether the project is inside a Git work tree, reads the current branch, and compares its final path segment with two naming rules. Accepted forms include sequential names such as 001-feature-name and timestamp names such as 20260319-143022-feature-name. Namespaces are allowed because validation uses the final segment.

When the branch matches, the skill searches specs/ for a directory with the same numeric or timestamp prefix. It reports the matching spec path or the missing directory, and shows an expected format for other branches. The project needs a .specify/ directory. If Git cannot be used, SPECIFY_FEATURE is checked as a fallback; without it, validation is skipped with a warning.

What it helps with

  • check the current Git branch name
  • flag branches outside the spec-kit convention
  • match a branch prefix to a folder in specs/
  • fall back to SPECIFY_FEATURE when Git is unavailable

Example prompts for the agent

  • Check the current branch with the speckit-git-validate rules and find its matching spec.
  • Tell me whether this branch follows 001-feature-name or 20260319-143022-feature-name.
  • Look under specs/ for the directory matching the current feature branch prefix.

How to install speckit-git-validate

1Skills CLI (Vercel)

npx skills add alfredoperez/speckit-companion --skill speckit-git-validate -a claude-code

2Manually: put the files in place

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

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

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about speckit-git-validate

How do I install speckit-git-validate in Claude Code?

Run npx skills add alfredoperez/speckit-companion --skill speckit-git-validate -a claude-code, then check ~/.claude/skills/speckit-git-validate/SKILL.md.

What does speckit-git-validate do?

It checks the current Git branch against spec-kit feature naming rules and looks for the related directory under specs/. It also reports branches that do not match the expected patterns.

What does speckit-git-validate require?

The project needs a spec-kit layout with .specify/. When Git is unavailable, the skill can validate SPECIFY_FEATURE instead.

Source text

SKILL.md · MIT
---
name: speckit-git-validate
description: Validate current branch follows feature branch naming conventions
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 Validate Skill

# Validate Feature Branch

Validate that the current Git branch follows the expected feature branch naming conventions.

## Prerequisites

- Check if Git is available by running `git rev-parse --is-inside-work-tree 2>/dev/null`
- If Git is not available, output a warning and skip validation:
  ```
  [specify] Warning: Git repository not detected; skipped branch validation
  ```

## Validation Rules

Get the current branch name:

```bash
git rev-parse --abbrev-ref HEAD
```

The branch name's final path segment must start with one of these feature markers:

1. **Sequential**: `[0-9]{3,}-` (e.g., `001-feature-name`, `042-fix-bug`, `1000-big-feature`, `jdoe/web/008-guided-tour`)
2. **Timestamp**: `[0-9]{8}-[0-9]{6}-` (e.g., `20260319-143022-feature-name`, `jdoe/web/20260319-143022-feature-name`)

## Execution

If on a feature branch (matches either pattern):
- Output: `✓ On feature branch: <branch-name>`
- Check if the corresponding spec directory exists under `specs/`:
  - For sequential branches, look for `specs/<prefix>-*` where prefix matches the numeric portion, regardless of branch namespace prefixes
  - For timestamp branches, look for `specs/<prefix>-*` where prefix matches the `YYYYMMDD-HHMMSS` portion, regardless of branch namespace prefixes
- If spec directory exists: `✓ Spec directory found: <path>`
- If spec directory missing: `⚠ No spec directory found for prefix <prefix>`

If NOT on a feature branch:
- Output: `✗ Not on a feature branch. Current branch: <branch-name>`
- Output: `Feature branches should be named like: 001-feature-name, 20260319-143022-feature-name, or <namespace>/001-feature-name`

## Graceful Degradation

If Git is not installed or the directory is not a Git repository:
- Check the `SPECIFY_FEATURE` environment variable as a fallback
- If set, validate that value against the naming patterns
- If not set, skip validation with a warning

© spec-kit-core · MIT · alfredoperez/speckit-companion

Similar skills

All skills for Git and GitHub →

From the same set83

The whole set →
cleanup-implementer cleanup-implementer executes a single repository cleanup work packet. It edits assigned files, runs target checks, and never touches git write operations. CX Codex ★ 110repo stars bench-prep bench-prep is a command for Claude Code and Codex that resets three test cells to baseline and assigns them one task size before an agent works through the SpecKit Companion workflow. CX Codex +1 ★ 110repo stars speckit.companion.before-converge speckit.companion.before-converge is a Claude Code command that records the start of converge in .spec-context.json for the Companion GUI. Run it from the repository root before that step. CX Codex +1 ★ 110repo stars speckit.companion.classify speckit.companion.classify evaluates task scope from spec.md to classify changes as simple, normal, or oversized. Companion workflows use this signal to adapt the execution pipeline. CX Codex +1 ★ 110repo stars speckit.companion.after-plan speckit.companion.after-plan writes a plan finish marker to .spec-context.json for the Companion GUI to track agent workflow stages. CX Codex +1 ★ 110repo stars speckit.companion.after-converge speckit.companion.after-converge logs converge completion into .spec-context.json for Companion GUI. It tells the companion interface that the step finished. CX Codex +1 ★ 110repo stars speckit.companion.after-specify speckit.companion.after-specify — a command for Claude Code and Codex that writes the current spec-kit step to .spec-context.json for the Companion GUI. Runs from the repository root after the specify stage completes. CX Codex +1 ★ 110repo stars speckit.companion.after-implement speckit.companion.after-implement — a command that writes implement step progress from tasks.md into .spec-context.json for the Companion GUI. CX Codex +1 ★ 110repo stars

Project sponsors

Companies that keep this analytics open