Build Walkthrough
Readout
Skill Build
How the readout skill came to be: an MDX-authored successor to the artifact skill whose documents are published to readout.ssscribe.app, where teammates leave anchored comments the agent reads back into the session.
01What it is
Artifact v2, rebuilt around sharing instead of local files.
- The agent writes
<slug>.mdxwith JSX components instead of raw HTML — less boilerplate, deterministic structure. - A compile step renders the exact class vocabulary the four v1 themes (dossier, editorial, terminal, brutalist) already style.
- Publishing rsyncs the compiled site to a PocketBase instance that serves it and stores comments + version history on the same origin.
- Reviewers comment on any block via hover pins;
read-comments.mjspulls the threads back into a Claude session.
02Architecture
One PocketBase does three jobs: static host, comments API, version store.
flowchart LR A[agent writes slug.mdx] --> B[compile.mjs MDX to themed HTML] B --> C[publish.mjs] C -->|rsync| D[PocketBase pb_public readout.ssscribe.app] C -->|POST version + mdx| E[(readout_versions)] F[reviewer browser] -->|anchored pins| G[(readout_comments)] G -->|read-comments.mjs| A
Comments need no keys or injected config — the widget talks to its own origin and no-ops when the page is opened from disk.
Anchors are compile-time (data-anchor per section/block), so threads survive republishing as long as section titles are stable.
Comment posting is public-with-the-link; field length limits and superuser-only deletes are the whole moderation story for now.
03What replaced what
v1 conventions carried over where they earned it; the rest moved server-side.
| v1 (artifact) | v2 (readout) |
|---|---|
| hand-written HTML with class vocabulary | MDX + JSX components, compiled |
| local git repo as version history | readout_versions collection (full MDX snapshot per publish) |
| file:// as a design constraint | server-first; local open still works incidentally |
| share by sending a file | share a URL; comments come back to the agent |
04Try the comments
This section exists so you can test the loop.
Hover any block on this page and click the pin. Leave a comment — then in a
Claude session run the reader and it will show up, anchored to this section as
s-try-the-comments.
node ~/.claude/skills/readout/scripts/read-comments.mjs claude-skills/readout-skill-build