AGENT SKILL

starting-work

Sync local main, then create a properly named branch (or worktree) to start new work. Use when starting new work, asked to "start a new branch", "create a branch for X", "sync main and branch off", or "set up a worktree for this feature" — before any commits happen. Validates the branch name against git-kit's [type]/[description] convention and offers a worktree as an alternative to a plain branch checkout.

License 许可
Apache-2.0
最近更新
2026-11-15
Stars
★ 0
Forks
0

01 前言 Front Matter

name
starting-work
description
Sync local main, then create a properly named branch (or worktree) to start new work. Use when starting new work, asked to "start a new branch", "create a branch for X", "sync main and branch off", or "set up a worktree for this feature" — before any commits happen. Validates the branch name against git-kit's [type]/[description] convention and offers a worktree as an alternative to a plain branch checkout.
allowed-tools
Bash(git fetch:*), Bash(git checkout:*), Bash(git pull:*), Bash(git status:*), Bash(git branch --show-current:*), Bash(git symbolic-ref refs/remotes/origin/HEAD:*), Bash(git worktree add:*), Bash(git worktree lock:*), Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/git-write-marker.sh:*), Read, Glob, Write, AskUserQuestion
argument-hint
(optional) branch type and description, e.g. "feature add-user-auth"

02 资源文件 2

03 SKILL.md 正文

Starting Work

Get from "I'm about to start something new" to a properly named, up-to-date branch (or worktree) in one gated flow — instead of manually remembering to sync main, checking the naming convention, and deciding whether a worktree makes sense, separately, every time.

When to Use

Before writing any code for a new piece of work: syncing local main and creating the branch (or worktree) it'll happen on. Triggers: "start a new branch", "create a branch for X", "sync main and branch off", "set up a worktree for this feature".

When NOT to Use

  • Rebasing an already-existing feature branch onto a newer main — that's /git-sync-branch, not this skill. starting-work only runs before a branch exists.
  • Renaming an existing branch based on what it now contains — that's /git-update-branch-name.
  • Anything after the first commit — once work has started, this skill has nothing left to do.

