How do I install the Worktree skill?

Run npx skillmds@latest add steveclarke/worktree in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Worktree safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Worktree?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Worktree free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Worktree?

steveclarke (@steveclarke) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Worktree by steveclarke — Agent Skill

Name: Worktree
Author: steveclarke

Worktree

Work in an isolated git worktree for issues, features, or refactors. Use when the user asks to spin up a worktree, work in isolation, create an isolated branch, or says "worktree" in the context of starting work on something.

steveclarke f68d8cb 2.4 KB Updated Sep 17, 2026

File contents

Worktree Workflow

Work on a task in an isolated git worktree with its own Lookbook instance.

1. Create the worktree

Use the EnterWorktree tool to create and switch into a worktree. Name it after the task when possible:

EnterWorktree(name: "fix-button-hover")

This creates a worktree in .claude/worktrees/, creates a branch based on HEAD, and switches your working directory into it.

2. Start Lookbook

Start Lookbook on the worktree's assigned port:

bin/worktree start

This daemonizes Lookbook + Tailwind and returns immediately. The port is deterministic (based on worktree name, range 4101-4600) and printed to stdout.

Print the URL for the user:

Lookbook → http://localhost:<port>/lookbook

Useful commands while working:

bin/worktree port       # Show the assigned port
bin/worktree status     # Check if services are running
bin/worktree stop       # Stop services (do this at the end)

3. Do the work

Work on the task. For component work, follow the contributing skill (.claude/skills/contributing/SKILL.md) for conventions.

4. Commit

The worktree already has its own branch (created by EnterWorktree). Commit to the current branch — do NOT create a new branch:

git add [specific files]
git commit -m "feat: description (#N)"

Run lint and tests before committing:

bundle exec standardrb --fix
bundle exec rake test

5. Push and create PR

git push -u origin $(git branch --show-current)

Create the PR. Include Closes #N in the body if working on an issue:

gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
- [what was done]

Closes #N

## Test plan
- [ ] Visual review in Lookbook
EOF
)"

Print the PR URL for the user.

6. Show Lookbook preview

Print the Lookbook URL so the user can review visually:

Lookbook → http://localhost:<port>/lookbook/inspect/kiso/<component>/playground
PR → https://github.com/steveclarke/kiso/pull/<number>

7. Cleanup

Stop Lookbook when the user is done reviewing:

bin/worktree stop

On session exit, Claude Code will prompt the user to keep or remove the worktree.

---name: worktreedescription: Work in an isolated git worktree for issues, features, or refactors. Use when the user asks to spin up a worktree, work in isolation, create an isolated branch, or says "worktree" in the context of starting work on something.---# Worktree WorkflowWork on a task in an isolated git worktree with its own Lookbook instance.## 1. Create the worktreeUse the `EnterWorktree` tool to create and switch into a worktree. Name itafter the task when possible:```EnterWorktree(name: "fix-button-hover")```This creates a worktree in `.claude/worktrees/`, creates a branch based onHEAD, and switches your working directory into it.## 2. Start LookbookStart Lookbook on the worktree's assigned port:```bashbin/worktree start```This daemonizes Lookbook + Tailwind and returns immediately. The port isdeterministic (based on worktree name, range 4101-4600) and printed tostdout.Print the URL for the user:```Lookbook → http://localhost:<port>/lookbook```Useful commands while working:```bashbin/worktree port # Show the assigned portbin/worktree status # Check if services are runningbin/worktree stop # Stop services (do this at the end)```## 3. Do the workWork on the task. For component work, follow the contributing skill(`.claude/skills/contributing/SKILL.md`) for conventions.## 4. CommitThe worktree already has its own branch (created by `EnterWorktree`). Committo the current branch — do NOT create a new branch:```bashgit add [specific files]git commit -m "feat: description (#N)"```Run lint and tests before committing:```bashbundle exec standardrb --fixbundle exec rake test```## 5. Push and create PR```bashgit push -u origin $(git branch --show-current)```Create the PR. Include `Closes #N` in the body if working on an issue:```bashgh pr create --title "<title>" --body "$(cat <<'EOF'## Summary- [what was done]Closes #N## Test plan- [ ] Visual review in LookbookEOF)"```Print the PR URL for the user.## 6. Show Lookbook previewPrint the Lookbook URL so the user can review visually:```Lookbook → http://localhost:<port>/lookbook/inspect/kiso/<component>/playgroundPR → https://github.com/steveclarke/kiso/pull/<number>```## 7. CleanupStop Lookbook when the user is done reviewing:```bashbin/worktree stop```On session exit, Claude Code will prompt the user to keep or remove theworktree.

Frequently asked questions