Skill: PR Description
Create or update PR description based on git diff.
Inputs
Steps
Gather context:
- Refresh the base first:
git fetch origin "$BASE". gh repo view hands back a branch
name; it does not update the local remote-tracking ref, and a stale origin/$BASE
describes commits that merged upstream days ago as if they were this PR's.
- For new PR:
git diff "origin/$BASE"...HEAD and git log "origin/$BASE"..HEAD --oneline
- For existing PR:
gh pr diff <pr-number>, and its current body:
gh pr view <pr-number> --json title,body. An update is a merge, not a rewrite: a body
often carries hand-written limitations, verification evidence and issue links that the
diff cannot reconstruct, and --body-file replaces all of it silently. Carry that
content forward, and only rewrite what the diff has actually made wrong.
Generate description in this format:
## Changes
### Summary
[Brief summary of changes - 1-3 sentences]
### Business Context
[Business/technical context - why was this change needed. Infer from branch name, commits, and code changes. Remove this section if unclear.]
### Changes
[Technical approach - main architectural decisions, main changes. Use bullet points.]
### Architecture
[Diagrams, for an architectural change only — see Rules. Reference each attached image as `` with one sentence saying what the reader should take from it. Remove this section for a change with no architectural shape.]
### Verification
[Example queries, commands, or steps to verify the changes work correctly. When the change is observable through the project's own tracing/observability backend (new or changed spans, telemetry attributes, logged events — check whether the repo has one before assuming), include links or excerpts from example traces you actually produced — see Rules.]
### Linked Issues
[Link to any relevant issues or tickets found in branch name or commits. Remove this section if none found.]
Execute (write the body to a file and pass --body-file; a long body with backticks
does not survive --body "…" intact):
- New PR:
gh pr create --base "$BASE" --title "<title>" --body-file body.md
- Existing PR:
gh pr edit <pr-number> --body-file body.md
- Diagrams go in the body as mermaid, so there is nothing to upload and no asset URL to
go stale.
gh has no image-upload flag - --attach is not a flag gh pr create or
gh pr edit has ever exposed - and a local PNG referenced by path renders as a broken
image for every reviewer.
Return the PR URL.
Rules
- No "Test plan" or "Generated with..." sections
- Keep descriptions concise
- Use present tense ("Add", "Update", "Remove")
- Omit
Business Context and Linked Issues sections when there's nothing to fill in — don't leave placeholders
- Include trace/log evidence for observable changes, when the repo has the means to produce it. When the change produces or alters observability (new/changed spans, telemetry attributes, structured logs) and the project has a tracing or logging backend, link to or excerpt example traces/log lines you actually produced in the
Verification section — one per meaningful path (happy path + key error paths), using that backend's own link format (e.g. a dashboard deep-link, a log query, a captured span tree). Only cite evidence you genuinely produced — never fabricate ids, URLs, or output. If the project has no such backend, or the change isn't observable through one, skip this and verify with the project's normal test/run commands instead.
- Attach diagrams for an architectural change. When a change adds or reshapes a flow
across components — a new tool or service path, a new gate, a state machine, a
cross-channel behaviour — put images in the
Architecture section rather than making the
reviewer rebuild the shape from the diff. Two usually suffice: one component/flow diagram
(who calls what, and what each outcome writes) and one sequence diagram (the call order,
with the refusal branches). Put the mermaid straight in the body, in a fenced ```mermaid
block: GitHub renders it in a pull request description, so the diagram needs no renderer,
no uploaded asset and no version of anything. It also stays readable in the diff and as
text, which a PNG does not. A committed architecture doc's diagram belongs wherever this
repo keeps those instead, e.g. docs/architecture.md, a docs/architecture/ directory,
or an ADR. Diagram the mechanism the PR actually changes, including its failure paths; a
box-and-arrow restatement of the module tree earns nothing. Skip the section for a fix, a
test-only change, or a one-file tweak.
1---2name: pr-description3description: Create or update PR. Use this skill every time user asks to create or update a PR to ensure clear, consistent descriptions between PRs.4metadata:5 source: https://skillmd.com/skills/vstorm-co/pr-description6---78# Skill: PR Description910Create or update PR description based on git diff.1112## Inputs1314- **PR number** — required when updating an existing PR; provided by the user (referred to as `<pr-number>` below)15- **Base branch** — detect dynamically; do not assume `main`:16 ```bash17 BASE=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)18 ```19 If the user names a different base (e.g. `develop`), use that instead.2021## Steps22231. **Gather context**:24 - Refresh the base first: `git fetch origin "$BASE"`. `gh repo view` hands back a branch25 *name*; it does not update the local remote-tracking ref, and a stale `origin/$BASE`26 describes commits that merged upstream days ago as if they were this PR's.27 - For new PR: `git diff "origin/$BASE"...HEAD` and `git log "origin/$BASE"..HEAD --oneline`28 - For existing PR: `gh pr diff <pr-number>`, **and its current body**:29 `gh pr view <pr-number> --json title,body`. An update is a merge, not a rewrite: a body30 often carries hand-written limitations, verification evidence and issue links that the31 diff cannot reconstruct, and `--body-file` replaces all of it silently. Carry that32 content forward, and only rewrite what the diff has actually made wrong.33342. **Generate description** in this format:3536```markdown37## Changes3839### Summary4041[Brief summary of changes - 1-3 sentences]4243### Business Context4445[Business/technical context - why was this change needed. Infer from branch name, commits, and code changes. Remove this section if unclear.]4647### Changes4849[Technical approach - main architectural decisions, main changes. Use bullet points.]5051### Architecture5253[Diagrams, for an architectural change only — see Rules. Reference each attached image as `` with one sentence saying what the reader should take from it. Remove this section for a change with no architectural shape.]5455### Verification5657[Example queries, commands, or steps to verify the changes work correctly. When the change is observable through the project's own tracing/observability backend (new or changed spans, telemetry attributes, logged events — check whether the repo has one before assuming), include links or excerpts from example traces you actually produced — see Rules.]5859### Linked Issues6061[Link to any relevant issues or tickets found in branch name or commits. Remove this section if none found.]62```63643. **Execute** (write the body to a file and pass `--body-file`; a long body with backticks65 does not survive `--body "…"` intact):66 - New PR: `gh pr create --base "$BASE" --title "<title>" --body-file body.md`67 - Existing PR: `gh pr edit <pr-number> --body-file body.md`68 - Diagrams go in the body as mermaid, so there is nothing to upload and no asset URL to69 go stale. `gh` has no image-upload flag - `--attach` is not a flag `gh pr create` or70 `gh pr edit` has ever exposed - and a local PNG referenced by path renders as a broken71 image for every reviewer.72734. Return the PR URL.7475## Rules7677- No "Test plan" or "Generated with..." sections78- Keep descriptions concise79- Use present tense ("Add", "Update", "Remove")80- Omit `Business Context` and `Linked Issues` sections when there's nothing to fill in — don't leave placeholders81- **Include trace/log evidence for observable changes, when the repo has the means to produce it.** When the change produces or alters observability (new/changed spans, telemetry attributes, structured logs) and the project has a tracing or logging backend, link to or excerpt **example traces/log lines you actually produced** in the `Verification` section — one per meaningful path (happy path + key error paths), using that backend's own link format (e.g. a dashboard deep-link, a log query, a captured span tree). Only cite evidence you genuinely produced — never fabricate ids, URLs, or output. If the project has no such backend, or the change isn't observable through one, skip this and verify with the project's normal test/run commands instead.82- **Attach diagrams for an architectural change.** When a change adds or reshapes a flow83 across components — a new tool or service path, a new gate, a state machine, a84 cross-channel behaviour — put images in the `Architecture` section rather than making the85 reviewer rebuild the shape from the diff. Two usually suffice: one component/flow diagram86 (who calls what, and what each outcome writes) and one sequence diagram (the call order,87 with the refusal branches). Put the mermaid straight in the body, in a fenced ```mermaid88 block: GitHub renders it in a pull request description, so the diagram needs no renderer,89 no uploaded asset and no version of anything. It also stays readable in the diff and as90 text, which a PNG does not. A committed architecture doc's diagram belongs wherever this91 repo keeps those instead, e.g. `docs/architecture.md`, a `docs/architecture/` directory,92 or an ADR. Diagram the mechanism the PR actually changes, including its failure paths; a93 box-and-arrow restatement of the module tree earns nothing. Skip the section for a fix, a94 test-only change, or a one-file tweak.