Finishing a Development Branch
obra/superpowers
Walks the last step of a branch: confirm tests pass, detect the git environment, ask how to integrate, carry out your choice and clean up the worktree.
Create and manage git worktrees for parallel development. An agent skill from forrestchang/worktree-workflow.
Install Worktree
$ npx skills add forrestchang/worktree-workflow --skill worktree -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install forrestchang/worktree-workflow worktree --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/forrestchang/worktree-workflow.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/worktree .claude/skills/worktree && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "worktree" agent skill from https://github.com/forrestchang/worktree-workflow/tree/main/skills/worktree into .claude/skills/worktree/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "worktree", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/forrestchang/worktree-workflow/tree/main/skills/worktreeType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add forrestchang/worktree-workflow --skill worktree -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install forrestchang/worktree-workflow worktree --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/forrestchang/worktree-workflow.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/worktree .agents/skills/worktree && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "worktree" agent skill from https://github.com/forrestchang/worktree-workflow/tree/main/skills/worktree into .agents/skills/worktree/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "worktree", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add forrestchang/worktree-workflow --skill worktree -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install forrestchang/worktree-workflow worktree --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/forrestchang/worktree-workflow.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/worktree .cursor/skills/worktree && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "worktree" agent skill from https://github.com/forrestchang/worktree-workflow/tree/main/skills/worktree into .cursor/skills/worktree/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "worktree", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/forrestchang/worktree-workflow.git --path skills/worktree--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add forrestchang/worktree-workflow --skill worktree -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install forrestchang/worktree-workflow worktree --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/forrestchang/worktree-workflow.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/worktree .gemini/skills/worktree && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "worktree" agent skill from https://github.com/forrestchang/worktree-workflow/tree/main/skills/worktree into .gemini/skills/worktree/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "worktree", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install forrestchang/worktree-workflow worktreeInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add forrestchang/worktree-workflow --skill worktree -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/forrestchang/worktree-workflow.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/worktree .github/skills/worktree && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "worktree" agent skill from https://github.com/forrestchang/worktree-workflow/tree/main/skills/worktree into .github/skills/worktree/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "worktree", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add forrestchang/worktree-workflow --skill worktree -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install forrestchang/worktree-workflow worktree --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/forrestchang/worktree-workflow.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/worktree .opencode/skills/worktree && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "worktree" agent skill from https://github.com/forrestchang/worktree-workflow/tree/main/skills/worktree into .opencode/skills/worktree/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "worktree", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
worktree- GitHub stars
- 108
- Token cost
- ~1.4k tokens
- SKILL.md length
- 359 words
- Files
- 1
- Skills in repo
- 1
- Repo updated
- First seen
- Licence
- MIT
At a glance
Create and manage git worktrees for parallel development. An agent skill from forrestchang/worktree-workflow.
- Works in 6 steps: Get repository info → Check repository status → Determine base branch → …
- You need to work on multiple branches simultaneously without stashing
- SKILL.md covers Arguments, Worktree Directory Convention, Instructions and Temporary Branch Handling, plus 4 more sections
- Calls git
What it does
Worktree is an agent skill from forrestchang/worktree-workflow. Create and manage git worktrees for parallel development. Use when you need to work on multiple branches simultaneously without stashing or switching contexts.
Its SKILL.md is about 1.4k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It sits in Development, covering Git worktrees. The repository describes itself as: A toolkit for parallel development with git worktrees, designed for Claude Code. The licence is MIT.
When your agent uses it
- You need to work on multiple branches simultaneously without stashing
- Switching contexts
Example prompts
- “/worktree”
Requirements
- Pre-approved tools (allowed-tools): Bash(git *), Bash(ls *), Bash(mkdir *), Bash(basename *)
Workflow steps
6 steps, taken from the first numbered list in SKILL.md.
- Get repository info
- Check repository status
- Determine base branch
- Create the worktree
- Verify creation
- Report to user
What it can do on your machine
Read from SKILL.md and the folder at commit 7095bb4. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves these tools, so the agent can use them without asking each time:
Bash(git *)Bash(ls *)Bash(mkdir *)Bash(basename *)
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
git
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Worktree loads about 1.4k tokens when it runs. Until then it costs about 42 tokens; SKILL.md has 359 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from forrestchang/worktree-workflow at commit 7095bb4, republished under its MIT licence (© forrestchang). 359 words, ~1,388 tokens.
Download SKILL.mdSave it as
.claude/skills/worktree/SKILL.md (or your agent's skills folder).- name
- worktree
- description
- Create and manage git worktrees for parallel development. Use when you need to work on multiple branches simultaneously without stashing or switching contexts.
- allowed-tools
- Bash(git *), Bash(ls *), Bash(mkdir *), Bash(basename *)
- argument-hint
- [branch-name] [base-branch]
Git Worktree Workflow
Create a git worktree to enable parallel development on multiple branches.
Arguments
- First argument: New branch name (required)
- Second argument: Base branch to create from (optional, auto-detects default branch)
Worktree Directory Convention
Worktrees are created in ../worktrees/<repo-name>-<branch-name> relative to the main repository.
This naming convention:
- Keeps all worktrees in a shared
worktreesdirectory above the repo - Includes repo name to avoid conflicts when working on multiple projects
- Includes branch name for easy identification
Example: If working in /home/user/projects/my-app on branch feature-auth, the worktree path would be /home/user/projects/worktrees/my-app-feature-auth
Instructions
Get repository info
bash # Get repo root and name repo_root=$(git rev-parse --show-toplevel) repo_name=$(basename "$repo_root")Check repository status
bash git status git worktree listDetermine base branch
- Use the second argument if provided
- Otherwise, detect default branch:
bash # Try remote HEAD first git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' # Fallback to checking main/master git show-ref --verify --quiet refs/remotes/origin/main && echo "main" git show-ref --verify --quiet refs/remotes/origin/master && echo "master"
Create the worktree
bash # Define paths branch_name="<first-argument>" # Convert slashes in branch name to dashes for directory name # e.g., "feature/user-auth" -> "feature-user-auth" dir_safe_branch="${branch_name//\//-}" worktrees_dir="$(dirname "$repo_root")/worktrees" worktree_path="$worktrees_dir/${repo_name}-${dir_safe_branch}" # Create worktrees directory if needed mkdir -p "$worktrees_dir" # Fetch latest from base branch git fetch origin <base-branch> # Create worktree with new branch from base git worktree add "$worktree_path" -b "$branch_name" origin/<base-branch>Verify creation
bash git worktree listReport to user
- Confirm the new worktree path
- Show which branch it's based on
- Remind user how to navigate:
cd <worktree_path>
Show full SKILL.md (259 more words)Show less
Temporary Branch Handling
When a branch has a temporary name (pattern: wt-* or similar timestamp-based names), you should:
Detect temporary branch
bash branch=$(git branch --show-current) if [[ "$branch" == wt-* ]]; then # This is a temporary branch fiAsk about the task context
- What feature or fix is being worked on?
- Is there an issue ID (e.g., ISSUE-123)?
Suggest and rename the branch
bash # Rename to a meaningful name based on the task git branch -m <old-name> <new-name>Naming conventions:
feature/<description>- New featuresfix/<description>- Bug fixesrefactor/<description>- Code refactoringdocs/<description>- Documentation changesISSUE-123-<description>- When linked to an issue tracker
Example interaction:
User: Let's add user authentication Claude: I notice the current branch has a temporary name 'wt-1706789012'. Based on your task, I'll rename it to something more descriptive. [Runs: git branch -m wt-1706789012 feature/user-auth] Branch renamed to 'feature/user-auth'. Now let's implement the authentication...
Cleanup Instructions
When the user wants to remove a worktree:
# Get current repo info
repo_root=$(git rev-parse --show-toplevel)
repo_name=$(basename "$repo_root")
branch_name="<branch-name>"
# Convert slashes in branch name to dashes for directory name
dir_safe_branch="${branch_name//\//-}"
worktrees_dir="$(dirname "$repo_root")/worktrees"
# Remove a specific worktree
git worktree remove "$worktrees_dir/${repo_name}-${dir_safe_branch}"
# Or manually delete and prune
rm -rf "$worktrees_dir/${repo_name}-${dir_safe_branch}"
git worktree prune
# List remaining worktrees
git worktree listExamples
# Create a feature branch worktree from auto-detected default branch
/worktree feature/user-auth
# Create a feature branch worktree from main
/worktree feature/user-auth main
# Create a hotfix worktree from production branch
/worktree hotfix/login-bug productionIntegration with claude-wt
This skill works with the claude-wt bash script:
claude-wtcreates a worktree with a temporary branch name (e.g.,wt-1706789012)- The worktree is created at
../worktrees/<repo-name>-<branch-name> - Claude Code starts in the worktree directory
- When the user describes their task, rename the branch appropriately
- Continue with the implementation
Red Flags
Never:
- Proceed with a temporary branch name (
wt-*) without asking about renaming - Create worktrees in directories that don't follow the convention
Always:
- Use the path convention:
../worktrees/<repo-name>-<branch-name> - Detect and offer to rename temporary branches
- Auto-detect the default branch if not specified
- Verify worktree creation with
git worktree list
© forrestchang, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
Just SKILL.md in skills/worktree of forrestchang/worktree-workflow.
Open the folder on GitHubat commit 7095bb4
Compare with similar skills
Worktree next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Worktree this skillforrestchang/worktree-workflow | 108 | — | ~1.4k | Automated safety check: Pass | MIT | |
| Finishing a Development Branchobra/superpowers | 296k | 5 repos | ~1.9k | Automated safety check: Pass | MIT | |
| Migrate Core Code to Submodulestinyhumansai/openhuman | 41k | — | ~2.6k | Automated safety check: Pass | GPL-3.0 | |
| Finishing A Development Branchfarm-fe/farm | 5.6k | 33 repos | ~1.8k | Automated safety check: Pass | MIT | |
| Git Worktree Cleanuplobehub/lobehub | 83k | — | ~2.8k | Automated safety check: Pass | Custom licence | |
| Keep Codex Fastvibeforge1111/keep-codex-fast | 1.6k | — | ~3.1k | Automated safety check: Pass | MIT |
Similar skills
Migrate Core Code to Submodules
tinyhumansai/openhuman
Plans and carries out moving non-host-specific code and its tests from the OpenHuman core into vendored tiny submodule libraries, then releases the submodule and re-pins the host.
Finishing A Development Branch
farm-fe/farm
A skill your agent uses when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for…
Git Worktree Cleanup
lobehub/lobehub
Audits stale Git worktrees and branches with a bundled script, classifies each one, and deletes only after you approve the exact candidates.
Keep Codex Fast
vibeforge1111/keep-codex-fast
A skill your agent uses when Codex feels slow or bloated, when local sessions/logs/worktrees/config have grown over time, or when a user wants safe maintenance for Codex Desktop/CLI state.
Pre-Release PR Triage
jamiepine/voicebox
Sorts a backlog of open pull requests into must-merge, candidate, superseded and deferred, writes a triage doc and works the merge loop before a release.
Related
Categories
Questions about Worktree
What does Worktree do?
Create and manage git worktrees for parallel development. An agent skill from forrestchang/worktree-workflow. Worktree is an agent skill from forrestchang/worktree-workflow. Create and manage git worktrees for parallel development.
When should I use Worktree?
Worktree fits situations like: you need to work on multiple branches simultaneously without stashing; switching contexts.
How do I install Worktree in Claude Code?
Run `npx skills add forrestchang/worktree-workflow --skill worktree -a claude-code`. Or copy the skill folder (skills/worktree in forrestchang/worktree-workflow) into .claude/skills/worktree in your project. Claude Code loads it when a task matches its description.
How do I install Worktree in Codex?
Run `npx skills add forrestchang/worktree-workflow --skill worktree -a codex`. Or copy the skill folder (skills/worktree in forrestchang/worktree-workflow) into .agents/skills/worktree in your project. Codex loads it when a task matches its description.
Can I use Worktree in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add forrestchang/worktree-workflow --skill worktree -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/worktree, .gemini/skills/worktree, .github/skills/worktree and .opencode/skills/worktree in your project.
What does Worktree need to run?
Going by SKILL.md and its folder, Worktree needs the command-line tools its instructions call (git). Its frontmatter pre-approves these tools: Bash(git *), Bash(ls *), Bash(mkdir *), Bash(basename *).
Does Worktree access the network?
SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.
Is Worktree safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Worktree use?
Worktree is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Worktree use?
About 1.4k tokens (SKILL.md is roughly 5.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Worktree?
Skills that share tags, products or a category with Worktree: Finishing a Development Branch (obra/superpowers, 296k stars), Migrate Core Code to Submodules (tinyhumansai/openhuman, 41k stars), Finishing A Development Branch (farm-fe/farm, 5.6k stars) and Git Worktree Cleanup (lobehub/lobehub, 83k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Worktree?
forrestchang (a GitHub user) maintains it in forrestchang/worktree-workflow, which has 108 GitHub stars. The repository was last updated on February 1, 2026.
Source: forrestchang/worktree-workflow on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.