Instructions

  1. Note the starting point and sync: git branch --show-current (for the report). git fetch origin --prune. Resolve the actual default branch — git symbolic-ref refs/remotes/origin/HEAD (falling back to main if that fails, e.g. no origin remote configured) — the same resolution finishing-work uses, so the two halves of the branch lifecycle agree on what "main" means in a repo that defaults to something else. Note: because the resolved branch name is dynamic, allowed-tools grants Bash(git checkout:*) broadly rather than pinned to a literal branch name — this also covers step 4's git checkout -b, so no separate grant is needed there. This skill never runs the file-restore form (git checkout -- <path>); only branch checkout and -b are ever invoked. If not already on the resolved default branch, ask via AskUserQuestion — "Base the new branch off <resolved-branch>, or off the current branch (<name>)?" — default the resolved branch. If basing off it: git checkout <resolved-branch>, then git pull --ff-only. If that fails (diverged local branch, or it's already checked out in another worktree), tell the user exactly why and stop rather than force anything. If basing off the current branch, skip the checkout/pull — see references/worktree-decision.md for why this branch-off-a-branch case is legitimate (e.g. stacking related work). Verify git status --porcelain is clean before proceeding; if not, tell the user to commit or stash first (point at the commit skill) and stop here.
  2. Resolve the branch name: use $ARGUMENTS if it supplies a type and description; otherwise ask via AskUserQuestion for both, one at a time. Validate:
    • Type: a single lowercase word, no slashes or spaces.
    • Description: kebab-case — lowercase letters, digits, and hyphens only; no leading/trailing/double hyphen. Don't hardcode or restate the accepted type list here — commit's own "Branch Naming Convention" section is the single source of truth for that. If the user is unsure what type to use, point them there instead of guessing or duplicating the list. If either value fails validation, tell the user why and ask again via AskUserQuestion — never pass an invalid type or description forward to step 4, the same "stop and explain" discipline step 1 already applies to a diverged main.
  3. Ask worktree or plain branch: read use_worktree (default true) the same way commit reads its own settings — .claude/git-kit.local.json if it exists and sets the field, else the git-tracked ${CLAUDE_PLUGIN_ROOT}/git-kit.settings.json default. This field doesn't need the trust-boundary check commit's commit_confirm_before_commit/commit_auto_stage require — it never skips the question below or triggers any automation on its own, it only changes which option is pre-highlighted, so honor it from either file, tracked or not. Then always ask via AskUserQuestion — "Create a plain branch, or a separate worktree for this?" — options "Plain branch" and "Worktree", with whichever use_worktree favors listed first and suffixed (Recommended): "Worktree (Recommended)" when true (the default, chosen with multiple agents — e.g. Codex CLI alongside Claude Code — potentially working in this same repo, where a separate working directory per piece of work avoids one agent's uncommitted state colliding with another's), "Plain branch (Recommended)" when false. The setting never replaces this ask — a human always makes the actual choice. See references/worktree-decision.md for the tradeoffs to mention if the user wants guidance rather than a snap decision.
  4. Create: immediately before either branch-creating command below, run bash "${CLAUDE_PLUGIN_ROOT}/scripts/git-write-marker.sh" git-branch-create starting-work — this writes the marker git-kit's branch-creation guard requires; it must be written right before the command runs, not earlier, since the hook only accepts a marker up to 60 seconds old.
    • Plain branch: git checkout -b <type>/<description>.
    • Worktree: compute a default path at .claude/worktrees/<description> (this skill only ever runs under Claude Code; the equivalent path for a Codex CLI session would be .codex/worktrees/<description> — both are gitignored). This is starting-work's own default for a session-lifecycle-managed worktree — distinct from git-worktrees' sibling-directory convention (../project-feature), which stays the right default for manual, ad-hoc worktree management outside this automated flow; see that skill's own note on the two use cases. Confirm the computed path with its own AskUserQuestion — "Create the worktree at <path>?" — options "Use this path" / "Enter a different path". Don't rely on step 3's worktree-vs-branch question to also cover the path (its own options only ever say "Plain branch" / "Worktree" — never fold the computed path into that option's description text as a substitute for asking here). If the user supplies an override, constrain it: letters, digits, hyphens, underscores, forward slashes, and periods only (no shell metacharacters), it must not contain a .. path segment, and it must resolve to a location either (a) inside this repo under .claude/worktrees/ or .codex/worktrees/, or (b) alongside/below the repo's parent directory (the old sibling convention, still supported as an explicit override) — not step 2's kebab-case rule, which is stricter than a filesystem path needs to be. If the override doesn't meet this, tell the user why and ask again rather than passing it through. Then git worktree add -b <type>/<description> <path>, followed immediately by git worktree lock <path> --reason "claude session" so the worktree can't be removed by git worktree remove (without --force) until it's explicitly unlocked — git-cleanup knows to unlock a session-locked worktree before removing it once its branch is safe to delete. Then copy over local, gitignored config git worktree add doesn't carry (it only shares tracked history, not untracked files): Glob the main worktree root for .claude/*.local.json (top-level only, not recursive) and copy each match found into the same relative path in the new worktree, only if the destination doesn't already exist there (never clobber). This covers .claude/settings.local.json plus every other per-plugin .claude/<name>.local.json override this repo's local-config precedent (.claude/rules/ask-before-config-decisions.md) produces — e.g. git-kit.local.json, analysis-kit.local.json, plugin-auditor.local.json, codex-windows-guardrails.local.json — generically, rather than a hardcoded list that needs a follow-up fix every time a new plugin adopts the same precedent. Also Glob the main worktree for **/CLAUDE.local.md and copy each match found into the same relative path in the new worktree, same no-clobber rule — but first drop any match under a vendored/third-party tree (node_modules/, .venv/), this repo's own .temp/ directory, or another worktree's own directory (.claude/worktrees/*/, .codex/worktrees/*/) — this last exclusion matters because this same skill's own default worktree path lives under one of those trees, so without it a CLAUDE.local.md belonging to a different, unrelated worktree could be swept in and copied into the new one. Since a bare **/CLAUDE.local.md pattern would otherwise sweep all of these, and Glob itself has no exclude syntax, filter the match list before copying rather than trying to encode the exclusion into the pattern.
  5. Report: the branch (or worktree path) just created, current location, and — for a worktree — that cd-ing into the worktree path is needed before working there, and that it's now locked to this session: when the work here is done, finishing-work//git-cleanup handles unlocking and removal — don't git worktree remove --force it directly, since that bypasses the lock as a safety signal that this worktree is still in active use. Mention git-worktrees has further operations (compare, merge, cleanup) if multiple worktrees end up in play.

