[feature-description] Required Feature description
Natural-language feature or fix to isolate in a new worktree. May be an exact branch name; omit when running an explicit maintenance command.
/ak:worktree fix checkout retry handling Quick Ref / Command
Engineer Kit
/ak:worktree
Create, inspect, and clean isolated git worktrees for parallel feature work, worktree audits, stale metadata cleanup, monorepos, and submodule workflows.
Read repo info
Detect exact names
Infer branch type
Build the slug
Rule 01
Start by reading repo metadata with scripts/worktree.cjs info --json.
Rule 02
Use --no-prefix when the user supplied an exact branch name or convention.
Rule 03
Let configured worktree roots resolve by priority; use --worktree-root only for true overrides.
Rule 04
In monorepos, ask for or supply the project before creating the worktree.
Rule 05
Rely on env-template copying and background dependency installation inside the new worktree.
Core lanes from input to output, aligned with the command's real execution path.
Start
Input, scope, route
Work
Agent / skill execution
Verify
Gate, review, validation
Close
Report, handoff, artifact
How to invoke the skill: syntax, positional arguments, shared options, then each subcommand with its own syntax and outcome.
Syntax
/ak:worktree [feature-description]or
/ak:worktree [project] [feature]or
/ak:worktree <create|info|list|status|remove|prune> ...[feature-description] Required Feature description
Natural-language feature or fix to isolate in a new worktree. May be an exact branch name; omit when running an explicit maintenance command.
/ak:worktree fix checkout retry handling [project] Monorepo project
Optional project name or path for monorepos. It selects which project receives the new isolated checkout.
/ak:worktree web fix checkout redirect [feature] Project feature
Feature description used with a monorepo project. The skill still derives or preserves the branch name from this value.
/ak:worktree web fix checkout redirect --prefix <type> Branch prefix
Override the inferred branch type. Allowed values are feat, fix, refactor, docs, test, chore, and perf.
/ak:worktree create login hardening --prefix fix --base <branch> Base branch
Use an existing branch instead of the automatic dev, develop, main, then master detection order.
/ak:worktree create analytics export --base release/next --no-prefix Preserve exact name
Skip prefixing and preserve a validated supplied branch name, including case and safe slash segments.
/ak:worktree create ND-1377-cleanup-docs --no-prefix --worktree-root <path> Worktree root
Override where this skill places new worktrees after path validation. It does not affect host-created worktrees.
/ak:worktree create billing dashboard --worktree-root ../app-worktrees --checkout-submodules Checkout submodules
Run recursive submodule initialization in the new worktree after creation.
/ak:worktree create sdk update --checkout-submodules --dry-run Preview only
Preview create, remove, or prune without applying that filesystem or Git operation.
/ak:worktree prune --dry-run --json Structured output
Return structured result and error fields for automation and audits.
/ak:worktree status --json create Create /ak:worktree create [project] <feature> [--prefix <type>|--no-prefix] [--base <branch>] [--worktree-root <path>] [--checkout-submodules] [--dry-run] [--json] Create or attach a branch in a new isolated worktree. Monorepos can pass the project first.
Outcome: New worktree path, branch, base branch, root source, copied env templates, warnings, and optional dependency setup evidence.
/ak:worktree create web fix checkout redirect info Info /ak:worktree info [--json] Read repository type, detected base, projects, worktree root, env file names, and dirty-state counts.
Outcome: Repository metadata for deciding project, branch, base, and placement before a create operation.
/ak:worktree info --json list List /ak:worktree list [--json] List normalized worktree records without removing or changing them.
Outcome: Normalized worktree paths, branches, and records for audit or selection.
/ak:worktree list --json status Status /ak:worktree status [--json] Inspect worktree health, normalized paths, current/main flags, dirty state, branch existence, detected base, and ahead/behind counts.
Outcome: Current checkout health plus normalized worktree records and base-branch divergence details.
/ak:worktree status --json remove Remove /ak:worktree remove <name-or-path> [--dry-run] [--json] Force-remove one matched worktree by exact name or path, then attempt a safe branch delete.
Outcome: Matched worktree removed when not dry-run; merged branches may be deleted safely, while unmerged branches are kept and reported.
/ak:worktree remove /Users/me/app-worktrees/feat-demo --dry-run prune Prune /ak:worktree prune [--dry-run] [--json] Clean stale Git worktree metadata. Use dry-run first for an audit pass.
Outcome: Stale metadata entries are listed in preview or removed during the confirmed prune operation.
/ak:worktree prune --dry-run Exact branch mode
Select --no-prefix for Jira-style keys, uppercase branch names, multi-segment branches, or explicit exact-name requests.
Root resolution
Location priority is CLI --worktree-root, project config, user config, WORKTREE_ROOT, superproject, monorepo, then sibling directory.
Safe prune
Use prune --dry-run as the first pass when auditing stale worktree metadata.
Concrete invocations for each flag, subcommand, mode, or route available in the live workflow.
/ak:worktree create billing dashboard /ak:worktree create ND-1377-cleanup-docs /ak:worktree create web fix checkout redirect /ak:worktreestatus--json
/ak:worktreeprune--dry-run
/ak:worktreeinfo--json
/ak:worktreelist--json
/ak:worktree remove billing-dashboard