Skip to content
Skills Library
Programming · Automation

sc-git-worktree

/sc-git-worktree

Create, manage, scan, update, and clean up git worktrees for parallel development with protected branch safeguards. Use when working on multiple branches simultaneously, isolating experiments, updating protected branches (main/develop), cutting a gh-stack layer as a worktree (top or mid-stack insert), or when user mentions "worktree", "parallel branches", "feature isolation", "branch cleanup", "worktree status", "update main/develop", "stack layer worktree", or "stacked worktree".

Licence
MIT
Last repository change
17.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Create, manage, scan, update, and clean up git worktrees for parallel development with protected branch safeguards. Use when working on multiple branches simultaneously, isolating experiments, updating protected branches (main/develop), cutting a gh-stack layer as a worktree (top or mid-stack insert), or when user mentions "worktree", "parallel branches", "feature isolation", "branch cleanup", "worktree status", "update main/develop", "stack layer worktree", or "stacked worktree".

Triggers from the description

worktreeparallel branchesfeature isolationbranch cleanupworktree statusupdate main/developstack layer worktreestacked worktree
Original author description

Create, manage, scan, update, and clean up git worktrees for parallel development with protected branch safeguards. Use when working on multiple branches simultaneously, isolating experiments, updating protected branches (main/develop), cutting a gh-stack layer as a worktree (top or mid-stack insert), or when user mentions "worktree", "parallel branches", "feature isolation", "branch cleanup", "worktree status", "update main/develop", "stack layer worktree", or "stacked worktree".

How it works

  1. Agent Delegation (Required)
  2. Stack Layers (gh-stack)
  3. Standards and Paths
  4. Protected Branch Configuration
  5. Safety and reminders
Original SKILL.md headings · 88 lines, 807 words
SKILL.md preview
---
name: sc-git-worktree
description:
  Create, manage, scan, update, and clean up git worktrees for parallel development with protected branch safeguards.
  Use when working on multiple branches simultaneously, isolating experiments, updating protected branches (main/develop),
  cutting a gh-stack layer as a worktree (top or mid-stack insert), or when user mentions "worktree", "parallel branches",
  "feature isolation", "branch cleanup", "worktree status", "update main/develop", "stack layer worktree", or "stacked worktree".
version: 0.14.0
entry_point: /sc-git-worktree
---

# Managing Git Worktrees

Use this skill to manage worktrees with a standard structure and tracking. Use the `/sc-git-worktree` command to invoke this skill.

## Agent Delegation (Required)

This skill delegates all execution to specialized agents via the **Task tool** (no manual git commands in the primary session).
Always pass inputs via `<input_json>` and render `<output_json>` from the subagent response.

**Task tool template:**

```xml
<invoke name="Task">
<parameter name="subagent_type">$SUBAGENT</parameter>
<parameter name="description">$DESCRIPTION</parameter>
<parameter name="prompt">Run $SUBAGENT with this input:

<input_json>
```json
$INPUT_JSON
```
</input_json>
</parameter>
</invoke>
```

| Operation | Agent | Returns |
|-----------|-------|---------|
| Create | `sc-worktree-create` | JSON: success, path, branch, tracking_entry |
| Create stack layer | `sc-worktree-create-stacked` | JSON: success, path, branch, stack, stack_handoff |
| Scan | `sc-worktree-scan` | JSON: success, worktrees list, recommendations |
| Cleanup | `sc-worktree-cleanup` | JSON: success, branch_deleted, tracking_update |
| Abort | `sc-worktree-abort` | JSON: success, worktree_removed, tracking_update |
| Update | `sc-worktree-update` | JSON: success, commits_pulled, conflicts (if any) |

To invoke an agent, use the Task tool with the agent prompt and pass parameters exactly as documented in the agent Inputs section.

**Routing rule:** a worktree that is a gh-stack layer (the user says "stack", "layer", "on top of <branch>", "insert under", or the branch will be linked with `gh stack`) goes to `sc-worktree-create-stacked`. Everything else goes to `sc-worktree-create`.

## Stack Layers (gh-stack)