Worktree Topic Scope

A worktree this skill creates is scoped to one topic. If a session's already-bound worktree was created for a different piece of work, don't start unrelated work in it — run this skill again for the new topic, which creates its own worktree. Symmetrically, don't keep working across worktrees for unrelated topics in the same session: finish the current topic (finishing-work / /git-cleanup) before starting the next one, rather than leaving multiple topics open at once.

This is a convention for how these worktrees get used, not a mechanical lock — nothing enforces "topic" the way a file lock enforces exclusive access, since there's no way to check whether two pieces of work are actually the same topic from git state alone.

Why it matters: a worktree that accumulates unrelated work becomes hard for git-cleanup to reason about — it can't tell whether all the work in it is done, just the piece currently top of mind, so a mixed-topic worktree is more likely to get force-deleted along with unrelated in-progress changes by mistake. One worktree per topic keeps git-cleanup's merged/unmerged/dirty analysis meaningful: "this worktree's branch merged" reliably means "this worktree is done."

The session-level half — don't leave one topic's worktree open while starting a second, unrelated one — matters because the Stop exit-guard (git-guard-dirty-worktree-exit.sh) only checks the worktree the session's current working directory is actually in when the turn ends, not every worktree the session has ever locked. Moving into a second worktree before finishing the first leaves the first one's dirty/unmerged state unchecked at Stop time, even though it's still locked and still at risk.

Testing & Validation

Verify this skill activates on:

  • "start a new branch for the auth refactor"
  • "create a branch for X" / "sync main and branch off"
  • "set up a worktree for this feature"

Verify it does NOT activate on:

  • "sync my current branch with main" → /git-sync-branch
  • "rename this branch to match what it does now" → /git-update-branch-name
  • "I just merged, clean this up" → finishing-work

Verify use_worktree behavior:

  • use_worktree: true (the default) — confirm step 3's AskUserQuestion still fires every time, with "Worktree (Recommended)" listed first
  • use_worktree: false — confirm the same question fires, with "Plain branch (Recommended)" listed first instead
  • Either value — confirm the setting never skips the question outright; the user's actual answer at step 3 always decides, regardless of which option was pre-highlighted

Verify the worktree-path confirmation:

  • Worktree chosen at step 3, default path accepted at step 4's own AskUserQuestion — confirm git worktree add runs with the computed default path
  • Worktree chosen at step 3, path overridden at step 4 — confirm the override goes through the existing character-class/..-segment/location validation before being passed to git worktree add
  • Confirm the computed path is never mentioned inside step 3's own option description text as a substitute for step 4's own question — step 3 asks whether, step 4 asks where

