Immutable. This exact content is served forever at /api/v1/blob/b66e099bbf690995.
--- name: render description: Turn a plan, PRD, review, audit, comparison, brainstorm, explanation or architecture map into an interactive HTML page the user marks up in place, then read their marks back and act on them. Every section carries an anchored comment affordance, so feedback returns bound to the exact thing it was left on. Use for "render this as a page", "make this visual", "I want to review this properly", "turn this plan into something I can comment on", or to wrap another skill's output (`render /review-code`). Not for generating a Mermaid diagram into docs/ (use docs-diagram), not for designing a UI for a product being built (use product-design-spec), and not for simplifying prose the user did not understand (use wtf). metadata: author: mgiovani version: 1.0.0 disable-model-invocation: true argument-hint: <mode|/skill|path> [subject] allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Task, Skill, Artifact --- # Render Build a page the user can work, not a document they have to scroll. Long findings lists, requirement inventories, option matrices and step plans all lose their shape as linear markdown. This skill gives them one, and gives the user a way to answer back that survives the round trip. ## Invocation forms | Form | Behavior | |------|----------| | `render <mode> [subject]` | Build that mode's page for the subject | | `render /<skill> [args]` | Run the wrapped skill, then render its output in the matching mode | | `render <path>` | Read an existing file and convert it to its matching mode | | `render` | Show the mode table and ask which one; never pick one silently | ## Modes | Mode | The page is | Per-item verdicts | |------|-------------|-------------------| | `prd` | Requirements grouped by family, the evidence behind each | keep / change / drop | | `plan` | Ordered steps, their dependencies, the files each touches | approve / rework / cut | | `review` | Findings by severity and file, with the code excerpt | fix / won't fix / discuss | | `audit` | Whole-repo findings, filterable by area and severity | same triage as review | | `compare` | Options against weighted criteria, evidence per cell | pick a winner | | `brainstorm` | Idea cards, the tension each one resolves, by theme | shortlist / park / drop | | `explain` | The one-line answer, the mechanism, then detail on demand | none, comments only | | `map` | Module graph, data flow, entry points | none, comments only | Each mode's contents are specified in `references/<mode>.md`. Load only the one you need, and load it after the mode is settled. ## Workflow ### 1. Resolve the mode From the first argument: - A mode name: use it. - A skill name with a leading slash: run that skill first, then map its output to a mode using the table in `references/wrapping.md`. - A file path: read the file, then pick the mode its content matches. State which mode you picked and why, in one line, before building. - Nothing: print the mode table above and ask. Do not guess. ### 2. Gather the real content The page renders what the run actually produced. Never invent an item to fill a grid, never write placeholder copy, never carry an example from a reference file into a real page. If a section would be empty, the page says it is empty and why. A wrapped skill supplies its own output, and a file supplies its contents. With a bare mode, do the work the mode implies before rendering: `render review` on a diff runs the review first. ### 3. Load the design guidance Announce `Using artifact-design to calibrate this page's treatment` and load the `artifact-design` skill before writing any HTML, via the `Skill` tool where one exists. If the page will declare a runtime capability, load `artifact-capabilities` the same way. Both are host skills rather than siblings in this repository, so they are absent on some agents. Where neither can be loaded, say so in one line and apply [references/page-kit.md](references/page-kit.md) directly: it carries the theming rules, the type and layout floor, and the state contract this skill depends on. The page is still built; it just loses the calibration pass. ### 4. Build the page [references/page-kit.md](references/page-kit.md) holds the document skeleton and the state block, plus how a page is written and published. Anchors and the comment affordance are specified in [references/feedback-loop.md](references/feedback-loop.md), and every mode carries them. Reach for [references/diagrams.md](references/diagrams.md) only once the content turns out to have a shape worth drawing. Six rules hold across every mode: 1. **Every page is annotatable.** Anchors and the comment affordance are not a per-mode feature. A page without them cannot return feedback, which is the point of the skill. 2. **Real content only.** See step 2. 3. **Theme-correct in all three states.** Define the light palette as tokens on bare `:root`, redefine those tokens under `@media (prefers-color-scheme: dark)` guarded by `:not([data-theme="light"])`, and redefine them again under `:root[data-theme="dark"]`. Give `body` an explicit token background. A color whose only definition sits inside a media block renders one theme's text on the other theme's background. 4. **The page is greyscale.** Color is spent only on the verdict vocabulary, where it distinguishes marked items at a glance. Selected and pressed states are an ink fill, not a hue; there is no brand accent, no colored heading or filter, and no colored diagram. See the Color section of [references/page-kit.md](references/page-kit.md). 5. **Diagrams are inline SVG built from the page's own tokens.** Mermaid brings its own theme and fights the three-state setup above. 6. **State drives the DOM, never the reverse.** The page renders from its embedded state object. Saving serializes that object, never the live DOM. ### 5. Deliver and report Report the output path, the published link if there is one, and whatever count matters for this mode. Then say how to answer back: marks and comments are both kept by the page, so the user presses save and tells you. Keep this to two lines. ### 6. Read the marks back When the user says they have marked it, read the page back per `references/feedback-loop.md`, then act on what it returns. Group your response by what they decided, not by page order, and name any comment whose anchor no longer resolves rather than dropping it. ## Worked examples **Bare mode** (`render compare postgres vs sqlite for the vault store`): gather the real criteria from the project's own constraints and build the matrix with evidence behind every cell. Publish it, report the link, and wait. The user picks a winner on the page; you read it back and write the decision up. **Wrapping a skill** (`render /review-security`): run `review-security` to completion first. Its output is a severity-ranked list with file:line evidence, which maps to `review` mode. Build the triage board from the findings it actually produced, one anchor per finding. **Converting a file** (`render docs/plans/auth.md`): read it first. It turns out to be an ordered step list with dependencies, so say "rendering as `plan` mode" before building. Do not rewrite the plan's content while converting it. **No argument** (`render`): print the mode table and ask which mode. Build nothing until that is answered. ## Notes - The wrapped skill never needs to know this skill exists. `render /<skill>` runs it unchanged and renders what comes out. - Re-running `render` on the same subject updates the same page when the output path matches. This is the intended way to revise, and preserving the reader's marks across it is a required step, not a side effect: read the existing state block and embed it in the new page, per the re-render rules in [references/feedback-loop.md](references/feedback-loop.md). - Two modes carry no verdict controls, `explain` and `map`. They still carry anchored comments, which is usually the only feedback those pages need.