A stack layer is a worktree whose branch will be a PR in a `gh stack`. The plain create is wrong for it: it branches from the **local** base ref (possibly stale or another writer's unpushed state) and, from a remote ref, would leave the parent as upstream. `sc-worktree-create-stacked` cuts from `origin/<parent>` with `--no-track`, refuses bad cuts before touching anything (parent not pushed, already landed, insert target not stacked on the parent), records the parent SHA in tracking, and returns a `stack_handoff` block.

- `stack_handoff.writer` goes verbatim to the agent that will work in the worktree (WIP commit, first push with `-u`, at most one rebase at task start, no edits to lower layers, no gh stack write commands). `stack_handoff.stack_writer` goes to the stack writer only (PR with base = parent, reuse sufficient complete composition/exact-head evidence, link on top, or the insert sequence: merge-forward by every layer above, unstack, `gh pr edit --base`, full relink). Explicit-number link/full link needs no per-worktree checkout; import local tracking only where a later operation requires it. Reconcile mutation responses and acquire only missing affected facts with a scoped view.
- Record the numeric stack number returned by link/relink. Only if complete composition/base evidence remains missing, use `/sc-gh-stack-view --stack <returned-stack#> --refresh`; selecting the new branch cannot discover it without a qualified local catalog that already records its number.
- Cleanup refuses to delete a branch that live layers sit on unless git shows a merge-commit landing in the trunk (`STACK.HAS_CHILDREN`; batch cleanup reports `stack_blocked`, and never sweeps a fresh layer with no commits). Abort always refuses. Both read the tracking file.
- Scan reports `stack_parent_advanced` (layer no longer contains the parent's head) and `stack_parent_landed` (PR should now target the trunk) on layer rows.

Details and the handoff contract: `references/stack-layers.md`. The stack model, recipes and the view tool live in the `sc-gh-stack` package (`/sc-gh-stack`, `/sc-gh-stack-view`); this skill only makes the worktree side of that model safe.

## Standards and Paths
- Repo root: current directory.
- Default worktree base: `../<repo-name>-worktrees` where `<repo-name>` is the basename of the repo root directory, derived at runtime via `basename $(git rev-parse --show-toplevel)` (e.g. repo `my-project` → `../my-project-worktrees`).
- Worktrees live in `<worktree_base>/<branch>`.
- Tracking file (if used): `<worktree_base>/worktree-tracking.jsonl` must be updated on create/scan/cleanup/abandon. Allow a toggle to disable tracking for repos that don't use it.
- Naming: worktree directory = branch name; branch naming follows repo policy.
- Branch protections/hooks: no direct commits to protected branches.

## Protected Branch Configuration

Protected branches (main, develop, master, etc.) require special handling to prevent accidental deletion:

```yaml
# .sc/shared-settings.yaml
git:
  protected_branches:
    - "main"
    - "develop"
    - "master"
```

**Protected Branch Rules:**
- Protected branches are read from `.sc/shared-settings.yaml` (`git.protected_branches`)
- If missing, protected branches are auto-detected from git-flow and cached to `.sc/shared-settings.yaml`
- **Cleanup/abort agents NEVER delete protected branches** (local or remote)
- Protected branches can only be removed from worktrees, never deleted
- Use `--update` to safely pull changes for protected branches in worktrees

## Safety and reminders
- **NEVER delete protected branches** (main, develop, master) under any circumstances.
- Protected branches can only be removed from worktrees; the branch itself must always be preserved.
- Never delete branches or force-remove worktrees without explicit approval.
- Never clean/abandon a worktree with uncommitted changes unless explicitly approved.
- Keep tracking JSONL in sync on every operation when enabled.
- Respect branch protections and hooks; no direct commits to protected branches.
- Use background agents for worktree operations; keep the main context focused on decisions and summaries.
Files in this package (3)
  • SKILL.md 6 KB
  • SKILL.md.local.j2 6 KB
  • references/stack-layers.md 7 KB

Versions

The database has no other skills named sc-git-worktree.

Database snapshot: 13.11.2026 · package version ecc417deeb9c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95sc-managing-worktrees
    Create, manage, scan, update, and clean up git worktrees for parallel development with protected branch safeguards. Use when working on multiple branches simultaneously, isolating experiments, updating protected branches (main/develop), or when user mentions "worktree",…
  • 100worktree-open
    Create or reopen a git worktree for parallel development. Use when user wants to "open a worktree", "spin up a branch", "work on X separately", "work on this in parallel", "start a parallel task", "isolated environment for an agent", "side branch without switching", or mentions…
  • 100using-git-worktrees
    Creates and removes isolated git worktrees for parallel development. Use when starting feature work needing isolation, working on multiple branches simultaneously, or removing one specific worktree and its branch after its PR merges. NOT for simple branch switching, sweeping…
  • 95dev_manage_git-worktrees
    Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification. Triggers: worktree, git worktree, isolated workspace, feature branch…
  • 90git-worktree-manager
    Manage parallel development with Git worktrees: creation with port allocation, environment sync, branch isolation, and cleanup. Use when working multiple branches at once, running parallel CI validations, or isolating agent workspaces.
  • 100worktree
    Creates git worktrees for isolated development. Use when user wants to "create a worktree", "start a new feature branch", "work on a fix in isolation", or needs a parallel development environment.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.