Worktree Agent Skill

Git worktree management for any AI coding tool that supports the Agent Skills open format — create, list, remove, and prune worktrees with flexible placement strategies.

Who this is for

• Developers who work on multiple branches simultaneously and want a consistent worktree workflow
• Teams who want their AI agent to handle worktree operations with safe defaults (force removal, auto-prune, .gitignore management)
• Anyone tired of remembering the git worktree command syntax

How to Use This Skill

Option A: Using skills.sh (recommended)

Install this skill with a single command:

npx skills add https://github.com/jamesyorke/worktree-agent-skill --skill worktree-manager

Then use the skill in your AI agent, for example:

Use the worktree skill to create a new worktree for feature/auth off develop

Option B: Claude Code Plugin

Personal Usage

To install this Skill for your personal use in Claude Code:

1. Add the marketplace:

   /plugin marketplace add jamesyorke/worktree-agent-skill

2. Install the Skill:

   /plugin install worktree-manager@worktree-agent-skill

Project Configuration

To automatically provide this Skill to everyone working in a repository, configure the repository's .claude/settings.json:

{
  "enabledPlugins": {
    "worktree-manager@worktree-agent-skill": true
  },
  "extraKnownMarketplaces": {
    "worktree-agent-skill": {
      "source": {
        "source": "github",
        "repo": "jamesyorke/worktree-agent-skill"
      }
    }
  }
}

Option C: Manual install

1. Clone this repository.
2. Install or symlink the worktree-manager/ folder following your tool's official skills installation docs.
3. Use your AI tool as usual and ask it to use the "worktree-manager" skill.

What This Skill Offers

Create Worktrees

• Create a new branch and worktree in one step
• Check out an existing branch into a new worktree
• Choose between subfolder (.worktrees/) or sibling directory placement
• Automatic .gitignore management for subfolder worktrees

List Worktrees

• View all worktrees with their paths, commits, and branches
• Porcelain output for scripting

Remove Worktrees

• Safe removal with --force (handles submodules automatically)
• Automatic pruning of stale references after removal
• Cleanup of empty .worktrees/ directories

Troubleshooting

• Submodule removal errors
• Branch already checked out conflicts
• Stale worktree references
• .gitignore issues

Skill Structure

worktree-manager/
├── SKILL.md                    # Main skill file with routing and agent contract
└── references/
    ├── _index.md               # Navigation index
    ├── creating.md             # Creating worktrees (new branch or existing)
    ├── listing.md              # Listing and inspecting worktrees
    ├── placement.md            # Subfolder vs parent folder strategies
    ├── removing.md             # Removing, pruning, cleanup
    └── troubleshooting.md      # Common errors and fixes

License

This skill is open-source and available under the MIT License. See LICENSE for details.