wt-switch-create - SKILL.md Agent Skill

name: wt-switch-create description: Create a new worktrunk worktree (optionally in another repo) and switch this session's working directory into it. Use when launching a session that should work in its own worktree. argument-hint: "[] [] [-- ]" license: MIT OR Apache-2.0 compatibility: Requires the `wt` CLI (https://worktrunk.dev)

Arguments: $ARGUMENTS. Grammar: [<branch>] [<repo>] [-- <task>].

branch — optional; the branch name for the new worktree. When omitted, pick one (step 1 below).
repo — optional path; create the worktree in this repo instead of the session's current one.
task — optional; what to do inside the new worktree. No task means enter the worktree and wait.

Tokens before the -- are the branch and/or repo: a path-shaped token (starting with /, ~, ./, or ../) is the repo; any other token is the branch (docs is a branch name, never the docs/ directory). More than one branch-shaped token before a -- doesn't fit the grammar — ask. Without a --, judge where the task starts: leading tokens that read as a branch name (fix-auth) or a repo path are consumed as such, and the rest is the task; otherwise the whole input is the task (fix the parser bug has no branch-shaped lead — all task).

/wt-switch-create my-feature -- fix the parser bug
/wt-switch-create -- fix the parser bug
/wt-switch-create my-feature ~/workspace/other-repo -- fix the parser bug
/wt-switch-create my-feature

What to do

Steps 1–3 come before any other work.

Pick the branch name if none was given: short, from the task and consistent with existing worktree names, or, mid-session, from the work being moved; with nothing to derive from, ask.
Create the worktree with a Bash call (omit -C <repo> for this repo):
```
wt -C <repo> switch --create <branch> --no-cd --format=json
```
Stdout is JSON whose path field is the worktree's absolute path (status lines go to stderr). On Branch <branch> already exists: if the user named the branch, rerun without --create (it enters the branch, creating its worktree if missing); if step 1 picked the name, pick another and rerun. Any other failure (not a git repo, invalid name): report it and stop.

Mid-session, carry uncommitted work across: git stash push -u before creating the worktree, then git -C <path> stash pop after (the stash is shared across worktrees).
Enter the worktree, then do the task. Call EnterWorktree({path: "<path from the JSON>"}).
- Accepted → the session is re-rooted in the worktree. Do the task (or, with no task text, confirm it's ready and wait).
- Rejected → graceful, and nothing is created. EnterWorktree re-roots only into a worktree the session is permitted to enter, and that permitted set is fixed by two factors: the repo your cwd resolves to, and the session's state. Each rejection is just that set coming up empty or without the target: no repo resolves (cwd is outside any git repo, e.g. a non-git parent such as ~/workspace that only holds repos, as in a background job), which fails with the current directory is not in a git repository; the target belongs to a different repo than the one resolved; or the session is already rooted in a worktree (or is a pinned agent), a state that narrows the set to the resolved repo's .claude/worktrees/ and so excludes even a same-repo wt sibling. All reduce to the same recovery test: whether you can cd into the worktree, which works when it's inside an allowed directory (a permissions.additionalDirectories entry such as ~/workspace). So cd <path> and read the result:
  - no Shell cwd was reset notice → it stuck; the worktree is reachable. Work there, but a bare cd is not a tracked re-root, so the cwd can revert to the session's launch worktree across turns (and in spawned subagents); pin commands with git -C <path> / wt -C <path> rather than trusting the cd to persist.
  - Shell cwd was reset → not reachable. Stop and ask the user to make it reachable: add the repo, or a parent like ~/workspace, to permissions.additionalDirectories (durable, every session), or run /add-dir <path> (this session). Then continue. Don't grind through absolute paths with cd resetting on every command.

Cleanup

The worktree is a normal worktrunk worktree: it persists after the session ends, shows up in wt list, and is merged or removed with wt merge / wt remove <branch> like any other. Don't remove it unprompted. If the user asks to leave mid-session, ExitWorktree({action: "keep"}) returns the session to its original directory; ExitWorktree cannot remove a worktree entered by path, so removal is always wt remove <branch>.

Scope

This command authorizes creating/entering ONE worktree (in the named repo, if one was given) and doing the requested task. Commits, pushes, and merges still each require explicit user permission.