Render

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

Modes

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 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 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, and every mode carries them. Reach for 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.
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.
• Two modes carry no verdict controls, explain and map. They still carry anchored comments, which is usually the only feedback those pages need.