# Worktree From Issue

> Create a git worktree with a new branch for implementing a fix or feature for a GitHub issue

- Skill: `dlt-hub/worktree-from-issue` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dlt-hub/worktree-from-issue`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dlt-hub/worktree-from-issue/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dlt-hub (https://skillmd.com/u/dlt-hub)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dlt-hub/worktree-from-issue

---


# Git Worktree for Issue Implementation

Set up an isolated git worktree with a new branch to implement a fix or feature for a GitHub issue.

Parse `$ARGUMENTS` to extract the branch name in format `<category>/<issue-number>-<short-description>`.

## Branch Naming Convention

Branches must follow the pattern from CONTRIBUTING.md:

```
{category}/{ticket-id}-description-of-the-branch
```

Categories: **feat**, **fix**, **exp**, **test**, **docs**, **keep** (all lowercase, dashes, no underscores).

For `feat` and `fix`, a ticket number is mandatory.

Examples:
- `fix/3562-clickhouse-drop-sync-perf`
- `feat/1234-add-new-destination`

## Steps

### 1. Parse and validate

Extract from `$ARGUMENTS`:
- `branch_name`: Full branch name (e.g., `fix/3562-clickhouse-drop-sync-perf`)
- `category`: Prefix before `/` (e.g., `fix`)
- `issue_number`: Number after `/` and before first `-` (e.g., `3562`)
- `short_name`: Directory-friendly version: `{category}-{issue_number}-{first-few-words}` (e.g., `fix-3562-clickhouse-drop-sync`)

Validate the branch name matches pattern `(feat|fix|exp|test|docs|keep)/[0-9]+-[a-z0-9-]+`.

### 2. Verify the issue exists

```
gh issue view <issue_number> --json number,title,state
```

Warn if the issue doesn't exist or is closed, but continue.

### 3. Fetch latest devel

Fetch the newest devel from origin so the branch starts from the latest code:

```
git fetch origin devel
```

### 4. Create the worktree

Use `/create-worktree` skill:

```
/create-worktree <short_name> --branch origin/devel
```

Then create the feature branch inside the worktree:

```
git -C <worktree-path> checkout --no-track -b <branch_name>
```

`--no-track` leaves the branch without an upstream, so the user's `git push` works.

### 5. Set up dev environment

Use `/worktree-make-dev` skill to set up the development environment in the worktree. This runs `make dev` and copies `secrets.toml`.

Note which secrets source was used — this determines what destinations can be tested.

### 6. Verify cwd

After dev setup, verify the cwd is still in the worktree:

```
pwd
```

If `pwd` does not show the worktree path, run `cd <worktree-path>` and verify again. Stop with an error if the cwd cannot be set.

### 7. Report

Report the worktree info and available test destinations:

```
Worktree ready: <worktree-path>
Branch: <branch_name> (based on origin/devel)
Issue: #<issue_number> - <issue_title>
```

Include the test credential availability from `/worktree-make-dev` output — downstream skills need this to know which destinations can be tested.