feat(skills): add pr-design-doc skill

README.md

@@ -89,7 +89,7 @@ The JS and Python versions are kept in lock-step by `release-please` and guarded
 ## Extensions Catalog
 
 <!-- BEGIN AUTO-GENERATED CATALOG -->
-This repository contains **2 marketplace(s)** with **64 extensions** (54 skills, 10 plugins).
+This repository contains **2 marketplace(s)** with **65 extensions** (55 skills, 10 plugins).
 
 ### large-codebase
 
@@ -108,7 +108,7 @@ OpenHands skills for interacting, improving, and refactoring large codebases
 
 Official skills and plugins for OpenHands — the open-source AI software engineer.
 
-**60 extensions** (52 skills, 8 plugins)
+**61 extensions** (53 skills, 8 plugins)
 
 | Name | Type | Description | Commands |
 |------|------|-------------|----------|
@@ -155,6 +155,7 @@ Official skills and plugins for OpenHands — the open-source AI software engine
 | openhands-sdk | skill | Reference skill for the OpenHands Software Agent SDK - build AI agents with custom tools, LLM configuration, conversa... | `/sdk` |
 | pdflatex | skill | Install and use pdflatex to compile LaTeX documents into PDFs on Linux. Use when generating academic papers, research... | — |
 | plain-english-content | skill | Write and edit clear, accessible prose in a plain English content style: active voice, front-loaded content, sentence... | — |
+| pr-design-doc | skill | For a non-trivial pull request, write a self-contained HTML design doc under the temporary .pr/ directory and link it... | `/pr-design-doc`, `/design-doc` |
 | pr-review | plugin | Automated PR code review — analyzes diffs and posts inline review comments via the GitHub API. | — |
 | prd | skill | Generate a Product Requirements Document (PRD) for a new feature through an interactive clarifying-question workflow.... | `/prd` |
 | qa-changes | plugin | Validate pull request changes by actually running the code — setting up the environment, exercising changed behavior,... | — |

marketplaces/openhands-extensions.json

