| name | creating-worktree |
| description | Creates isolated git worktrees in .claude/worktrees/ with intelligent branch naming, auto-incrementing, and commit type detection (feat/fix/refactor). Supports manual descriptions and auto-generation from uncommitted git changes. Use when user requests to create worktree, start isolated work, parallel development, run /worktree command, or mentions "worktree". |
| model | haiku |
Git Worktree Creation Workflow
Create isolated git worktrees in .claude/worktrees/ with intelligent branch naming. Combines worktree isolation with the same naming convention as the creating-branch skill.
Usage
This skill is invoked when:
- User runs
/worktree or /git:worktree command
- User requests to create a worktree for isolated work
Two Operation Modes
Mode 1: With Description (Manual)
The command takes a description and automatically detects the commit type.
Format: /worktree <description>
Examples:
/worktree add user authentication
/worktree fix login bug
/worktree refactor auth service
Mode 2: Auto-Generate from Changes (No Arguments)
When no arguments provided and no sdlc-develop specs exist, analyze uncommitted changes to generate names automatically.
Format: /worktree (no arguments)
Process:
- Check for sdlc-develop specs (see Mode 3)
- If no specs, check for uncommitted changes (both staged and unstaged)
- If no changes exist, display error and require description
- If changes exist, analyze to generate description
- Create worktree with auto-generated names
Mode 3: From SDLC-Develop Spec (Arkhe Integration)
When no arguments provided and sdlc-develop specs exist, create worktree linked to an existing feature spec.
Detection Flow:
- Check if
.arkhe.yaml exists -> read develop.specs_dir (default: arkhe/specs)
- Scan
{specs_dir}/ for existing spec directories
- If specs found -> present selection via
AskUserQuestion
- Use spec directory name for worktree and branch names
Naming Convention
This skill produces dual names:
| Component | Format | Example |
|---|
| Worktree directory | .claude/worktrees/{keywords} | .claude/worktrees/user-authentication |
| Git branch | {type}/{number}-{keywords} | feat/001-user-authentication |
The directory uses just keywords (tab-completion friendly). The branch uses the full conventional format (consistent with /create-branch).
Commit Type Detection
Automatically detect commit types from keywords in the description:
| Type | Keywords |
|---|
| feat | add, create, implement, new, update, improve |
| fix | fix, bug, resolve, correct, repair |
| refactor | refactor, rename, reorganize |
| chore | remove, delete, clean, cleanup |
| docs | docs, document, documentation |
If no keyword is detected, defaults to feat.
Keyword Extraction
- Split description into words
- Remove stopwords: the, a, an, for, to, in, on, at, by, with, from, and, or, but, this, that
- Remove commit type keywords (add, fix, create, etc.)
- Keep first 2-3 meaningful words
- Convert to lowercase, join with hyphens
Workflow Steps
Step 1: Parse Arguments and Determine Mode
DESCRIPTION="$ARGUMENTS"
If $ARGUMENTS is provided -> Mode 1 (manual)
If empty -> check for .arkhe.yaml specs (Mode 3), then fall back to auto-generate (Mode 2)
For Mode 2 (auto-generate):
CHANGED_FILES=$(git diff --name-only HEAD 2>/dev/null; git diff --cached --name-only 2>/dev/null)
If no changes, display error: "No arguments and no uncommitted changes. Provide a description: /worktree <description>"
If changes exist, analyze filenames/paths to generate a description.
Step 2: Generate Names
Detect commit type from description keywords (see table above). Default to feat.
Extract keywords: Filter stopwords from description, keep first 2-3 meaningful words, hyphenate.
Find next sequential number:
MAX_NUM=$(git branch --list | grep -oE '/[0-9]{3}-' | grep -oE '[0-9]{3}' | sort -n | tail -1)
NEXT_NUM=$(printf "%03d" $((10#${MAX_NUM:-0} + 1)))
Assemble names:
- Worktree directory:
KEYWORDS (e.g., user-authentication)
- Git branch:
TYPE/NUMBER-KEYWORDS (e.g., feat/001-user-authentication)
Step 3: Validate Worktree Directory
ls .claude/worktrees/$KEYWORDS 2>/dev/null
If it exists, report the conflict and stop. Suggest either a different description or removing the existing worktree.
Also check if the branch already exists:
git branch --list "$TYPE/$NEXT_NUM-$KEYWORDS"
If the branch exists, increment the number and retry.
Step 4: Safety Check - Git Ignore
Verify .claude/worktrees/ is git-ignored:
git check-ignore -q .claude/worktrees 2>/dev/null
If NOT ignored (exit code non-zero), add .claude/worktrees/ to .gitignore:
echo '\n# Worktrees\n.claude/worktrees/' >> .gitignore
git add .gitignore && git commit -m "chore: add .claude/worktrees/ to .gitignore"
Step 5: Ask Base Branch
Use AskUserQuestion to ask which branch to base the worktree on:
- main (Recommended) -- Create from the main branch
- Current branch -- Create from the currently checked out branch
- Other -- User specifies a different branch name
Step 6: Create Worktree
mkdir -p .claude/worktrees
git worktree add ".claude/worktrees/$KEYWORDS" -b "$TYPE/$NEXT_NUM-$KEYWORDS" "$BASE_BRANCH"
Where $BASE_BRANCH is main, HEAD, or the user-specified branch.
Step 7: Confirm Success
Report:
- Worktree path:
.claude/worktrees/<keywords>
- Git branch:
<type>/<number>-<keywords> (based on <base-branch>)
- List worktrees:
git worktree list
- Remove when done:
git worktree remove .claude/worktrees/<keywords>
Important Notes
- Sequential Numbering: Shared number space with
/create-branch -- scans all branches
- Keyword Extraction: Filters common words, keeps 2-3 meaningful terms
- Lowercase Convention: All names are lowercase with hyphens
- Conventional Commits: Branch names align with conventional commit types
- Dual Naming: Directory name differs from branch name for usability
Supporting Documentation
