From rich-docs
Creates or updates rich single-file HTML planning docs (tabs, mermaid, file-change tree, comment threads). Use when 'planning doc', 'rich doc', 'html plan', 'render the plan as html', or when given a DOC COMMENTS block to merge. Not for markdown task docs (use new-task/new-solution/new-plan).
How this skill is triggered — by the user, by Claude, or both
Slash command
/rich-docs:planning-docThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Produce a single self-contained HTML file that renders a plan or design as an
Produce a single self-contained HTML file that renders a plan or design as an interactive document: tabbed pages, mermaid diagrams, a file-change tree, a clickable phase stepper, and inline review threads. The goal is a doc a human can absorb in minutes instead of reading pages of text — while the raw HTML stays lean and semantic enough for an agent to re-read and edit cheaply.
The doc uses the pd-* web component library, loaded from a CDN. You do not
write any CSS or JavaScript — you write semantic markup; the components do the
rendering.
The component library is versioned with this skill. Fetch the reference for the exact release this skill targets — an immutable tag, so it never drifts or serves a stale cache:
curl -fsSL https://cdn.jsdelivr.net/gh/mistakenot/[email protected]/pd-components/dist/llms.txt
It contains the page boilerplate, the release tag to pin, every component with
attributes and examples, the authoring rules, and the comment-merge protocol.
Follow it exactly — in particular, import the bundle pinned to the release tag
it names (pd-v0.6.0), never @main. To move to a newer component
release, update this skill (npx skills install …) — the new tag rides along.
If the fetch fails (offline/sandboxed): inside the skills repo itself, read
pd-components/dist/llms.txt; elsewhere, fall back to the cheat sheet at the
bottom of this skill and flag to the user that the reference may be stale.
<pd-tab> per concern
(e.g. Overview / Solution / Plan / Wireframe); small docs skip tabs and put
sections directly in <pd-doc>. Mind the tab roles: Solution is the end
state (human-reviewed — file tree, API outlines, final snippets live
here); Plan is the recipe (agent-consumed — keep it self-sufficient).<pd-stepper> (set each phase's files so the file tree highlights);
file changes belong in <pd-files>; flows and architectures belong in
<pd-mermaid>; acceptance criteria in <pd-ac> with traceability chips.
Use only the mermaid diagram types llms.txt lists as supported.<topic>.html where the user keeps planning artifacts (for task
workflows: the task folder's artifacts/; otherwise ask or use docs/).
Tell the user to open it in a browser; it works from file:// directly.Authoring rules that matter most (full set in llms.txt):
pd-* elements and stable kebab-case section ids, not in styled
divs. Tailwind utility classes are welcome ONLY inside wireframe/freeform
content.<pd-decisions>).<pd-decision> (rationale +
alternatives + consequences), not buried in prose. It feeds <pd-decisions>
alongside resolved threads.<script type="application/json" id="pd-meta"> blocks when editing
existing docs. Never modify, move, or delete the pd-meta block — it tracks
task lifecycle state managed by the planning workflow.When the user asks for changes, edit the HTML in place — do not regenerate the whole file (that would orphan threads and churn the diff). Keep section ids stable so existing threads and deep links keep pointing at the right content.
Reviewers comment in the browser and paste back an export block delimited by
=== DOC COMMENTS / === END DOC COMMENTS ===. When you receive one:
REPLY to thread "X" → append <pd-comment by="review"> with the text to
that thread. If you can address it, do so, append your <pd-comment by="author"> explaining what changed, and set the thread's
status="resolved" (or "rejected" with reasoning).NEW <priority> comment on "X" (anchor: id) → insert a new
<pd-thread anchor="<id>" priority="<priority>" title="<short summary you write>"> directly after the anchored element, containing the comment.Classic scripts in head (never type="module"):
https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4 and
https://cdn.jsdelivr.net/gh/mistakenot/[email protected]/pd-components/dist/pd.min.js (defer).
<pd-doc title status pr generated> shell · <pd-tab name> page
pr: "pending" → placeholder; a URL → clickable badge. Update when PR opens.<pd-section id title> titled/anchorable section, freeform body<pd-thread anchor status{unresolved|resolved|rejected} priority{p1|p2|p3} title>
with <pd-comment by{review|author|name}> children — append-only<pd-files> + <pd-file path change{add|edit|delete}>note</pd-file><pd-stepper> + <pd-phase n title files status{done|active|todo}><pd-mermaid caption> source as text content; flowchart/graph, sequence,
state, class, ER, xychart only<pd-code lang path lines highlight caption> highlighted snippet (code as
text content; use a nested <script type="text/plain"> if it contains <>&)<pd-api kind name lang path> + <pd-member kind sig>note</pd-member> —
API/outline: signatures + comments only, generic kind badges<pd-ac id title phases tests> acceptance-criteria card<pd-decision id title status{accepted|proposed|superseded} by summary> authored ADR block<pd-decisions> auto decision log · <pd-wire label h> / <pd-note> wireframesProvides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.
npx claudepluginhub mistakenot/skills --plugin rich-docs