create-git-worktree
Manual invocation only; use only when the user explicitly requests `create-git-worktree` by exact name. Create a clean git worktree for the current repository and symlink reusable local tool-state directories into it.
Best use case
create-git-worktree is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Manual invocation only; use only when the user explicitly requests `create-git-worktree` by exact name. Create a clean git worktree for the current repository and symlink reusable local tool-state directories into it.
Teams using create-git-worktree should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/create-git-worktree/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How create-git-worktree Compares
| Feature / Agent | create-git-worktree | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Manual invocation only; use only when the user explicitly requests `create-git-worktree` by exact name. Create a clean git worktree for the current repository and symlink reusable local tool-state directories into it.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Create Git Worktree Manual invocation only: use this skill only when the user explicitly requests `create-git-worktree` by exact name. Create a fresh worktree from the current repository while leaving the active checkout untouched. Prefer the bundled script so branch handling, default paths, and safe symlink rules stay consistent. ## Quick Start Run: ```bash bash scripts/create_worktree.sh [--branch BRANCH] [--path TARGET_PATH] [--link-dir NAME] ``` Use these defaults unless the user says otherwise: - Source ref: current branch from `git branch --show-current` - Target path: `<repo-root>/.shadow-repo/worktree-<ts>` - Timestamp format: `YYYYMMDD-HHMMSS` in UTC - Extra symlink dirs: none If the user specifies a path, use it instead of the default. If the user specifies extra directories to reuse, pass them with repeated `--link-dir` flags. ## Workflow ### 1. Resolve the source ref - Use the user-selected branch or ref if provided. - Otherwise use the current branch. - If the current checkout is detached and the user did not provide a branch or ref, pause and ask for one. ### 2. Create the worktree with Git - Use `git worktree add`; do not copy the repository manually. - If the source ref is a local branch that is not checked out in another worktree, create a normal branch worktree. - If that branch is already checked out elsewhere, create a detached worktree at the branch tip instead. This preserves the requested clean snapshot while avoiding Git's branch checkout conflict. ### 3. Symlink reusable local-state directories Consider these default candidates: - `.claude` - `.codex` - `.gemini` - `.github` - `.aider` - `.cursor` - `.continue` - `.windsurf` - `.kiro` Apply these rules for each candidate and for any user-requested extra directory: - Symlink only when the source path already exists in the repo root. - Skip the path if Git tracks any files under it. - Do not replace tracked content in the new worktree with a symlink. ### 4. Handle Pixi projects - Detect Pixi via `pixi.toml`, `pixi.lock`, or a `[tool.pixi]` section in `pyproject.toml`. - If the repo is Pixi-managed and `.pixi/` exists as an untracked directory, symlink it into the new worktree. ### 5. Verify and report Report: - The created worktree path - The source ref used - The resulting commit - Whether the worktree is attached to a branch or detached - Which directories were linked - Which directories were skipped because they were tracked Note that `git status` in the new worktree may show the linked local-state directories as untracked. That is expected. ## Resources - `scripts/create_worktree.sh`: Create the worktree and add the safe symlinks. ## Example Prompts - `Create a shadow worktree for this repo under .shadow-repo and link the agent home directories.` - `Make a clean worktree of branch release/1.4 at tmp/release-wt and reuse .claude and .pixi.` - `Create a worktree for this repo at /tmp/gig-agents-clean; keep my current uncommitted changes untouched.`
Related Skills
impl-via-git-worktree
Manual invocation only; use only when the developer explicitly requests `impl-via-git-worktree` or asks for implementation in a fresh local branch/worktree. Snapshot the current repository state into a new local `feature/topic-slug` or `fix/topic-slug` branch, create a separate git worktree, bridge the ignored local resources that worktree needs, implement and test there, and commit the result without pushing. If the target is an OpenSpec change or a path under `openspec/changes/`, derive the change from that target and, once inside the worktree, use OpenSpec tooling plus `openspec-apply-change` there instead of manually assuming artifact paths.
pixi-make-offline-channel
Use when the user wants to create a self-hosted, offline-installable Conda channel (mirror) containing a specific subset of packages using Pixi.
pixi-make-cu-build-env
Guides the agent to setup a new or existing Pixi environment for compiling C++ and CUDA code. It ensures the correct compilers, toolkits, and CMake configurations are in place for a robust user-space build.
pixi-install-nvidia
Use when the user says "use pixi to install <some nvidia tool>" (or similar) and wants NVIDIA/CUDA/GPU packages installed via Pixi (no sudo/apt), e.g., CUDA toolkit pieces, cuDNN/NCCL, PyTorch CUDA builds, RAPIDS.
pei-docker-usage
Helper for PeiDocker (`pei-docker-cli`). Trigger ONLY when the user explicitly requests PeiDocker usage OR when working within a PeiDocker-generated project (indicated by `user_config.yml`).
conan-basic-usage
Basic operations for the Conan C++ package manager. Use when the user explicitly asks to 'use conan' for tasks like creating projects, installing dependencies, or building packages, or asks for 'how to' guidance on Conan setup.
explore-dnn-model
Manual invocation only; use only when the user explicitly requests `explore-dnn-model` by name. Explore how to run a given DNN model checkpoint in the current Python environment by locating weights + upstream source code, resolving dependencies with user confirmation, running reproducible experiments under `tmp/`, and producing reports about I/O contracts, timing, and profiling.
openspec-ext-revise-by-decision
Manual invocation only; use only when the user explicitly requests `openspec-ext-revise-by-decision` by exact name. Revise OpenSpec change artifacts from a review or decision document that contains questions plus `DECISION` blocks, applying chosen decisions from a review file such as `openspec/changes/<change>/review/review-*.md` back into proposal, design, specs, and tasks.
openspec-ext-review-plan
Review an OpenSpec change (or a single OpenSpec change artifact file) for completeness, coherence, and alignment with existing system design; capture actionable feedback plus open questions; write a review report under the change directory (review/review-YYYYMMDD-HHMMSS.md).
openspec-ext-respond-to-review
Read an OpenSpec review report critically, evaluate the reviewer's proposals and findings against the current change artifacts and repository context, and write developer-owned final decisions/responses back into the review document. Use when the user explicitly mentions `openspec` or points to a path under `openspec/` while asking to examine a review report carefully, decide open questions, respond to findings, fill `DECISION` blocks, respond to an OpenSpec review file, or record final answers in an OpenSpec review document without yet revising the proposal, design, specs, or tasks.
openspec-ext-hack-through-test
Manual invocation only. OpenSpec-specific hack-through-testing workflow targeting production-level end-to-end paths using real data and real user workflows — not CI smoke/unit/integration tests. Three subskills: `propose` to create an OpenSpec change with HTT-ready test cases (automatic scripts and interactive guides) by invoking `openspec-propose` or `openspec-ff-change`, `revise` to update an existing OpenSpec change so its artifacts support hack-through-testing-driven implementation and testing, and `run` to exercise an implemented OpenSpec change through the full hack-through-testing loop (in-place by default, or in a disposable snapshot worktree when requested). Use when the user explicitly asks for `openspec-ext-hack-through-test`, points to `openspec/changes/...` while asking to propose, revise, run, exercise, or prepare work under hack-through-testing principles, or wants OpenSpec work shaped for fast blocker discovery through patch-forward testing.
openspec-ext-explain
Create or update OpenSpec change explanation docs that capture developer-facing questions and answers under `openspec/changes/.../explain/`. Use when the user explicitly mentions `openspec` or points to a path under `openspec/` while asking to create, update, document, or maintain a Q&A, FAQ, explain note, or question-and-answer doc for an OpenSpec change based on user questions, implementation notes, review questions, or current chat context.