@@ -5,15 +5,15 @@
     "email": "contact@all-hands.dev"
   },
   "metadata": {
-    "description": "Official skills and plugins for OpenHands \u2014 the open-source AI software engineer.",
+    "description": "Official skills and plugins for OpenHands — the open-source AI software engineer.",
     "maintainer": "OpenHands",
     "homepage": "https://github.com/OpenHands/extensions"
   },
   "plugins": [
     {
       "name": "agent-creator",
       "source": "./skills/agent-creator",
-      "description": "Create file-based sub-agents as Markdown files \u2014 no Python code required. Guides the user through a structured interview and generates a ready-to-deploy .md agent file following the OpenHands SDK specification.",
+      "description": "Create file-based sub-agents as Markdown files — no Python code required. Guides the user through a structured interview and generates a ready-to-deploy .md agent file following the OpenHands SDK specification.",
       "category": "agent-authoring",
       "keywords": [
         "agent",
@@ -429,7 +429,7 @@
     {
       "name": "openhands",
       "source": "./plugins/openhands",
-      "description": "Unified OpenHands plugin \u2014 bundles Cloud CLI, REST API (openhands-api), and Automations (openhands-automation) into a single plugin.",
+      "description": "Unified OpenHands plugin — bundles Cloud CLI, REST API (openhands-api), and Automations (openhands-automation) into a single plugin.",
       "category": "openhands",
       "keywords": [
         "openhands",
@@ -470,7 +470,7 @@
     {
       "name": "pr-review",
       "source": "./plugins/pr-review",
-      "description": "Automated PR code review \u2014 analyzes diffs and posts inline review comments via the GitHub API.",
+      "description": "Automated PR code review — analyzes diffs and posts inline review comments via the GitHub API.",
       "category": "code-quality",
       "keywords": [
         "pr-review",
@@ -482,7 +482,7 @@
     {
       "name": "qa-changes",
       "source": "./plugins/qa-changes",
-      "description": "Validate pull request changes by actually running the code \u2014 setting up the environment, exercising changed behavior, and posting a structured QA report.",
+      "description": "Validate pull request changes by actually running the code — setting up the environment, exercising changed behavior, and posting a structured QA report.",
       "category": "quality-assurance",
       "keywords": [
         "qa",
@@ -645,7 +645,7 @@
     {
       "name": "iterate",
       "source": "./skills/iterate",
-      "description": "Iterate on a GitHub pull request \u2014 drive it through CI, code review, and QA until merge-ready. Monitors state, fixes failures, addresses review feedback, retries flaky checks, and pushes fixes in one continuous loop.",
+      "description": "Iterate on a GitHub pull request — drive it through CI, code review, and QA until merge-ready. Monitors state, fixes failures, addresses review feedback, retries flaky checks, and pushes fixes in one continuous loop.",
       "category": "code-quality",
       "keywords": [
         "github",
@@ -770,6 +770,21 @@
         "jira",
         "atlassian"
       ]
+    },
+    {
+      "name": "pr-design-doc",
+      "source": "./skills/pr-design-doc",
+      "description": "For a non-trivial pull request, write a self-contained HTML design doc under the temporary .pr/ directory and link it in the PR description via htmlpreview, so maintainers grasp the proposal at a glance - the code/API design and the before/after of the change, grounded to real code.",
+      "category": "code-quality",
+      "keywords": [
+        "pull-request",
+        "design-doc",
+        "html",
+        "review",
+        "before-after",
+        "htmlpreview",
+        "pr"
+      ]
     }
   ]
 }

skills/pr-design-doc/.claude-plugin

@@ -0,0 +1 @@
+.plugin

skills/pr-design-doc/.codex-plugin

@@ -0,0 +1 @@
+.plugin

skills/pr-design-doc/.plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "pr-design-doc",
+  "version": "1.0.0",
+  "description": "For a non-trivial pull request, write a self-contained HTML design doc under the temporary .pr/ directory and link it in the PR description via htmlpreview, so maintainers grasp the proposal at a glance - the code/API design and the before/after of the change, grounded to real code.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "pull-request",
+    "design-doc",
+    "html",
+    "review",
+    "before-after",
+    "htmlpreview"
+  ]
+}

skills/pr-design-doc/README.md

@@ -0,0 +1,25 @@
+# PR Design Doc
+
+For a non-trivial pull request, write a self-contained HTML design doc under the temporary
+`.pr/` directory and link it in the PR description via htmlpreview, so maintainers grasp the
+proposal at a glance — the code/API design and the before/after of the change, grounded to
+real code.
+
+## Triggers
+
+This skill is activated by the following keywords:
+
+- `/pr-design-doc`
+- `/design-doc`
+
+## Details
+
+See [SKILL.md](./SKILL.md) for when to use it, the `.pr/` workflow (the directory is removed
+on approval for same-repository PRs, and manually before merge for fork PRs), the
+step-by-step process, and the non-negotiable principles.
+
+The HTML craft — the editorial look, hand-drawn before/after SVG technique, code grounding,
+and the htmlpreview delivery link — is in
+[`references/html-craft.md`](references/html-craft.md).
+
+Adapted from the `show-me` visualization skill for the OpenHands PR-review workflow.

skills/pr-design-doc/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: pr-design-doc
+description: >
+  For a non-trivial pull request, write a self-contained HTML design doc under the
+  temporary `.pr/` directory and link it in the PR description via htmlpreview, so
+  maintainers grasp the proposal at a glance — code/API design, and the before/after of
+  the change, grounded to real code. Use when opening or updating a non-trivial PR, or
+  when the user says "add a design doc", "document this PR for reviewers", "show the
+  before/after", "make the design reviewable", or "write the .pr/ page".
+triggers:
+- /pr-design-doc
+- /design-doc
+license: MIT
+metadata:
+  tags: pull-request, design-doc, html, review, before-after, htmlpreview
+---
+
+# pr-design-doc — a reviewable design doc for a non-trivial PR
+
+A diff shows *what changed line by line*. It does not show *the design*: the shape of the
+change, the API before and after, and why this approach. Reviewers reconstruct that by
+hand, slowly. The scarce resource is the maintainer's attention and trust budget — not the
+agent's effort. Spend extra effort to hand them **one self-contained HTML page** that
+conveys the **big picture** and the **before → after core difference**, with every claim
+**clickable back to the real code**, then link it from the PR description.
+
+This is the same craft as a "show me this change" explainer, aimed at one job: making a
+non-trivial PR easy to review.
+
+## When to use it
+
+- Opening or updating a **non-trivial** PR: new/changed public API, a new module or
+  subsystem, a behavior change in core logic, a migration, or anything a reviewer can't
+  fully judge from the diff in a couple of minutes.
+- **Skip it** for trivial PRs — a typo, a one-line guard, a dependency bump, a docs tweak, a simple bug fix.
+  A design doc adds more to review. Use judgment; if the diff *is* the explanation, don't add a
+  page.
+
+## The `.pr/` workflow (why this is safe to commit)
+
+OpenHands repos use a temporary **`.pr/`** directory for PR-only artifacts. For
+same-repository PRs it is removed automatically on approval (`.github/workflows/pr-artifacts.yml`
+in `OpenHands/OpenHands`); for **fork** PRs that cleanup does not run, so remove `.pr/`
+yourself before merging to keep it out of `main`. The doc is a review aid that lives with the
+branch and renders while the PR is open.
+
+## Workflow
+
+1. **Get the change.** You usually already have the branch. Otherwise:
+   ```bash
+   gh pr view <n> --json title,body,baseRefName,headRefName,files,additions,deletions
+   gh pr diff <n>                 # or: git diff <base>...<head>  /  git diff
+   gh repo view --json url        # for clickable blob links; pin the head SHA
+   ```
+   Group changed files by area; note the merge base and head SHA for source links.
+
+2. **Read both sides of each logical file.** `git show <base>:<path>` vs head. Capture the
+   **function-level** behavioral difference — what the code *did* vs *does now*.
+   - new file → no "before"; one "after" diagram + a line on the role it adds.
+   - deleted file → "before" diagram + who/what takes over.
+   - edited file → a before/after pair, with the delta highlighted.
+
+3. **Classify each file.** *Logic* change (behavior moved) → draw before/after. *Mechanical*
+   change (rename, constant, config, import move) → a one-line `before → after` row, no
+   diagram. Don't dilute the signal by drawing mechanical edits.
+
+4. **If the change is an API change, lead with the API.** Show the signature/schema/type
+   **before and after** side by side (function signature, endpoint + payload, config field,
+   event shape). Name the compatibility impact plainly: additive, breaking, or behind a flag.
+
+5. **Find the cross-file story.** If one call chain threads several files, draw a single
+   **overview** before/after at the top; per-file cards drill in.
+
+6. **Build the page** per [`references/html-craft.md`](references/html-craft.md) — one
+   self-contained, offline, editorial HTML file with hand-drawn SVG figures. Save it to
+   the repo's `.pr/` directory, e.g. `.pr/design.html` (or `.pr/<topic>.html`). If it
+   helps, lean on the `frontend-design` skill to make the page look polished.
+
+7. **Commit under `.pr/`, push, and link it.**
+   ```bash
+   git add .pr/design.html
+   git commit -m "docs(.pr): design doc for <PR topic>"
+   git push <your-fork> <pr-branch>
+   ```
+   Then add the htmlpreview link near the top of the PR description, pointing at the **fork
+   and branch the PR is opened from** (it renders before merge):
+   ```
+   📄 Design doc: https://htmlpreview.github.io/?https://github.com/<fork-owner>/<repo>/blob/<pr-branch>/.pr/design.html
+   ```
+
+## What the page contains
+
+1. **What changed (decision first)** — one paragraph: the intent, net effect, and why the
+   reviewer should care. Put the highest-impact conclusion, risk, or API-compat note in a
+   `★` callout, with the most important changed `path:line` nearby. Stats (`N files ·
+   +A / −D`) are context, not the lead. If there's a cross-file flow, the **overview
+   before/after SVG** goes here.
+2. **API before → after** (when the PR changes an interface) — signatures/schemas/types side
+   by side, with the compatibility verdict stated.
+3. **Left rail / index** — changed files grouped by area, each tagged (🟢 added · 🔴 removed ·
+   ✏️ changed · ⚙️ mechanical) with +/− counts; click to jump.
+4. **Per-file cards** — for each logical file: a claim-carrying title, a one-line summary of
+   how its behavior changed, **before/after** diagrams with real symbol names + `file:line`
+   (changed nodes in orange), and the diff in a collapsed `<details>`. Mechanical files get a
+   small `before → after` table, no diagram.
+5. **(optional) Risk / follow-ups** — only if grounded in what you read.
+
+## Non-negotiable principles
+
+1. **Optimize for scarce reviewer attention.** The first screen answers, in ~15 seconds:
+   what this PR does, whether it's risky, where to look first, and what evidence backs the
+   claim. Lead with the conclusion, not your process.
+2. **Show the difference, not just the after.** For any logic or API change, draw **before**
+   and **after** and make the *delta* visually loud (color + line style). The contrast is
+   the product.
+3. **Ground everything to code, beside the claim.** Every box, node, and sentence names a
+   real symbol + `path:line`, and links to the source (GitHub blob URL at the head SHA)
+   where possible. One click from "this changed" to the exact code.
+4. **Hand-draw the carrying diagrams.** Prefer bespoke inline SVG for the before/after that
+   makes the argument; Mermaid is fine only for quick auxiliary graphs.
+5. **Self-contained & offline.** One HTML file, inline CSS/SVG, opens by double-click,
+   survives being copied to another machine (htmlpreview needs this).
+6. **`.pr/` only, and temporary.** The doc is a review aid, not project docs. Keep it in
+   `.pr/` and ensure it is removed before merge (automatic on approval for same-repo PRs,
+   manual for forks). Do not move design HTML into `docs/` or ship it in the merged tree.
+
+## Anti-patterns
+
+- ❌ Dumping the raw diff / file tree and calling it a "design doc" — adds nothing over the
+  PR page.
+- ❌ Empty nodes ("process data", "handle request") — every node is a real symbol +
+  location.
+- ❌ Only the after-state when something changed — reviewers want the *contrast*.
+- ❌ A design doc on a trivial PR — noise. Skip it.
+- ❌ Committing the HTML outside `.pr/` (e.g. `docs/`), where it would merge into `main`.
+- ❌ A private-repo htmlpreview link — htmlpreview can't fetch private raw content (auth +
+  CORS). Use GitHub Pages or the local-serve fallback in the craft reference instead.

skills/pr-design-doc/commands/design-doc.md

@@ -0,0 +1,8 @@
+---
+# auto-generated by sync_extensions.py
+description: For a non-trivial pull request, write a self-contained HTML design doc under the temporary `.pr/` directory and link it in the PR description via htmlpreview, so maintainers grasp the proposal at a glance — code/API design, and the before/after of the change, grounded to real code. Use when opening or updating a non-trivial PR, or when the user says "add a design doc", "document this PR for reviewers", "show the before/after", "make the design reviewable", or "write the .pr/ page".
+---
+
+Read and follow the complete instructions in the SKILL.md file located in this skill's directory.
+
+$ARGUMENTS

skills/pr-design-doc/commands/pr-design-doc.md

@@ -0,0 +1,8 @@
+---
+# auto-generated by sync_extensions.py
+description: For a non-trivial pull request, write a self-contained HTML design doc under the temporary `.pr/` directory and link it in the PR description via htmlpreview, so maintainers grasp the proposal at a glance — code/API design, and the before/after of the change, grounded to real code. Use when opening or updating a non-trivial PR, or when the user says "add a design doc", "document this PR for reviewers", "show the before/after", "make the design reviewable", or "write the .pr/ page".
+---
+
+Read and follow the complete instructions in the SKILL.md file located in this skill's directory.
+
+$ARGUMENTS