skills.rest
zhiyuan-zhang0206
zhiyuan-zhang0206COMMUNITY
Explore all skills by this author →
GitHub

worktree

Creates agent-named git worktrees for isolated coding changes before editing a repository.

1|Updated Aug 14, 2026
Search Tags:#git#pull request#isolation#uv#branching#worktree#venv
One-click install
npx skills add https://github.com/zhiyuan-zhang0206/Ava --skill worktree-zhiyuan-zhang0206
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: worktree
Source: https://github.com/zhiyuan-zhang0206/Ava/tree/main/ava_builtins/plugins/ava_code/skills/worktree
Command: npx skills add https://github.com/zhiyuan-zhang0206/Ava --skill worktree-zhiyuan-zhang0206

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When multiple agents or tasks share one source checkout, their edits overwrite each other into a messy diff. This Skill enforces working in a dedicated git worktree named with the agent id, so every change stays isolated and traceable to its owner. ## Core Features & Use Cases - Worktree Creation: Creates a branch ava-<id>-<task> from main and checks it out as a worktree in one command, with a two-step fallback when main is already the primary checkout. - Environment Bootstrap: Builds a real per-worktree virtual environment with uv sync and an editable install, since a fresh worktree has no .venv. - Safe Cleanup and Stash Rules: Explains why git stash is unsafe in shared checkouts and how to remove worktrees after the PR merges. - Use Case: Before fixing a one-line bug in a shared repository, an agent runs the documented command to create .worktrees/ava-7-bugfix, bootstraps its venv, makes the change, and opens a PR without touching the main checkout. ## Quick Start Ask the agent to create a git worktree named with its agent id and task before making any code changes to the repository.

Frequently Asked Questions about worktree

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

FAQPage Schema
How do I create a git worktree with a new branch?▼

Run git worktree add -b <branch> <path> main from the repo root to create the branch from main and check it out as a worktree in one step. The two-step alternative is git branch <branch> main followed by git worktree add <path> <branch>.

Why does git worktree add fail when main is checked out?▼

git worktree add <path> main fails because main is already the primary checkout and a branch cannot be checked out twice. Use the -b flag to create a new branch, or create the branch first and then add the worktree.

When should I not use a git worktree?▼

Skip the worktree for genuinely read-only work such as code analysis, and for single-agent sequential changes where no parallel task can overwrite your edits. Any actual modification to a shared repository should go through a worktree and a PR.

Why is git stash dangerous with multiple worktrees?▼

All worktrees share one .git directory, so git stash operates on a repo-wide list. A bare git stash pop can drop another agent's WIP into your tree; use git stash push -m <branch> and pop that explicit entry, or use git show and git diff instead.

How do I set up a virtual environment in a new worktree?▼

A fresh worktree has no .venv, so build a real one before the first commit: run the editable-venv guard script, then uv sync and uv pip install -e . with VIRTUAL_ENV unset. Never symlink an existing venv into the worktree.

Related Skills

Explore More Software Engineering Skills→
EveryIncEveryInc
24.7k

ce-worktree

Creates isolated git worktrees for new branches or existing refs like PRs and commits.

Official
Intermediate
josorio7122josorio7122
1

ship

Squash commits, push a feature branch, and open a pull request via GitHub CLI.

Community
Intermediate
socialsoftwaresocialsoftware
5

service-guard

Add a Layer 3 service-layer guard that reads the DB before mutations.

Official
Advanced
OpenAuthorityOpenAuthority
8

git_checkout

Checkout a Git branch or commit with uncommitted change safeguards.

Official
Intermediate