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.

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.

Visual And Evidence Checks

addressed, export visually inspected, labels readable at PR viewing size.

tokens, confidential screenshots, or unapproved public uploads.

• Every diagram edge and claim matches the implementation being reviewed.
• Source and export represent the same canvas revision; source saved, lints addressed, export visually inspected, labels readable at PR viewing size.
• Image links work for the intended repo/audience; no local paths, bearer tokens, confidential screenshots, or unapproved public uploads.
• Test results distinguish executed checks from instructions for reviewers.
• Existing PR base and draft state are preserved unless a change was requested.
• Description covers the complete reviewed diff, not unrelated local work.

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