AK Render
AK Render compiles a YAML or JSON Page Spec into one deterministic,
self-contained HTML file. The page opens from file:// and makes no network
request. You describe what the page says; the compiler owns layout, colour,
typography, accessibility and security.
This plugin pins @bestagentkits/render@0.3.0. Everything below works with
that version; don't use commands that it does not list in --help.
Tools
When the ak-render MCP tools are available (catalog, search-catalog,
describe, recipes, recipe, validate, render, themes), use them.
spec may be YAML or JSON text. render writes the HTML to out and returns
only a summary.
Otherwise use the CLI with the same pinned version. Every command except
mcp accepts --json, and none of them prompts:
npx -y @bestagentkits/render@0.3.0 --version
If npx is missing or Node is older than 20.11, stop and tell the user to
install Node.js 20.11 or later. Don't fall back to hand-written HTML.
The loop: brief → spec → validate → render → inspect
Pick a starting point. For a report, dashboard or architecture review,
start from a recipe or from a bundled example and replace its content:
| Brief |
Recipe |
Bundled example |
| Report, recap, postmortem |
research-report, incident-report, release-recap |
examples/report.yaml |
| KPI or service dashboard |
dashboard |
examples/dashboard.yaml |
| Architecture or design review |
architecture-review, decision-memo |
examples/architecture.yaml |
npx -y @bestagentkits/render@0.3.0 recipes
npx -y @bestagentkits/render@0.3.0 recipe dashboard > page.yaml
The examples sit in the examples/ folder next to this file. Their numbers
are fictional sample data, so replace every value.
Find and describe only the blocks you need.
npx -y @bestagentkits/render@0.3.0 search-catalog sortable table
npx -y @bestagentkits/render@0.3.0 describe kpi chart data-table --compact
Write the spec to a .yaml file. Every number, date, name and finding
must come from the conversation, the repository or tool output. If a value
is unknown, leave the block out or ask; never fill it with a guess.
Validate and fix. Exit code 1 means fix and retry:
npx -y @bestagentkits/render@0.3.0 validate page.yaml --json
The result is { ok, diagnostics[] }. Each diagnostic has a stable code
and a JSON path such as $.blocks[0].titl; for an unknown prop,
details.allowed lists the valid ones. Fix each diagnostic at its path and
validate again until ok is true.
Render to an .html file:
npx -y @bestagentkits/render@0.3.0 page.yaml --out page.html --json
Exit code 1 means the spec is invalid and nothing was written; exit code 2
means a file could not be read or written. Report the message to the user.
Inspect the result. Read the JSON summary, not the HTML: confirm out
is the path you asked for, title is right and warnings is empty (fix the
spec for each warning and render again). Don't read the HTML back into
context. Give the user the file path, and open it once with open (macOS),
xdg-open (Linux) or start (Windows) only if the file did not exist
before this render; otherwise ask them to refresh.
Rules
- No raw HTML, CSS or JS. The spec has no field for them; keys such as
rawHTML, iframe, srcdoc or script are rejected. Don't post-process
the emitted file. Links accept https, http, mailto and relative paths.
- Keep the page offline.
policy.network defaults to deny; only opt in
when the user asks for remote media.
- Choose a theme by name. List them with
themes and set
theme.preset; don't restyle the page.
- Not for generated media. AK Render lays out text, tables, charts and
diagrams from data you already have. It does not create images, video or
audio.
Minimal spec
version: 1
meta:
title: Migration plan
description: How we move the API to the new gateway.
blocks:
- type: hero
eyebrow: Plan
title: Migration plan
description: Move the public API to the new gateway without downtime.
- type: steps
items:
- title: Mirror traffic
text: Send a copy of production requests to the new gateway.
- title: Switch reads
text: Route read endpoints once error rates match.
1---2name: ak-render-23description: Build a polished offline HTML report, dashboard or architecture review page with AK Render. Write a short YAML Page Spec, validate it, and compile it to one self-contained HTML file instead of hand-writing HTML, CSS or JavaScript. Use when the user asks for an HTML report, a status or incident report, a KPI dashboard, an architecture or design review page, or a shareable page that presents results already in the conversation. Needs Node.js 20.11+ on the machine running Claude; not for images, video, audio or slide decks.4metadata:5 source: https://skillmd.com/skills/bestagentkits/ak-render-26---78# AK Render910AK Render compiles a YAML or JSON **Page Spec** into one deterministic,11self-contained HTML file. The page opens from `file://` and makes no network12request. You describe what the page says; the compiler owns layout, colour,13typography, accessibility and security.1415This plugin pins `@bestagentkits/render@0.3.0`. Everything below works with16that version; don't use commands that it does not list in `--help`.1718## Tools1920When the `ak-render` MCP tools are available (`catalog`, `search-catalog`,21`describe`, `recipes`, `recipe`, `validate`, `render`, `themes`), use them.22`spec` may be YAML or JSON text. `render` writes the HTML to `out` and returns23only a summary.2425Otherwise use the CLI with the same pinned version. Every command except26`mcp` accepts `--json`, and none of them prompts:2728```bash29npx -y @bestagentkits/render@0.3.0 --version30```3132If `npx` is missing or Node is older than 20.11, stop and tell the user to33install Node.js 20.11 or later. Don't fall back to hand-written HTML.3435## The loop: brief → spec → validate → render → inspect36371. **Pick a starting point.** For a report, dashboard or architecture review,38 start from a recipe or from a bundled example and replace its content:3940 | Brief | Recipe | Bundled example |41 | --- | --- | --- |42 | Report, recap, postmortem | `research-report`, `incident-report`, `release-recap` | `examples/report.yaml` |43 | KPI or service dashboard | `dashboard` | `examples/dashboard.yaml` |44 | Architecture or design review | `architecture-review`, `decision-memo` | `examples/architecture.yaml` |4546 ```bash47 npx -y @bestagentkits/render@0.3.0 recipes48 npx -y @bestagentkits/render@0.3.0 recipe dashboard > page.yaml49 ```5051 The examples sit in the `examples/` folder next to this file. Their numbers52 are fictional sample data, so replace every value.53542. **Find and describe only the blocks you need.**5556 ```bash57 npx -y @bestagentkits/render@0.3.0 search-catalog sortable table58 npx -y @bestagentkits/render@0.3.0 describe kpi chart data-table --compact59 ```60613. **Write the spec** to a `.yaml` file. Every number, date, name and finding62 must come from the conversation, the repository or tool output. If a value63 is unknown, leave the block out or ask; never fill it with a guess.64654. **Validate and fix.** Exit code 1 means fix and retry:6667 ```bash68 npx -y @bestagentkits/render@0.3.0 validate page.yaml --json69 ```7071 The result is `{ ok, diagnostics[] }`. Each diagnostic has a stable `code`72 and a JSON `path` such as `$.blocks[0].titl`; for an unknown prop,73 `details.allowed` lists the valid ones. Fix each diagnostic at its path and74 validate again until `ok` is `true`.75765. **Render** to an `.html` file:7778 ```bash79 npx -y @bestagentkits/render@0.3.0 page.yaml --out page.html --json80 ```8182 Exit code 1 means the spec is invalid and nothing was written; exit code 283 means a file could not be read or written. Report the message to the user.84856. **Inspect the result.** Read the JSON summary, not the HTML: confirm `out`86 is the path you asked for, `title` is right and `warnings` is empty (fix the87 spec for each warning and render again). Don't read the HTML back into88 context. Give the user the file path, and open it once with `open` (macOS),89 `xdg-open` (Linux) or `start` (Windows) only if the file did not exist90 before this render; otherwise ask them to refresh.9192## Rules9394- **No raw HTML, CSS or JS.** The spec has no field for them; keys such as95 `rawHTML`, `iframe`, `srcdoc` or `script` are rejected. Don't post-process96 the emitted file. Links accept `https`, `http`, `mailto` and relative paths.97- **Keep the page offline.** `policy.network` defaults to `deny`; only opt in98 when the user asks for remote media.99- **Choose a theme by name.** List them with `themes` and set100 `theme.preset`; don't restyle the page.101- **Not for generated media.** AK Render lays out text, tables, charts and102 diagrams from data you already have. It does not create images, video or103 audio.104105## Minimal spec106107```yaml108version: 1109meta:110 title: Migration plan111 description: How we move the API to the new gateway.112blocks:113 - type: hero114 eyebrow: Plan115 title: Migration plan116 description: Move the public API to the new gateway without downtime.117 - type: steps118 items:119 - title: Mirror traffic120 text: Send a copy of production requests to the new gateway.121 - title: Switch reads122 text: Route read endpoints once error rates match.123```