Isolate repository work with ak:worktree

Use ak:worktree to place a Marketing implementation or validation task in an isolated Git checkout. The Skill can inspect repository shape, choose a branch and worktree location, preview creation, report health, and perform explicitly approved cleanup through its packaged Node.js helper.

Choose ak:worktree for repository isolation

Use ak:worktree when

• A campaign site, dashboard, automation, or documentation change should be isolated from current repository work.
• Independent tasks need separate branches and checkouts.
• You need to list worktrees or inspect dirty state, base-branch divergence, normalized paths, and stale metadata.
• You want a dry run before creating, removing, or pruning worktree state.

Choose another workflow when

• You only need a branch in the current checkout.
• The task does not change repository files and isolation adds no value.
• You want to implement the feature itself. Create the worktree first, then use the relevant implementation Skill inside it.
• You cannot approve the exact removal target. Do not run cleanup from an ambiguous name or partial match.

Prepare Git and the target

Before you start:

• Run from a Git repository with worktree support and Node.js 18 or newer.
• Preserve unrelated work and inspect staged, modified, and untracked files.
• Decide whether the repository is standalone, a monorepo, or part of a superproject; select a project when the monorepo match is not unique.
• Name the intended base branch when auto-detection is unsuitable.
• Decide whether dependency installation, remote fetches, submodule checkout, and environment-template copying are allowed.

Run the Skill

Ask for a dry run and state the cleanup boundary directly:

/ak:worktree "Create an isolated docs worktree for launch-brief validation. Use a docs branch, preview first, and do not install dependencies or remove any worktree"

/ak:worktree "Create an isolated docs worktree for launch-brief validation. Use a docs branch, preview first, and do not install dependencies or remove any worktree"

$ak:worktree "Create an isolated docs worktree for launch-brief validation. Use a docs branch, preview first, and do not install dependencies or remove any worktree"

Know the helper surface

Creation options are --prefix <type>, --base <branch>, --checkout-submodules, --no-prefix, --worktree-root <path>, --json, --dry-run, and the legacy --env <files>. Standard prefixes are feat, fix, refactor, docs, test, chore, and perf. --no-prefix preserves an approved exact branch name, including case and slash segments.

Understand the stages

1. Inspect the repository. The helper reports repoType, baseBranch, projects, worktreeRoot, worktreeRootSource, dirtyState, and dirtyDetails.
2. Choose branch semantics. The Skill preserves an explicitly exact branch with --no-prefix; otherwise it selects a type and creates a kebab-case slug.
3. Resolve project and location. It handles standalone, monorepo, and superproject layouts, asking when a project selection is ambiguous.
4. Preview the mutation. A --dry-run --json result shows the path, branch, base, location source, submodule choice, and existing-branch state.
5. Create only after review. Git adds the worktree and branch or attaches an existing branch. .env*.example templates are copied with .example removed; explicitly named legacy environment files may also be copied.
6. Handle setup separately. Dependency installation inferred from lockfiles and submodule checkout can use storage, compute, package registries, and the network; they need their own approval.
7. Report and hand off. The result records the worktree path, branch, base, copied templates, warnings, and next action.

Keep destructive and external effects controlled

The helper warns about a dirty source checkout but does not make that work safe automatically. remove uses forced worktree removal; uncommitted work in the target can be lost. Never select removal from a broad or ambiguous match.

Verify outputs and evidence

A successful creation should report:

• worktreePath, worktreeRootSource, branch, baseBranch, and baseBranchSource.
• Whether checkoutSubmodules was selected and whether an existing branch was reused.
• Any envTemplatesCopied, legacy envFilesCopied, and warnings.
• The current repository status and a clean ownership boundary for the next task.

For audits, review currentWorktree, normalized worktrees, dirty details, and ahead/behind values. For prune, review entries. For removal, confirm the reported path and whether the branch was deleted or kept.

Troubleshoot and respect limits

The Skill does not implement the feature, merge, push, publish, or deploy. Its automatic location and base choices are heuristics, and copied environment templates still need review before use. See Projects, artifacts, and checkpoints and continue with Marketing Kit after isolation is verified.