Verify the local-config copy behavior (issue #113):

  • Main worktree root has .claude/settings.local.json plus one or more other .claude/<name>.local.json files (e.g. .claude/git-kit.local.json) — confirm every one of them is copied into the new worktree, not just settings.local.json
  • A destination .claude/<name>.local.json already exists in the new worktree — confirm it's never clobbered
  • .claude/*.local.json glob stays top-level only — confirm a .local.json file nested deeper than .claude/ (not a realistic case today, but the pattern shouldn't accidentally reach one) is not swept

Verify the CLAUDE.local.md exclusion behavior:

  • An unrelated, already-existing worktree (e.g. .claude/worktrees/other-topic/) has its own CLAUDE.local.md — confirm creating a new worktree never copies that file in; the sweep must drop .claude/worktrees/*/ and .codex/worktrees/*/ matches the same way it already drops node_modules//.venv//.temp/
  • A CLAUDE.local.md genuinely at or below the main worktree root (not inside another worktree) is still copied normally

Verified live, 2026-08-28: ran find .claude -maxdepth 1 -name "*.local.json" against this repo's real main checkout — matched exactly .claude/settings.local.json and .claude/codex-windows-guardrails.local.json (the same file issue #113's own reproduction steps cite), confirming a .claude/*.local.json glob reaches every real per-plugin local override this repo currently has, not just settings.local.json. No fresh skill-tester eval re-run for this edit — the fix is a mechanical glob-pattern generalization of already-eval-covered copy logic (evals/starting-work/evals.json), verified directly against real repo files rather than re-run end-to-end.

Quality gates:

  • [ ] Step 1 never fast-forwards a diverged local main silently — always stops and tells the user
  • [ ] Step 2 never hardcodes the branch-type list — always points at commit's own convention section
  • [ ] Step 2 never passes an invalid type/description forward — always re-asks on validation failure
  • [ ] Step 3's worktree-vs-branch question always uses AskUserQuestion, never assumed — use_worktree only changes which option is recommended, it never skips the question
  • [ ] Step 4 never passes an unconstrained worktree-path override to git worktree add — always validates the character class and rejects any .. path segment
  • [ ] Step 4 always fires its own AskUserQuestion for the worktree path before git worktree add runs — a path mentioned only inside step 3's option description never satisfies this
  • [ ] Step 4's default worktree path is always .claude/worktrees/<description> (or .codex/worktrees/ for a Codex CLI session) — never the old sibling-directory convention, unless the user explicitly overrides to one
  • [ ] Every worktree Step 4 creates is locked (git worktree lock) immediately after git worktree add — never left unlocked
  • [ ] Step 4's local-config copy always globs .claude/*.local.json (every per-plugin override), never just .claude/settings.local.json alone
  • [ ] Step 4's CLAUDE.local.md sweep always drops matches under another worktree's own directory (.claude/worktrees/*/, .codex/worktrees/*/), never just node_modules//.venv//.temp/
  • [ ] Step 5's report always mentions the worktree is session-locked and points at finishing-work//git-cleanup for removal — never suggests git worktree remove --force directly
  • [ ] Step 4 always writes the git-branch-create marker immediately before git checkout -b / git worktree add -b, never earlier in the run
  • [ ] A dirty working tree at step 1 always stops the flow with a pointer to commit, never proceeds

Reference Guide

Resource Purpose
references/worktree-decision.md Worktree-vs-plain-branch tradeoffs, and the branch-off-a-branch escape hatch for stacking work on top of an open PR

04 同仓库更多 Skills

AndreHahm
AndreHahm/andres-cc-marketplace

demo

Fixture skill used by scripts.marketplace_ci sync tests.

★ 0
AndreHahm
AndreHahm/andres-cc-marketplace

export-demo

Fixture skill used by scripts.marketplace_ci export tests.

★ 0
AndreHahm
AndreHahm/andres-cc-marketplace

work-to-development

Validate an accepted Linear Issue's readiness for implementation (criteria, dependencies, duplicate/existing artifacts) and request governed branch/worktree creation through git-kit:starting-work — recording work-started Git/GitHub evidence and a deliberate Linear Started transition only after Git identity is read back and verified. Use when asked to start work on a Linear issue, begin development for an accepted issue, or prepare an accepted issue for implementation. Never creates a branch directly — always delegates to git-kit.

★ 0
AndreHahm
AndreHahm/andres-cc-marketplace

work-linking

Create and maintain stable cross-system links and authority labels between Notion and Linear records, and detect/repair drift between them. Use when asked to link a Notion record to a Linear record, check for drift between Notion and Linear, or repair a broken/stale link. Repairs only the bounded non-authoritative copy or link — never chooses by newest timestamp, and never creates a reverse-write loop against either system's own authority.

★ 0
AndreHahm
AndreHahm/andres-cc-marketplace

status-and-learning

Produce a dated, explicitly non-live Linear-to-Notion progress summary, or capture an outcome/learning after work completes. Use when asked to summarize progress to Notion, report portfolio status, or capture what was learned from a completed piece of work — not to disposition open follow-up items (see open-item-management for that). Never runs automatically or continuously — every summary is a deliberate, approved snapshot, not a live sync.

★ 0
AndreHahm
AndreHahm/andres-cc-marketplace

repository-gates

Discover, delegate, record, and invalidate this repository's actual Git/GitHub lifecycle gates (pre-commit, pre-push, PR required checks, Codex delta review, review requirements, merge rights) and the repository-policy provider profile that maps governed operations to git-kit. Use when asked what gates apply to this repository, to discover repository policy before starting Wave 2 work, or to check whether prior gate evidence is still valid after new commits. Discovery and delegation only — never executes a gate's own internal logic, and never invents a gate the repository doesn't actually define (in particular, never assumes a "Review Changes" gate exists).

★ 0