using-git-worktrees

Creates isolated git worktree workspaces with native tool detection and baseline test verification.

Updated Aug 5, 2026
One-click install
npx skills add https://github.com/JhonMA82/api-starter --skill using-git-worktrees-jhonma82
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: using-git-worktrees
Source: https://github.com/JhonMA82/api-starter/tree/main/.agents/skills/using-git-worktrees
Command: npx skills add https://github.com/JhonMA82/api-starter --skill using-git-worktrees-jhonma82

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Starting feature work directly in your main checkout risks mixing unfinished changes with stable code. This Skill ensures every implementation task begins in an isolated workspace, detecting existing isolation first and falling back to git worktrees only when no native tool exists. ## Core Features & Use Cases - Isolation Detection: Compares git-dir and git-common-dir paths to detect existing worktrees, with a submodule guard to avoid false positives. - Native Tool Preference: Uses platform-native worktree tools (like EnterWorktree or /worktree commands) before falling back to manual git worktree add. - Safe Directory Handling: Selects .worktrees/ or worktrees/ directories, verifies they are git-ignored, and commits the ignore rule if missing. - Baseline Verification: Auto-detects the project type (Node, Rust, Python, Go), installs dependencies, and runs tests to confirm a clean starting state. - Use Case: Before implementing a new feature branch, the Skill checks you're not already isolated, creates .worktrees/feature-x, runs npm install and the test suite, and reports a ready workspace. ## Quick Start Ask the AI to set up an isolated worktree for your new feature branch and verify the project tests pass before starting implementation.

Frequently Asked Questions about using-git-worktrees

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create an isolated git worktree for a feature branch?▼

Run `git worktree add <path> -b <branch-name>` from your repository root. The Skill automates this by selecting a `.worktrees/` directory, verifying it is git-ignored, creating the branch, and changing into the new workspace.

How to check if I am already inside a git worktree?▼

Compare `git rev-parse --git-dir` with `git rev-parse --git-common-dir`. If the resolved paths differ, you are in a linked worktree. Also run `git rev-parse --show-superproject-working-tree` to rule out being inside a submodule.

Should I use git worktree add or a native worktree tool?▼

Prefer a native tool (such as EnterWorktree or a /worktree command) when one is available, since it manages placement, branching, and cleanup. Use manual `git worktree add` only as a fallback when no native tool exists.

Why must the worktrees directory be in .gitignore?▼

An unignored worktree directory causes the entire nested worktree contents to be committed into the parent repository. The Skill runs `git check-ignore` and adds the directory to .gitignore with a commit before creating anything.

What happens if git worktree add fails with a permission error?▼

A permission error usually means the sandbox blocked worktree creation. The Skill reports the sandbox denial, then continues working in the current directory, running dependency setup and baseline tests in place.

Why run baseline tests before starting feature work?▼

Running the project test suite first confirms the workspace starts clean. A dirty baseline makes every later test failure ambiguous, so failures are reported and the user decides whether to proceed or investigate.