AGENT SKILL

create-pr

Open one pull request as a draft, with a body the reviewer can act on.

License 许可
MIT
最近更新
2026-11-12
Stars
★ 1
Forks
0

01 前言 Front Matter

name
create-pr
metadata
{ "credits": [ { "url": "https://github.com/humanlayer/skills/blob/main/plugins/show-me/skills/show-me/SKILL.md", "skill": "show-me", "author": "Dex Horthy", "organisation": "Humanlayer" }, { "url": "https://github.com/mattpocock/skills/blob/main/skills/engineering/pr/SKILL.md", "skill": "pr", "author": "Matt Pocock" } ] }
description
Open one pull request as a draft, with a body the reviewer can act on.

03 SKILL.md 正文

Create PR

Read /writing-for-humans skill first. It carries the title, the shape, the evidence rules, and the de-slopping pass. This skill adds only what a pull request needs on top.

The work is already written and committed. This turns it into a pull request a reviewer can act on. It opens as a draft. Marking it ready for review is the author's call, never yours.

The body carries what the diff can't

The diff is already open in the reviewer's tab. Anything they can read there is not your job to restate: bullets that say "adds X", "moves Y", "renames Z" pad the body without giving the reviewer something new. The body is these sections, in this order:

  1. ## What problem this solves — the issue that already exists, or the feature that is missing. What was true before, and what forced the change: the trigger, the report, the deadline, the security note.

  2. ## How this PR solves it — the idea holding the lines together, and the alternative you rejected. The reviewer reads the diff for the lines; they read this for the shape, so show it: see Show the shape.

  3. ## What happens when this merges — the effect downstream. Behaviour that changes for users, a migration that has to run, a follow-up this unblocks. Name the door: one-way when the merge is hard to walk back (a destructive migration, a published contract, deleted data), two-way when a revert undoes it. Then the blast radius: what breaks if the change is wrong (consumers, layout, mobile, a scheduled job).

  4. ## QA steps — how a person tries the change by hand before it merges, as a list of scenarios. Each scenario is an unticked checkbox naming one behaviour, with its steps numbered beneath it from a checkout of the branch: the command to run or the thing to click, then the result they should see. Scenarios for the changed behaviour come first, then its blast radius. CI already reports the tests, so every step is something a person does by hand. A change with no visible behaviour, such as a refactor, gets the scenario that shows nothing moved. Whoever tries a scenario and sees it pass ticks its box.

    - [ ] **Saving settings shows a toast**
      1. `pnpm dev`, open `/settings` → the form loads with your current values.
      2. Change the name, click Save → a "Saved" toast appears.
    
  5. ## Notes — what a careful reader still cannot infer from the diff after reading it. Invariants that hold across the change, a decision that looks arbitrary but was deliberate, a gotcha that will trip the next person, a constraint from outside the repo.

Anything belonging to none of them gets its own section after them, named the way a colleague would name it.

Every section survives on the test "could the reviewer figure this out from the diff alone?" A section that fails comes out rather than getting padded. What problem this solves and QA steps stay regardless — the reason for a change and how to try it are never in the diff — so a body carrying only those two is a fine pull request.

Show the shape

Pick the smallest visual that makes the approach clear, and place it beside the sentence it supports. Usually one, sometimes two:

  • Logic or an algorithm: pseudocode.
  • Runtime control flow: a call tree.
  • UI structure: a component tree, with the state and module boundaries that matter.
  • File responsibilities or a broad refactor: a shallow file tree, one comment per folder.
  • Interaction or data flow between parts: a Mermaid diagram.
  • A change to a shape that already exists: a diff block of that tree or flow.
 submitForm
   createSession
     persistPrompt
+    expandSkillMention
     launchAgent

Keep only the calls, files and boundaries the reviewer needs to see the idea. A visual that copies the code diff fails the diff-alone test like any bullet.

Read the diff, don't imagine it

