Skip to content

urmzd/dotfiles / dot_agents/skills/pr

Open a pull request via gh pr create with a reviewer-ready body: What, Why, How, Verification with real evidence, and a Demo (screenshot, GIF, terminal capture, or plan output). Follows the repo's pull_request_template.md when one exists. Use when the user says "create a pull request", "open a PR", "gh pr create", "raise a PR", or "make a PR for this branch", and whenever an agent opens a PR as part of a larger task. Also use to rewrite the body of a thin existing PR (gh pr edit). Assumes commits already exist and only opens the PR. Do NOT commit changes or watch CI (use ship); do NOT diagnose or fix a failing pipeline (use fix-and-retry / diagnose-ci).

PR

A PR body is for a reviewer who has not seen the session. It must answer, in order: what changed, why, how, how we know it works, and what it looks like. The commit log alone never does that.

Steps

  1. Gather context:

    • Default branch: gh repo view --json defaultBranchRef -q .defaultBranchRef.name
    • Commits: git log <default>..HEAD --format='%h %s%n%b'
    • Diff: git diff <default>...HEAD --stat, then read the diff itself
    • Pushed? git rev-list @{u}..HEAD --count 2>/dev/null
    • Template: .github/pull_request_template.md (or .github/PULL_REQUEST_TEMPLATE/)
    • Linked issues: any issue named in commits, or gh issue list --search "<keywords>"
  2. Collect evidence before writing. Run or reuse the checks that prove the change, and keep their actual output:

    • Tests or build: the command and its pass line (ok, test counts)
    • Infrastructure: the terraform plan summary (Plan: 1 to add, 0 to change, 0 to destroy) and the resource addresses
    • Bug fix: the failing output before, the passing output after
    • Never claim a check you did not run. Unrun checks are unchecked boxes.
  3. Make the demo (see Demo rules). gh cannot upload images, so use a capture that is already hosted (teasr output, a release asset, a CI artifact, a committed showcase image) or a fenced terminal block. Do not commit screenshots just for the PR.

  4. Push if needed: git push -u origin HEAD.

  5. Write the body. If the repo has a template, fill its headings and fold these sections into them; otherwise use this:

    ## What
    <1 to 3 sentences: the change, in user-visible terms.>
    
    ## Why
    <The problem or goal. Link the issue (Closes #N) or quote the failure it fixes.>
    
    ## How
    - <Approach and key decisions, one bullet each, naming files or components.>
    - <Alternatives rejected, only if a reviewer would ask.>
    
    ## Verification
    - [x] <check run>: `<command>` gives `<result line>`
    - [ ] <check not yet run, e.g. "deploy after merge">
    
    ## Demo
    <Screenshot, GIF, terminal capture, or plan excerpt. "None: <reason>" only when nothing is observable.>
    
    ## Notes
    <Breaking changes, follow-ups, rollout order, what the reviewer must do. Omit if empty.>
    
  6. Create: gh pr create --title "<title>" --body-file <file> (or a quoted HEREDOC). Never --fill: it copies the commit message and skips all of the above.

  7. Report: the PR URL.

Demo rules

ChangeDemo
UI, console, siteScreenshot or GIF (teasr, or a browser capture) of the changed screen
CLI or tool outputFenced block of the real command and its output
InfrastructureThe plan summary plus the resource addresses it creates or changes
Build, CI, DockerThe failing line before and the passing line after
Docs onlyLink to the rendered file on the branch
Refactor, no behavior change"None: no behavior change" plus the test result

Rules

  • Never create a PR if there are no commits ahead of the default branch.
  • If a PR already exists for this branch, improve its body with gh pr edit --body-file instead of opening a duplicate.
  • Title: conventional-commit style, under 70 characters.
  • No em dashes. No secrets or tokens.
  • Write for someone with no session context: name the system, the symptom, and the fix.

Gotchas

  • Refuse when HEAD is the default branch: compare git branch --show-current to the default and stop if they match.
  • For a fork-based PR, qualify the head: gh pr create --head <owner>:<branch>.
  • gh pr create --fill and --fill-first produce commit-message bodies. Do not use them, even inside a larger task that is in a hurry.
  • A merged PR's body can still be edited with gh pr edit: fix thin bodies after the fact rather than leaving them.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 319kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall