Skip to content
Skills Library
Programming · Automation

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".

Licence
MIT
Last repository change
14.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 14.08.2026, without references to retired models or APIs.

Licence

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

worktree
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

  1. Usage
  2. Two Operation Modes
  3. Naming Convention
  4. Commit Type Detection
  5. Keyword Extraction
  6. Workflow Steps
  7. Important Notes
  8. Supporting Documentation
Original SKILL.md headings · 198 lines, 865 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.