agentleFS
mattbutlerengineeringmattbutlerengineering/mattbutlerengineering/.claude/skills/ship-pr/SKILL.md

ship-pr

Skill3 starsChanged 2 days agoMITView on GitHub

Runs the full merge boundary on one open PR — fast-path decision, CI-gate classification, specialist and universal review, then merge — via the implement-queue profile's hooks, outside the queue loop. Invoke with /ship-pr <N> [--ready].

32 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use review-pr, implement and 8 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • DockerSkill

    review-pr

    Review one or more incoming Docker documentation pull requests as a maintainer. Independently validate technical claims, assess editorial fit and information architecture, choose a verdict, and draft exact inline or PR-wide feedback behind a confirmation gate. Use for requests such as "review PR 123", "is this PR correct?", "does this information belong here?", "validate this PR", or "help review backlog PRs". Do not use to maintain or fix a PR you own; use maintain-pr for that.

    Also in 5 projects that use this

  • Hugging FaceSkill

    implement

    Make tests pass. Invoke after /write-tests produces failing tests.

    Also in 5 projects that use this

  • Google CloudSkill

    triage

    Gather context on a change or bug and plan the implementation.

    Also in 4 projects that use this

  • GitHubSkill

    refactor

    Surgical code refactoring to improve maintainability without changing behavior. Covers extracting functions, renaming variables, breaking down god functions, improving type safety, eliminating code smells, and applying design patterns. Less drastic than repo-rebuilder; use for gradual improvements.

    Also in 3 projects that use this

  • GoogleSkill

    diagnosing-bugs

    Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

    Also in 3 projects that use this

  • GoogleSkill

    domain-modeling

    Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.

    Also in 3 projects that use this

  • +3 more from google

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 1 is distinctive, and 6 are very specific to this project.

  • 0

    Common

    Most of the 32 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Stop at the first step that doesn't clear — never fall through to the merge step on anything but a clean pass.

    line 31
  2. Very specific:

    Only once holds clear, and only if --ready was passed, run gh pr ready <N>.

    line 47
  3. Very specific:

    CI-gate classification: Follow .claude/implement-queue.md § ci-status verbatim, including its gate-missing dispatch-and-re-poll recovery …

    line 64
  4. Very specific:

    Only state: "green" proceeds to step 4.

    line 73
  5. Very specific:

    Review: Follow .claude/implement-queue.md § fast-path and § reviewers as written: whether review can be skipped is step 2's fastPath, not …

    line 77
  6. Very specific:

    Create a throwaway worktree of the PR head (git fetch origin pull/<N>/head then git worktree add --detach <scratch-path> <headRefOid>), …

    line 91
  7. Very specific:

    If GitHub reports the PR CLEAN and refuses --auto, merge directly with the same command minus --auto — this path, too, runs only after the …

    line 123

“Common” is measured: kept by at least 6 in 10 of the 32 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/ship-pr

A single-PR run of the same merge boundary /idea-to-prod:implement-queue runs per-PR in its own loop. This skill owns no gate logic of its own — every step below is a pointer into .claude/implement-queue.md's profile and the scripts it names. If a step's rule ever needs to change, change it there; this file must never grow a restated copy of a rule it only references (the duplicated-sentence drift recorded in .claude/rules/gotchas.md is exactly this failure mode).

Invocation

/ship-pr <N> [--ready]
  • <N> — an open PR number.
  • --ready — the PR is a draft; without this flag a draft PR is refused outright (an explicit author hold, not something this skill flips on its own). With it, run gh pr ready <N> once step 1's hold check clears, then continue.

Protocol

