The using-git-worktrees Skill — Isolated Workspaces Without Fighting the Harness
How the using-git-worktrees skill sets up a clean, isolated workspace before feature work — and why it checks for existing isolation before touching anything.
Starting implementation directly on a working branch is a reliable way to produce untraceable state. The using-git-worktrees skill provides a structured procedure for setting up an isolated workspace before any feature work begins. Its core principle: detect existing isolation first, use native tools before git fallback, and never fight the harness.
Step 0 — detect before creating
The first action is always detection, not creation. Two shell commands determine the state: comparing GIT_DIR to GIT_COMMON_DIR reveals whether the current directory is already a linked worktree. If they differ, the workspace is already isolated — no new worktree is created. There is a submodule guard: the same difference in paths occurs inside git submodules, so the skill checks git rev-parse --show-superproject-working-tree to distinguish the two cases.
If the current directory is not isolated and the user has not already indicated their preference, the skill asks for consent before proceeding. If consent is declined, work continues in place.
Native tools first
When isolation is needed, the skill checks whether the runtime already provides a worktree mechanism — a tool named EnterWorktree, a /worktree command, or a --worktree flag. If one exists, it is used. Native tools handle directory placement, branch creation, and cleanup automatically. Using git worktree add when a native tool is available creates phantom state the runtime cannot track.
Only when no native tool exists does the skill fall back to manual git worktree creation. Directory selection follows a priority: existing project-local directory (.worktrees/ or worktrees/), then global (~/.worktrees/project/), then the declared preference in instructions, then the default .worktrees/ at the project root.
Safety check before creation
For project-local directories, the skill runs git check-ignore before creating anything. If the directory is not already ignored, it adds it to .gitignore and commits the change first. This prevents worktree contents from being tracked and polluting git status. Global directories under ~/.worktrees/ are outside any repository and require no ignore verification.
Setup and baseline
Once the workspace exists, the skill auto-detects the project's package manager or build tool from the manifest file and runs the appropriate install command. Then it runs the project's canonical test command. If tests fail, it reports the failures and asks whether to proceed — working with a failing baseline makes it impossible to distinguish new regressions from pre-existing ones.
The using-git-worktrees skill is invoked at the start of feature work and before executing plans. It connects naturally with the systematic-debugging skill when baseline tests unexpectedly fail. For Datarim's overall workflow, see what is Datarim.