setup-repo
Configure this repo for the skills: issue tracker, triage and risk labels, domain docs, design system file, coding standards, commit and PR formats, pre-commit tooling, and the unattended-run wake mechanism. Run once before first use of the other skills.
- License 许可
- MIT
- 最近更新
- 2026-11-05
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- setup-repo
- description
- Configure this repo for the skills: issue tracker, triage and risk labels, domain docs, design system file, coding standards, commit and PR formats, pre-commit tooling, and the unattended-run wake mechanism. Run once before first use of the other skills.
- disable-model-invocation
- true
02 资源文件 23
- 参考文档agents/openai.yaml138 B
- 参考文档CREDITS.md482 B
- 参考文档docs-layout.md2.9 KB
- 参考文档domain.md2.0 KB
- 参考文档harness.md656 B
- 参考文档issue-tracker-github.md3.7 KB
- 参考文档issue-tracker-gitlab.md3.7 KB
- 参考文档issue-tracker-local.md1.8 KB
- 参考文档landing-policy.md1.3 KB
- 参考文档migration-landing.md1.1 KB
- 参考文档models.md4.5 KB
- 参考文档repo-mode.md443 B
- 脚本scripts/install-timers7.8 KB
- 脚本scripts/test-install-timers.sh5.3 KB
- 其他systemd/runner-fix-ci.service378 B
- 其他systemd/runner-fix-ci.timer324 B
- 其他systemd/runner-run.service376 B
- 其他systemd/runner-run.timer299 B
- 其他systemd/runner-triage.service387 B
- 其他systemd/runner-triage.timer320 B
- 参考文档triage-labels.md1.6 KB
- 参考文档unattended.md2.3 KB
- 参考文档verifier.md580 B
03 SKILL.md 正文
Setup Meta
Scaffold the per-repo configuration that the skills assume:
- Issue tracker: where issues live (GitHub by default; local markdown is also supported out of the box)
- Triage labels: the strings used for the five canonical triage roles
- Domain docs: where
GLOSSARY.mdand ADRs live, and the consumer rules for reading them - Models (optional): which model each subagent role uses, for skills that spawn subagents
This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
Solo fast-path
When the user wants solo (answers solo at Section H first, or says ship now or solo), skip the interview and apply these defaults: mode: solo, tiered auto-land for low-risk per docs/agents/unattended.md, local verifier offer via the Skill tool with "verify-new" (Section I), skip team repo-settings (Section K), skip unattended timers unless asked (Section G), models section optional and skip-friendly (Section F). Walk Sections A through E with defaults and one-word confirms only. Team or custom setups still walk every section.
1. Explore
Look at the current repo to understand its starting state. Read whatever exists; don't assume:
git remote -vand.git/config: is this a GitHub repo? Which one?AGENTS.mdat the repo root: does it exist? Is there already an## Agent skillssection in it?GLOSSARY.mdandGLOSSARY-MAP.mdat the repo root (legacy namesCONTEXT.md/CONTEXT-MAP.mdmean the same files)docs/adr/and anysrc/*/docs/adr/directoriesdocs/agents/: does this skill's prior output already exist?.scratch/: a sign that a local-markdown issue tracker convention is already in use- Is the
ship-triageskill installed? (aship-triageskill folder alongside this one, orship-triagein your available skills.) This decides whether Section B runs at all. - Monorepo signals: a
pnpm-workspace.yaml, aworkspacesfield inpackage.json, or a populatedpackages/*with its ownsrc/. These are present only in a genuinely large multi-package repo; their absence means single-context, which is almost every repo. - Unattended wake options: what this harness offers for runs without the user watching (a loop or wait command, a watch on CI or refs, an outside scheduler). This decides Section G.
- Repo settings for team landing:
allow_auto_merge,delete_branch_on_merge, branch protection, required checks (Section K; team only, solo skips as N/A).
2. Present findings and ask
Summarise what's present and what's missing. Then take the sections in order. One section, one answer, then the next.
Lead each section with the recommended answer so the user can accept it in a word. Give a one-line explainer only when the choice genuinely branches; skip the section entirely when exploration already settled it (Section B when ship-triage isn't installed, Section C when there's no monorepo).
Section A: Issue tracker.
Explainer: The "issue tracker" is where issues live for this repo. Skills like
plan-tickets,ship-triage, andplan-specread from and write to it. They need to know whether to callgh issue create, write a markdown file under.scratch/, or follow some other workflow you describe. Pick the place you actually track work for this repo.
Default posture: these skills were designed for GitHub. If a git remote points at GitHub, propose that. If a git remote points at GitLab (gitlab.com or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:
- GitHub: issues live in the repo's GitHub Issues (uses the
ghCLI) - GitLab: issues live in the repo's GitLab Issues (uses the
glabCLI) - Local markdown: issues live as files under
.scratch/<feature>/in this repo (good for solo projects or repos without a remote) - Other (Jira, Linear, etc.): ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose
Record the choice in docs/agents/issue-tracker.md. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted off. Leave it off and don't raise it: a user who wants external PRs in the ship-triage queue can flip the flag in the file later.
Section B: Triage label vocabulary. Skip this section entirely if the ship-triage skill isn't installed (exploration told you), since an uninstalled skill needs no labels.
If it is installed, ask exactly one question:
Do you want to keep the default triage labels? (recommended: yes)
The defaults are the five canonical roles, each label string equal to its name: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix. Plus three risk rows for agent PRs: risk-low, risk-medium, risk-high (mapped to risk:low, risk:medium, risk:high unless the tracker names them otherwise). On yes, write them as-is and create feature-request and deprecation labels idempotently with the label-create command from docs/agents/issue-tracker.md (gh label create --force on GitHub) alongside the vocab so issue templates resolve. Only if the user says no, usually because their tracker already uses other names (e.g. bug:triage for needs-triage), collect the overrides so ship-triage applies existing labels instead of creating duplicates.
Section C: Domain docs. Default to single-context (one GLOSSARY.md + docs/adr/ at the repo root). This fits almost every repo; write it without asking.
Offer multi-context (a root GLOSSARY-MAP.md pointing to per-context GLOSSARY.md files) only when exploration found monorepo signals. Then confirm which layout they want. A repo that already carries CONTEXT.md / CONTEXT-MAP.md keeps those names (legacy); do not create GLOSSARY.md beside them.
Section D: Meta docs. Ask which repo-level meta docs to scaffold. Default posture is all yes; skip any the repo genuinely does not need (a repo with no UI skips DESIGN.md).
DESIGN.md(Stitch format): machine-readable design tokens as YAML frontmatter (colors,typography,rounded,spacing,components) plus human-readable rationale in##sections in canonical order (Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts). Full format reference: https://github.com/google-labs-code/design.md. Scaffold tokens from the existing UI (or the user's brand notes), then validate withnpx @google/design.md lint DESIGN.mdand fix errors before writing.- Coding standards file: one file, agreed name. Default
CODING_STANDARDS.md; acceptCONTRIBUTION.mdorGUIDELINES.mdwhen the repo already leans that way. Draft it from the codebase (naming, module shape, test seams, what review checks) plus the user's stated rules. - Commit message format: agree one format (default: conventional commits) and record it in the standards file.
- PR body format: no new file. Confirm the repo uses the
ship-prskill shape (Summary visual, before/after Evidence, Merge Danger).
Section E: Tooling. Local gates in four layers, no mandatory CI template (the verifier in docs/agents/verifier.md decides; Section I wires it): call the Skill tool with "setup-hooks" for JS/TS repos (fast pre-commit gate under 3 seconds: format, token gate, staged-file checks; commit-msg enforces Conventional Commits; typecheck and full tests move to pre-push plus the configured verifier). Hook install and the --no-verify ban are enforced by script, not prose: skills/user-invoked/whips/scripts/ensure-worktree-hooks copies the pre-push verifier into a worktree and exits nonzero while the hook is still absent (worktree setup is incomplete without it), and skills/user-invoked/whips/scripts/no-verify-guard refuses any push argv carrying --no-verify plus any push from a worktree whose hook is missing. For non-JS repos, install shell hooks under .githooks/ and point git at them with git config core.hooksPath .githooks (no new runtime, no new dependencies without confirmation): use only preset commands whose tools already exist in the repo. Dart: dart format --set-exit-if-changed . in pre-commit, dart analyze and dart test in pre-push. PHP/Laravel: ./vendor/bin/pint --test (or pint --test when on PATH) in pre-commit, phpstan only when configured, php artisan test in pre-push. Python: project tools only when pyproject.toml declares them (format check in pre-commit, test command in pre-push). The commit-msg hook reuses the Conventional Commits shell from setup-hooks (merge and revert messages exempt). Record one line in docs/agents/ naming the four layers and banning --no-verify for bypassing gates.
Section F: Models (optional). Skip unless whips is installed. Solo fast-path: offer once and move on at the first no; team still walks all six steps. Run six steps, one question per step, and never name a model id the user has not confirmed. Never hardcode a harness or model id into the skill; copy only what detection found. Answering inherit-everywhere at step 1 ends the section with nothing written.
- Detect. Read the harness config and environment for model ids already available: config files, CLI
--helpor model list output, provider env var names without their values.inheritis always valid. Show what you found, nothing more.
Which of these detected ids should roles use, or should every role inherit?
- Budget. Solo fast-path default is
small; team picks per workload. Offer four familiar levels plusn/a:unlimited(max),large(xhigh),medium(high),small(medium). Write the pick as a# budget:line indocs/agents/models.md. A harness that names no effort levels getsn/a, and every role runs at its plain model.
Which budget fits the hardest work in this repo: unlimited, large, medium, small, or n/a?
- Map. One model for every role is fine; effort carries the difference. Put the confirmed id (or
inherit) on each row in models.md:code,hard-code,judgment,review,craft-how-explorer,craft-how-explainer,craft-why-investigator,craft-why-synthesizer,craft-swarm-worker,craft-arena-runner,craft-architect-runner,review-adversary-reviewer,learn-reflect-reviewer,learn-reflect-synthesizer.hard-codesits one step abovecode;craft-swarm-workerfollowsreview.
Same model everywhere, or a different id for any role?
- Validate. Check every id against what detection found (
inheritalways passes), and checkreviewis never effort-shifted belowcodeper whips SKILL.md section 6 (shift effort one step up for the hardest work, never down for review). Fix mismatches with the user before writing. - Write. Rewrite
docs/agents/models.mdfrom models.md in full on every run: no duplicated rows, retired roles deleted. Location is per repo (docs/agents/models.md); use the personal fallback only when the user explicitly asks for one config across repos, and record why. - Confirm. Show the written file and ask for corrections before moving on. Do not raise
/verify-newhere; the scaffold layout step owns that offer.
Section G: Unattended runs (opt-in). The skill never installs a harness by default; this section runs only when the user asks for unattended wake; otherwise write Wake: none in docs/agents/unattended.md and move on.
When asked, work in this order. Detect first: list the opaque probe binaries the user named (RUNNER_AGENT_PROBES, shown by runner.sh detect), then read <cmd> --help for the non-interactive flag, the session timeout, the structured output mode, and the approval flags. Copy only flags the help text documents; never guess them. When no probe answers, ask the user to type the full non-interactive command (it sees $RUNNER_MODEL, $RUNNER_PROMPT, $RUNNER_PROMPT_FILE) instead of installing or requiring any named harness.
Configure the runner with runner.sh setup --agent-cmd ... --model ... --repos ... (model choice comes from Section F). Setup writes the shared record to docs/agents/harness.md from harness.md and keeps the host config as a thin override. Preview timers with install-timers --dry-run: it prints the four units rendered from the systemd/ templates plus every command, and writes nothing. The templates use Type=oneshot, EnvironmentFile, an explicit Environment=PATH=, TimeoutStartSec from RUNNER_TIMEOUT_MIN, and timers use Persistent=true, OnBootSec, OnUnitActiveSec, RandomizedDelaySec.
Verify before enabling: systemd-analyze --user verify on each unit, one manual systemctl --user start probe, then read journalctl --user -u .... Enable only after the user says yes (--yes); print loginctl enable-linger $USER as a step the user runs themselves when timers must survive logout. Re-runs are idempotent: an installed unit is a no-op. The kill switch is runner.sh pause (until runner.sh resume) plus install-timers uninstall, which removes only units carrying its managed marker. Without systemd, print the one-line cron-line fallback instead. macOS needs brew util-linux plus coreutils for flock and timeout, and wakes via launchd or cron per the ship-runner CONTRACT non-systemd section.
Record the wake choice, run log convention (.scratch/whips/<run>/log.md, one row per iteration), and budget habit (predicate first, stated iteration, hour, or PR cap) in docs/agents/unattended.md. Point at /ship-runner for issue-queue runs; the skill reads this file.
Section H: Repo mode (solo or team). Ask one question:
Is this a solo repo (you plus agents) or a team repo? (no default; skill behavior branches on it)
Write the answer to docs/agents/repo-mode.md from repo-mode.md: mode: solo|team. Behavior differs: solo merges after the local verifier passes without waiting on GitHub checks; team waits on CI like pstack. Playbooks read this file; a missing file means stop and tell the user to run /setup-repo.
Section I: Verifier (solo) / CI (team). First ask once (only when no skills/verify-* exists yet): run /verify-new now or later; never auto-generate without an answer. On later, still write docs/agents/verifier.md from verifier.md with the command line set to pending: run /verify-new, so the next whips run sees the gap and waits per its verify rule. Solo: generate or wire the per-project verifier via the Skill tool with "verify-new", write its command to docs/agents/verifier.md from verifier.md (PASS = exit 0), install a pre-push hook that runs that command and refuses the push on nonzero exit, and copy the hook into every new worktree at creation time with skills/user-invoked/whips/scripts/ensure-worktree-hooks --worktree <path> (it exits nonzero while the hook is still absent; worktree setup is incomplete without it). Team: skip this section and point at CI running the same command plus a PR-title check. Never force Actions onto this repo. Agents never run git push --no-verify: opening-a-pr and shipping run skills/user-invoked/whips/scripts/no-verify-guard before every push, which refuses --no-verify argv and any push from a hookless worktree.
Section J: Docs layout. After Sections A through I, scaffold the canonical docs layout, idempotently. Dirs (create with .gitkeep where empty): docs/adr/, docs/research/, docs/agents/, .scratch/whips/, .audit/. .gitignore append (skip lines already present; re-run adds nothing): .scratch/, .audit/, decisions.tsv, **/decisions.tsv; never ignore docs/ or skills/verify-*/. Write docs/agents/docs-layout.md from docs-layout.md and add a ### Docs layout line to the ## Agent skills block pointing at it. Content stays lazy: ADR bodies, GLOSSARY.md, skills/verify-*/, workflows/*.md are not scaffolded, only their parent dirs with .gitkeep.
Then ask two more, one at a time. Autonomy tier for this repo (the whips mode): strict HIT with every landing human-approved, or tiered auto-land with low-risk PASS PRs merging untouched (recommended: tiered, human time reserved for high-risk). Record it in docs/agents/unattended.md; it overrides the default where the repo chooses strictness. Scheduled maintenance: which jobs run on a schedule and how they wake (cron line, systemd timer, or the harness non-interactive/headless mode invoking a skill). Default proposal: a stale-docs sweep via /learn-reflect plus /verify-upkeep upkeep daily via scheduled automation, proposals filed, never auto-applied. Record each job's command, cadence, and output sink in the same file.
Section K: Repo settings (team only, solo skips). Skip entirely when Section H answered solo: say "Repo settings are N/A in solo mode, the local verifier decides landing" and move on. For team repos, ask one question:
May I check the forge settings this repo needs for landing, and apply what is missing? (recommended: yes to check, apply only after you confirm each change)
Run skills/user-invoked/whips/scripts/repo-settings check --landing <auto-merge|direct> (read-only, ask-first; never apply without the user confirming each change). The Landing value comes from docs/agents/unattended.md: auto-merge arms gh pr merge --auto --squash on open and lands when required checks pass; direct merges with gh pr merge --squash after CI is green and a read-back shows state: MERGED. Check outcome decides landing downstream: team plus Landing: auto-merge must pass the check before any arm or merge; the fail-closed gates live in skills/user-invoked/whips/playbooks/shipping.md (step 1) and skills/user-invoked/whips/playbooks/ready-check.md (step 5). Refuse auto-merge when required checks are empty: write the needs-human marker <!-- needs-human reason=no-required-checks --> and tell the user to enable branch protection first. On user yes, run repo-settings apply --dry-run first, show the exact calls, then apply --yes only after the user confirms. Without admin rights the script prints UI steps instead of changing anything; never work around that. Record the outcome in docs/agents/unattended.md (Landing: line plus the check result) and in the ### Landing sub-block of the ## Agent skills block. Re-run is a no-op when settings already match.
3. Confirm and edit
Show the user a draft of:
- The
## Agent skillsblock to add to the repo'sAGENTS.md - The contents of
docs/agents/issue-tracker.md,docs/agents/domain.md,docs/agents/triage-labels.md(the last only whenship-triageis installed),docs/agents/unattended.md,docs/agents/repo-mode.md, anddocs/agents/verifier.md(the last only for solo repos) - The contents of
docs/agents/models.md, only when Section F ran with yes - The
repo-settings checkoutput, only for team repos (Section K)
Let them edit before writing.
4. Write
Edit the repo's AGENTS.md, creating it if it does not exist.
If an ## Agent skills block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections. On re-run, detect legacy landing text ("Open PRs as drafts", "never merge a risk:high", "agents must never merge"): show it to the user and offer the replacement; never silently overwrite.
The block:
## Agent skills
### Issue tracker
[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`.
### Triage labels
[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.
### Domain docs
[one-line summary of layout: "single-context" or "multi-context"]. See `docs/agents/domain.md`.
### Models
[one line: which roles are pinned]. See `docs/agents/models.md`.
### Unattended runs
[one line: the wake mechanism]. See `docs/agents/unattended.md`.
### Repo mode
[one line: solo or team]. See `docs/agents/repo-mode.md`.
### Verifier
[one line: the verify command]. See `docs/agents/verifier.md` (solo repos).
### Docs layout
One door into where skills write and read. See `docs/agents/docs-layout.md`.
### Landing
[one line: solo verifier or team checks plus the repo-settings outcome (Section K)]. See `docs/agents/landing-policy.md`.
### Meta docs
[one-line summary of what was scaffolded: DESIGN.md, standards file name, commit format]. PR body needs no line: the `ship-pr` skill is the format.
Include the ### Triage labels sub-block, and write docs/agents/triage-labels.md, only when ship-triage is installed and Section B ran. When it isn't, both are omitted. Include the ### Models sub-block, and write docs/agents/models.md, only when Section F ran with yes. Include the ### Verifier sub-block, and write docs/agents/verifier.md, only for solo repos. Always include the ### Unattended runs, ### Repo mode, ### Docs layout, and ### Landing sub-blocks, and always write docs/agents/unattended.md, docs/agents/repo-mode.md, docs/agents/docs-layout.md, and docs/agents/landing-policy.md.
Then write the docs files using the seed templates in this skill folder as a starting point:
- repo-mode.md: solo or team (Section H, always)
- verifier.md: verify command (Section I, solo only)
- docs-layout.md: map of where skills write and read (Section J, always)
- landing-policy.md: landing rules reading repo-mode plus verifier (always)
- issue-tracker-gitlab.md: GitLab issue tracker
- issue-tracker-local.md: local-markdown issue tracker
- triage-labels.md: label mapping (only if
ship-triageis installed) - domain.md: domain doc consumer rules + layout
- models.md: model per subagent role (only if Section F ran with yes)
- unattended.md: wake mechanism, run log convention, budget habit
Then write the repo-level meta docs agreed in Section D, at the repo root:
DESIGN.md: tokens frontmatter plus rationale sections in canonical order. Lint it withnpx @google/design.md lint DESIGN.mdand fix errors before finishing.- The coding standards file under its agreed name: naming, module shape, test seams, review checks, commit message format.
Then scaffold the Section J docs layout (dirs with .gitkeep, .gitignore append, docs-layout.md, AGENTS pointer) and run Section I (solo verifier + pre-push + worktree hooks) or skip it for team repos.
Then run Section E: call the Skill tool with "setup-hooks" for JS/TS repos, or install the .githooks/ shell presets for non-JS repos.
For "other" issue trackers, write docs/agents/issue-tracker.md from scratch using the user's description.
5. Done
Tell the user the setup is complete: which skills will now read from these files, which meta docs were scaffolded (DESIGN.md, standards file, commit format), whether pre-commit tooling was installed, and which wake mechanism unattended runs use. Mention they can edit docs/agents/*.md and the meta docs directly later; re-running this skill is only necessary if they want to switch trackers, restyle, or restart from scratch.
04 同仓库更多 Skills
whips
Route any non-trivial task through one entry: match a playbook, drive HIT skills plus subagents, open a reviewed ready PR with ship-pr-shaped evidence.
verify-upkeep
Periodic upkeep for a project's verification skill: source wave plus live pass per feature, at most one PR of proven corrections. Use to audit the verify skill.
verify-statechart
Check a TLA+ model of a system that moves between states, such as a product flow, a protocol, or a service, and draw it as a Mermaid statechart. The report gives the shortest path to each state that breaks a rule. Use to show a bug as a path through states.
verify-new
Generate a project-local skill that drives the app like a user (launch, doctor, drive, evidence, feature map), proven once. Use when a project has no scripted proof.
ship-triage
Move issues and external PRs through a state machine of triage roles, categorise, verify, interview if needed, and write agent-ready briefs.
ship-runner
Run ready-for-agent issue queues on any schedule through /whips intake, one fresh worktree each, landing per risk tier, with the agent and model you pick at setup.