using-git-worktrees

The using-git-worktrees skill provides a systematic framework for software development agents to manage parallel branches without the friction of constant context switching. By utilizing git worktrees, the agent creates isolated workspaces that share the same underlying repository, allowing for concurrent implementation, testing, and debugging. This skill is designed for engineering workflows that require clean, isolated environments for feature development or bug fixes.

• Automated directory selection prioritizes local hidden folders like .worktrees or dedicated global config paths to ensure consistent workspace organization.

• Mandatory safety verification uses git check-ignore to ensure the workspace directory does not conflict with repository tracking, preventing accidental source code pollution.

• Intelligent project setup detects file markers such as package.json, Cargo.toml, requirements.txt, or go.mod to automatically trigger installation commands like npm install, cargo build, or pip install.

• Baseline testing integration mandates the execution of project-specific test suites before a workspace is considered ready, ensuring the development environment starts in a known clean state.

• Strict adherence to project conventions and existing documentation (CLAUDE.md) prevents the agent from making unauthorized directory choices.

• Always announce intent before execution: "I'm using the using-git-worktrees skill to set up an isolated workspace."

• If an unignored directory is detected for project-local worktrees, the skill mandates immediate remediation by adding the path to .gitignore and committing the change before proceeding.

• When encountering failing baseline tests, the agent must report the specific issues and request human intervention rather than proceeding into an unstable development environment.

• Ideal for use cases involving multi-feature development, complex branch management, or subagent-driven-development flows where rapid context switching could lead to configuration errors.

• The skill functions as a prerequisite for implementation tasks, ensuring all dependencies are ready and the code baseline is verifiable before any new logic is injected into the repository.