creating-worktree
/creating-worktree
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".
- Author
- joaquimscosta ↗
- Repository
- arkhe-claude-plugins ↗
- Licence
- MIT
- Last repository change
- 14.08.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 14.08.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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".
Triggers from the description
Original author 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".
How it works
- Usage
- Two Operation Modes
- Naming Convention
- Commit Type Detection
- Keyword Extraction
- Workflow Steps
- Important Notes
- Supporting Documentation
SKILL.md preview
---
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**:
```bash
/worktree add user authentication
# Worktree: .claude/worktrees/user-authentication
# Branch: feat/001-user-authentication
/worktree fix login bug
# Worktree: .claude/worktrees/login-bug
# Branch: fix/002-login-bug
/worktree refactor auth service
# Worktree: .claude/worktrees/auth-service
# Branch: refactor/003-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**:
1. Check for sdlc-develop specs (see Mode 3)
2. If no specs, check for uncommitted changes (both staged and unstaged)
3. If no changes exist, display error and require description
4. If changes exist, analyze to generate description
5. 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:**
1. Check if `.arkhe.yaml` exists -> read `develop.specs_dir` (default: `arkhe/specs`)
2. Scan `{specs_dir}/` for existing spec directories
3. If specs found -> present selection via `AskUserQuestion`
4. 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
1. Split description into words
2. Remove stopwords: the, a, an, for, to, in, on, at, by, with, from, and, or, but, this, that
3. Remove commit type keywords (add, fix, create, etc.)
4. Keep first 2-3 meaningful words
5. Convert to lowercase, join with hyphens
## Workflow Steps
### Step 1: Parse Arguments and Determine Mode
```bash
# Check for arguments
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):
```bash
# Check for uncommitted changes
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**:
```bash
# Scan ALL branches (shared number space with /create-branch)
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
```bash
# Check directory doesn't already exist
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:
```bash
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:
```bash
git check-ignore -q .claude/worktrees 2>/dev/null
```
If NOT ignored (exit code non-zero), add `.claude/worktrees/` to `.gitignore`:
```bash
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
```bash
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
- **[WORKFLOW.md](WORKFLOW.md)** - Detailed step-by-step process
- **[EXAMPLES.md](EXAMPLES.md)** - Real-world examples for all worktree types
- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common issues and solutions
Files in this package (4)
- EXAMPLES.md 6 KB
- SKILL.md 7 KB
- TROUBLESHOOTING.md 6 KB
- WORKFLOW.md 10 KB
Versions
The database has no other skills named creating-worktree.
Database snapshot: 13.11.2026 · package version 936a33b5c271 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100creating-branch
Creates feature branches with optimized short 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 branch, start new branch, make branch, checkout… - 100ce-worktree
Set up isolated git worktrees — create a new branch for fresh work, or attach a worktree to an existing branch, PR, or commit. Use when starting isolated work or isolating an existing ref. - 95dev_manage_git-worktrees
Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification. Triggers: worktree, git worktree, isolated workspace, feature branch… - 100git-worktree
Use when work needs an isolated git worktree, such as parallel feature branches, reviewing a PR without disturbing the current checkout, or cleaning up old worktrees. - 100worktree
Creates git worktrees for isolated development. Use when user wants to "create a worktree", "start a new feature branch", "work on a fix in isolation", or needs a parallel development environment. - 100using-git-worktrees
Creates and removes isolated git worktrees for parallel development. Use when starting feature work needing isolation, working on multiple branches simultaneously, or removing one specific worktree and its branch after its PR merges. NOT for simple branch switching, sweeping…