Worktree Skill

The /worktree Claude Code skill is a thin wrapper around scripts/setup-worktree.sh: give it a ticket/PR id or a branch name and it resolves the right branch, creates the worktree, and switches your Claude session into it. For the underlying flags (--db isolation, ports, config patching, teardown), see Worktree Scripts.

/worktree <ENG-id | PR-id | branch-name>

NOTE

The scripts themselves are tracked in scripts/ — no install needed. Only the skill definition (SKILL.md) is per-machine under .claude/skills/worktree/ (.claude/ is gitignored); its tracked copy lives at apps/docs/skills/worktree/. Install it by asking Claude to "add the worktree skill", or cp apps/docs/skills/worktree/SKILL.md .claude/skills/worktree/.

What the skill adds over the raw script

• Resolves an ENG/PR id to the correct branch before creating anything (below).
• Switches the Claude session into the new worktree so work continues there.
• Everything else — free ports, config patching, --db isolation, VS Code workspace, removal — is the script's job. See Worktree Scripts.

Resolving an ENG / PR id

Give the skill a ticket or PR id and it finds the right branch before creating anything:

• ENG-<n> — looks up the Linear issue, reports its title/state/url and canonical gitBranchName, and lists any linked GitHub PRs.
• PR-<n> — runs gh pr view and uses the PR's head branch.

It then checks whether that branch already exists (locally and on origin):

• Exists → the worktree is created on that branch (local checkout, or fetch-and-track for a remote-only branch). No fork.
• Doesn't exist → a new branch is created from the Linear gitBranchName (or a eng-<n>-<slug> convention name).

A plain branch name skips resolution and is used as-is.

Remove

Ask Claude to "remove the worktree" — it runs scripts/remove-worktree.sh. See Worktree Scripts → Remove a worktree for flags and the --db teardown.