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

[smolpaws]

• A human has tested these changes.

HUMAN:
Human attention is a scarce resource. This PR proposes a skill to teach the agent the make-up of an HTML design doc for non-trivial PRs, that allows a better quick view of the proposed changes, than the raw diff. The doc would show the state before and after, and contains instructions to focus the agent on summarizing, on capturing what is relevant, including SVG diagrams if needed.

I have personally used a very similar skill for a few dozen arch notes, studies of a repo or component or feature behavior, and I think the result is much better to go through than raw diffs.

---

Why

Reviewers of a non-trivial PR often have to reconstruct the design from the diff alone — the shape of the change, the API before/after, and why this approach. That's slow and error-prone. This skill guides an agent to hand maintainers a single, self-contained HTML design doc they can grasp in ~15 seconds, grounded to real code.

It also operationalizes the .pr/ convention: the doc is committed under the temporary .pr/ directory (auto-removed on approval by pr-artifacts.yml), and linked in the PR description via an htmlpreview URL that renders before the PR is merged.

Companion guideline issue: OpenHands/OpenHands#16304.

Summary

• Add the pr-design-doc skill (/pr-design-doc, /design-doc): when to use it (and when to skip — trivial PRs), the .pr/ workflow, a step-by-step process, what the page contains (decision-first summary, API before/after, per-file before/after cards grounded to path:line), and anti-patterns.
• Include references/html-craft.md — the editorial look, hand-drawn before/after SVG technique, code-grounding discipline, and the htmlpreview delivery link (adapted so .pr/ + the fork/branch URL is the primary path).
• Register in the openhands-extensions marketplace + README catalog; add the .plugin manifest, vendor symlinks, and generated command files via scripts/sync_extensions.py.

Adapted from the show-me visualization skill, focused on the OpenHands PR-review workflow.

Issue Number

Related: OpenHands/OpenHands#16304

How to Test

# registry/catalog/symlinks/commands are all in sync
uv run python scripts/sync_extensions.py --check   # only the pre-existing, unrelated issue-duplicate-checker coverage warning

# skill structure + plugin-loading + sync tests
uv run pytest tests/test_skills_have_readme.py tests/test_skill_plugin_loading.py tests/test_sync_extensions.py tests/test_catalogs.py -q   # 117 passed

You can also read skills/pr-design-doc/SKILL.md and follow it against any non-trivial PR: it produces .pr/design.html and an htmlpreview link of the shape
https://htmlpreview.github.io/?https://github.com/<fork-owner>/<repo>/blob/<pr-branch>/.pr/design.html.

Notes

• Skills-only change; no integration catalog or code touched.
• The .pr/ auto-removal workflow lives in OpenHands/OpenHands; this skill documents relying on it.

Co-authored-by: smolpaws engel@enyst.org

[all-hands-bot]

👋 This PR needs a couple of things fixed before OpenHands can review it:

• the PR description's HUMAN: section needs at least 20 characters describing what you tested, not just the template placeholder

Push an update once this is addressed and this check re-runs automatically.

This is an automated check - no AI was used to generate this comment.

[all-hands-bot]

🚦 CI is currently failing on this PR's latest commit.

Please fix the failing checks before OpenHands reviews it - this is re-checked automatically once you push a new commit. (A maintainer can also request @all-hands-bot as a reviewer to have it reviewed regardless of CI status.)

This is an automated check - no AI was used to generate this comment.

[all-hands-bot]

🚦 CI is currently failing on this PR's latest commit.

Please fix the failing checks before OpenHands reviews it - this is re-checked automatically once you push a new commit. (A maintainer can also request @all-hands-bot as a reviewer to have it reviewed regardless of CI status.)

This is an automated check - no AI was used to generate this comment.

[enyst]

I am an AI agent posting on behalf of Engel.

Requesting changes before this is suitable for the global extensions registry:

• Scope and cleanup: .pr/ cleanup is repository-specific. Keep this skill repo-local until the cleanup and hosting contract is portable, and require a manual fallback when the workflow is absent or does not cover forks.
• Branch and filesystem safety: start from a clean checkout, verify HEAD equals the PR headRefOid, reject symlinks at .pr/ and the output file, then push explicitly to the verified head repository and branch.
• Evidence links: use the base repository at the merge-base SHA for before/deleted code, and the head repository at the verified head SHA for after code.
• Preview safety: use htmlpreview only for public repositories. Private/internal docs must stay local or access-controlled, contain no external active content, and context-escape attributes plus URL-encode dynamic path segments.
• Presentation correctness: make SVG edge styling match the legend and follow the repository's plain-hyphen guidance.

Corrected repo-local replacements:

• OpenHands/OpenHands#17221
• OpenHands/software-agent-sdk#4921
• OpenHands/automation#431