Stop at the first step that doesn't clear — never fall through to the merge step on anything but a clean pass.

  1. Precondition. Confirm the PR is open and read its draft state and labels: gh pr view <N> --json state,isDraft,labels,headRefOid,body. If it's a draft and --ready was not passed, stop and report "draft PR — pass --ready to proceed."

    Then check holds. The linked issues are the ones a GitHub closing keyword in the PR body names (Closes / Fixes / Resolves #M, any tense or case; none → only the PR's own labels count); read each one's labels with gh issue view <M> --json labels. If the PR or a linked issue carries any label in the profile's hold_labels (.claude/implement-queue.md frontmatter), stop here and report held — <label>: nothing is written to the PR, no review is dispatched, and nothing is merged.

    Only once holds clear, and only if --ready was passed, run gh pr ready <N>.

  2. Fast-path decision.

    node scripts/fast-path-decision.mjs check --pr <N>

    One JSON line: {fastPath, reviewers, holdForHuman, reason}. It folds in the agent-core build-freshness check (rebuilding the dist if needed) and fails closed — no fast path, every specialist — when the dist cannot be trusted; see .claude/implement-queue.md § fast-path for the precedence. Exit 0 is any decision; exit 1 means gh could not fetch the PR, so stop and report it. Keep the JSON for step 4. Step 3's scripts/ci-gate-status.mjs is independent of it.

  3. CI-gate classification. Follow .claude/implement-queue.md § ci-status verbatim, including its gate-missing dispatch-and-re-poll recovery and its explicit abstain on gate-unattributed/unknown:

    gh pr checks <N> --watch
    node scripts/ci-gate-status.mjs check --pr <N>

    Only state: "green" proceeds to step 4. Every other state stops here, named, per that section's table — do not re-derive the handling for failed/pending/gate-missing/gate-unattributed/unknown here.

  4. Review. Follow .claude/implement-queue.md § fast-path and § reviewers as written: whether review can be skipped is step 2's fastPath, not re-decided here. Dispatch the diff-matched specialists step 2's reviewers names, plus the universal reviewer subagent unless fastPath is true. A gate-path PR (holdForHuman) is still reviewed; step 5 holds it.

    § reviewers assumes a queue worker. For a single PR, take its inputs from here instead:

    • Acceptance criteria — from the PR body plus the issues step 1 found. Only when both lack them, pass acceptanceCriteria: [] and say so in the ReviewInput's taskDescription.
    • Code on disk — there is no .claude/worktrees/agent-<taskId>/. Create a throwaway worktree of the PR head (git fetch origin pull/<N>/head then git worktree add --detach <scratch-path> <headRefOid>), give the reviewers that path in place of the worker's, and remove it (git worktree remove --force <scratch-path>) once they return.
    • Verdict handling — a flag (reviewer) or block (specialist) verdict stops this invocation: report it with the reviewer's output. There is no retry and no worker dispatch (the section's retry policy re-dispatches a worker, which /ship-pr does not have). Do not proceed to step 5.
  5. Merge. On an all-pass verdict (or a fast-path skip), first re-read holds, since a label can land while review runs: gh pr view <N> --json labels (plus the linked issues', as in step 1). Two things hold the PR for a human merge, and either one means the merge command below is not run:

    • a label in the profile's hold_labels on the PR or a linked issue — report held — <label>;
    • step 2's holdForHuman: true (a changed file matches a gate path) — report held for human merge — gate path.

    Otherwise follow .claude/implement-queue.md § merge-command:

    gh pr merge <N> --auto --squash --delete-branch

    Issue it as the whole Bash call, nothing else on the line: Bash(gh pr *) in .claude/settings.json approves the plain form before the auto-mode classifier runs; a compound form is classified and can be denied.

    If GitHub reports the PR CLEAN and refuses --auto, merge directly with the same command minus --auto — this path, too, runs only after the hold re-read above cleared. If the plain merge call is still denied with [Merge Without Review] (Claude Code Remote sessions, gotchas § CCR #6125), do not retry through this or any other tool — report the PR as reviewed, green, and awaiting a human merge.

Output

One summary screen at the end of the run (success or stop):

PR #<N>
  CI:       <classifyCiGateStatus state>
  Reviewers: <specialist list + verdicts, or "fast path — skipped">
  Universal: <reviewer verdict, or "fast path — skipped">
  Action:   <armed --auto | merged directly | held — <label> | held for human merge — gate path | stopped at <step> — <reason>>

Scope

This skill adds no new gate logic, scripts, or classifiers — every rule it points at already exists and is already exercised by /idea-to-prod:implement-queue's per-PR loop. It exists only to make that same boundary callable against one PR number on demand, outside the queue.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.