PR

Open a pull request

Work the steps in order. A pair of hooks runs alongside them and refuses the shortcuts. A direct gh pr create is out, so is a gh pr edit rewriting the title or body, and so is any publish whose description the reviewer hasn't seen in its current form.

This skill ends when the pull request is open. From there watch-pr, fix-pr, and merge-pr take over, and step 8 routes to whichever the operator asked for.

Preflight

!bash ${CLAUDE_SKILL_DIR}/scripts/preflight.sh

Step 0: the checklist

Track these steps with the session's task-list tools where it carries them. Newer harnesses leave those tools out by default, and a session without them works the list in order as written.

1. Confirm the branch is ready
2. Draft the description in PR_AGENTDESC.md
3. Pass the prose gates with fix-prose
4. Review the draft with review-pr-description
5. Run the validator and the prose gates
6. Ask the operator how far to take it
7. Publish the pull request
8. Route the rest

Stop before any of it where preflight reports a rebase, merge, or cherry-pick in progress, or a missing precondition. Say what's wrong and hand back.

Step 1: confirm the branch is ready

Preflight answered each of these, so read rather than re-run:

• The branch has commits the base doesn't. Nothing to open otherwise.
• The branch isn't the default branch.
• Uncommitted changes stay out of the pull request. Where preflight listed some, say so and let the operator decide before going on.
• A pull request may already exist. Where one is open, publishing updates it rather than opening a second.
• The branch has a current base. Where preflight reports it behind the default branch, run the rebase skill before opening, so the reviewer reads the branch against the base it actually merges into.

Preflight also settled the draft on disk. It removed a stale PR_AGENTDESC.md where no open pull request matched it, then scaffolded a fresh one from the template. That scaffold has the frontmatter keys, a placeholder title, and every section the template declares, so nothing downstream reproduces the template's shape from memory. It fails the validator until something fills it, which is the point.

Step 2: draft the description

Invoke the write-pr-description skill, passing the repository root from preflight as its argument.

It runs forked, which keeps the branch diff in its context rather than this one, and it runs the mechanical validator until it reports nothing before returning. It comes back with DRAFT: WRITTEN plus what it changed, or with DRAFT: BLOCKED plus what stopped it. Where it reports a block, say what it found and hand back, because this workflow has nothing left to publish.

Don't write PR_AGENTDESC.md yourself. A guard hook refuses it, because editing the draft here means reading the diff here, which spends the whole point of forking the writer.

Step 3: pass the prose gates

Invoke the fix-prose skill, passing the draft and the task that judges it:

Skill(fix-prose, args: "PR_AGENTDESC.md mise run lint-pr-description")

It runs the lint rounds in a subagent, so the findings stay out of this session.

Run it before the review rather than after. The review in the next step signs the exact bytes it cleared, and a lint fix landing later voids that signature and buys another round.

Step 4: review the draft, and loop

Invoke the review-pr-description skill, passing the repository root. It runs as an independent agent that watched neither the work nor the drafting, so it reads the description against the branch with no memory of what anyone meant to write.

Its verdict drives a loop:

• VERDICT: PASS ends the loop. Go on to step 5.
• VERDICT: CHANGES REQUIRED sends the findings back to write-pr-description, verbatim, in its arguments. Then review again.

Bound it at three rounds, counting only the rounds a finding caused. A round the branch caused doesn't count against the bound. A remediation commit or a rebase changes what the description has to describe, and the reviewer then reads a branch it has never seen. Say which kind each round was as you go, so the count is accurate.

Past three, stop rather than opening a fourth. Report the count out loud along with the findings that keep coming back, and let the operator decide whether to go on.

A bound nobody reports is one nobody notices breaking.

This step is mandatory, and create-pr.sh enforces it. A clean verdict signs the exact bytes of the draft, a finding erases any earlier signature, and a later edit voids it the same way.

Step 5: run the validator and the prose gates

mise run lint-pr-description

That task runs the mechanical checks, then vale and cspell over the draft. The validator settles the frontmatter shape, the title's form and bounds, section presence and order, empty sections, surviving comments, unclosed fences, dead links, and whether every backticked path exists. Each finding names a line and the fix.

Resolve every one through fix-prose rather than editing it yourself, because a direct edit here spends the context that skill exists to save. Edited the draft either way? Then step 4 runs again, because the gate compares bytes rather than intentions.