git diff <base>...HEAD and git log <base>..HEAD before you write a word.

Every claim in the body traces back to a line you read. A body that describes a change the diff does not contain costs the reviewer more than an empty body: they have to find the lie before they can start reviewing.

Reading the diff also settles which sections are real. If a bullet you drafted turns out to sit in plain view of the diff, it fails the test and comes out.

The title becomes history

Your title is the line the squashed merge commit carries, so write it for git log.

Link the ticket

Closes owner/repo#123 at the bottom of the body, so merging closes the ticket. Reference the ticket by ID rather than pasting a link: some trackers put private detail in the URL.

No ticket exists? Write the body anyway and leave the line off. Do not open a ticket just to link it.

Length

One change per PR. A refactor and a fix in the same diff make the reviewer grade two things at once, and they will do both worse.

Process

1. Check where you are

You need a branch that is not the default one, and a clean tree with your work committed. On the default branch, or holding uncommitted changes? Say so and stop.

Done when: you know the base branch, the current branch, and that nothing is uncommitted.

2. Read the change

The diff, the log, and the ticket it closes.

Done when: from what you read, you can state the problem, the approach, the downstream effect with its door and blast radius, the QA scenarios a reviewer will try, and every Note you plan to include.

3. Draft the body

Title, then the sections in order, then any section that fits none of them, then the ticket line. Drop a section that fails the diff-alone test rather than filling it.

4. Clean it up

Run the draft through /writing-for-humans: the title, the evidence, the secrets check, and the humanizer pass. Extra tells in a pull request:

  • A bullet per file that only restates the filename.
  • A second section of checks beside ## QA steps (How you know, Verification). Fold it into QA steps, or cut it if it only restated the diff.

5. Open it

Push the branch and open the pull request as a draft:

gh pr create --draft --base <base> --title "<title>" --body "<body>"

Return the link, and say plainly that it is a draft waiting for them to mark it ready for review.

Labels go on after it exists (gh pr edit <n> --add-label ...), and only labels the repo already has.

Where it goes

GitHub through the gh CLI is the fallback. Before you settle for it, check git remote -v: GitLab takes glab, where the draft flag is --draft on glab mr create.

A repo pull request template at .github/pull_request_template.md is the house style, and it wins. Fill its sections; sections that do not apply to this change come out rather than getting padded. A template with no QA section still gets ## QA steps, after its own sections.

Boundaries

Opens the pull request. Reviewing it, merging it, and marking it ready for review belong to a person.

04 同仓库更多 Skills

synmux
synmux/claude-commit

writing-for-humans

How to write a short document a person has to read and act on - a ticket, a pull request body, a commit message, a handover note. Covers the title, a shape people skim, evidence that survives a refactor, and stripping the AI phrasing out. Call it before drafting any of those.

★ 1
synmux
synmux/claude-commit

writing-for-agents

Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.

★ 1
synmux
synmux/claude-commit

node-cli

Patterns and conventions for building Node.js CLI tools — src structure, entry point setup, Commander wiring, and update notifications. Use when creating or modifying a Node.js CLI, adding Commander commands, wiring update-notifier, or asking how to structure a CLI entry point or src directory.

★ 1
synmux
synmux/claude-commit

humanizer

Removes traces of AI-generated text. Suitable for editing or reviewing text to make it sound more natural and human-written. Based on the comprehensive Wikipedia guide on "AI writing characteristics." Detects and fixes patterns such as: exaggerated symbolism, promotional language, superficial analysis ending in "-ing," vague attribution, overuse of dashes, the rule of three, AI-typical vocabulary, negative parallelism, and excessive transitional phrases.

★ 1
synmux
synmux/claude-commit

create-ticket

Draft one small, plain ticket as a markdown file, then file it on the project's tracker once the user approves.

★ 1
synmux
synmux/claude-commit

create-pr

Open one pull request as a draft, with a body the reviewer can act on.

★ 1