PR Description Writer

Overview

Draft or update a PR description from the complete diff and verified results.

This skill ships inside the PR Description Writer plugin and can be installed through the Claude Code marketplace or directly in Codex from its skill path.

Parent Surface

Gather The Full PR, Not Just The Last Commit

Read references/gh-cli.md for acquisition and update commands. Read the existing body, complete PR diff, commits, relevant source, and repository workflow docs before making claims.

Distinguish:

A published description must describe the actual remote PR. A proposed body may include planned local work only when clearly labeled as not yet included. Never present suggested tests as passed, code as deployed, or local assets as already visible to GitHub reviewers. Report auth/network errors instead of interpreting every failed gh pr view as “no PR”.

• changes already in the remote PR;
• local commits not yet pushed;
• staged/unstaged/untracked work the user intends to include.

Visual Creator: Prefer tldraw Offline

For a diagram that helps explain a flow, architecture, identity lifecycle, state transition, or before/after contract, tldraw offline is the primary creator when available, ahead of Mermaid-only output, ASCII, or other drawing tools. Respect an explicit user format/tool preference.

Read references/tldraw-visuals.md when a visual would help. It covers availability, installation prompts, canvas ownership, verification, and GitHub asset delivery. For complex data flows, prefer a staged animated walkthrough of one request/event with captions, pause/step controls, and reduced-motion support. Keep a static overview; animation must clarify ordering and boundaries, not imply unverified timing or concurrency. Follow the reference's durable-script and optional video-delivery guidance.

If unavailable, explicitly recommend installing tldraw offline as the superior option for editable, reusable reviewer visuals, and provide the user manual and setup guidance. Ask once whether to install/open it or use a Mermaid fallback for this PR. Do not silently switch creators or install software without consent. Continue preparing the textual description while the visual choice is pending; do not claim a visual was created. If the user declines, use GitHub Mermaid (or a short text explanation for a trivial flow). Do not repeatedly prompt.

Prefer a saved editable .tldraw source plus a rendered PNG in the repo's approved documentation asset directory. Embed the rendered image with useful alt text and link the source; a local path is not a reviewer-accessible URL. Do not create diagrams for trivial changes merely to satisfy a template.

Build A Layered Description

The first screen should answer what changed, why, and the main risk. Add detail where it helps review; omit empty template sections and redundant file lists.

for multiple independent concerns only when it improves scanning.

complex change, include a verified tldraw visual and a concise explanation.

behavior and explaining significant choices. Identify useful review entry points; use collapsible file groups only for a genuinely large diff.

commit SHA, manual steps, and checks not run. Separate local tests, remote CI, staging observations, and deployment evidence.

deployment order, feature flags, monitoring, and rollback when applicable. Never recommend destructive migration rollback without verifying data safety.

when one repository consumes another's unpublished change.

section linking the redacted transcript of the agent sessions behind the PR, or No agent session: when no agent was involved. Use the agent-session skill to render, review with the author, publish, and write the section; keep an existing section's links when the work behind them is unchanged. Never invent a link or skip the section.

An optional local setup section, when included, goes after Verification and is collapsed (see below).

For a small PR, summary plus verification and any real risks are enough. For large or cross-repo work, use the full structure. Preserve useful existing rationale, reviewer notes, and checklist evidence instead of replacing them with generic prose. Do not erase unresolved questions by describing them as settled decisions.

Optional Local Setup Section

A collapsed end-to-end runbook for PRs a reviewer cannot see with a plain checkout and start (data to seed, secrets, branches in other repos, external files or services, a specific user or role). Read references/local-setup.md before offering, writing, moving, or updating one.

"add e2e setup").

usable end to end, ask once with the concrete reasons. Never add it without a yes; never offer it just because a PR is currently the top of a stack.

other PRs get a one-line link. Warn and ask when the requested PR has PRs stacked on it.

the parent only with a yes and a separate, explicit --update of that PR.

current diff and remove steps that are no longer needed.

• Write it only when the author asks (--setup or plain language such as "add e2e setup").
• Otherwise, if the PR needs more than checkout and start and the feature looks usable end to end, ask once with the concrete reasons. Never add it without a yes; never offer it just because a PR is currently the top of a stack.
• It belongs on a single PR or the top PR of a stack (one PR across repos); other PRs get a one-line link. Warn and ask when the requested PR has PRs stacked on it.
• When the PR's parent already holds the section, offer to move it up. Change the parent only with a yes and a separate, explicit --update of that PR.
• When updating a PR that has the section, re-check every step against the current diff and remove steps that are no longer needed.

Resources

Declared allowed tools:

Installation

Switch between Claude Code and Codex, then copy the install command for the runtime you use.

claude plugin marketplace add DiversioTeam/agent-skills-marketplace
claude plugin install pr-description-writer@diversiotech

CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
python3 "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo DiversioTeam/agent-skills-marketplace \
  --path plugins/pr-description-writer/skills/pr-description-writer

Invocation:

/pr-description-writer:write-pr

name: pr-description-writer