i inkling How inkling works

Skill reference

From markdown intent to interactive HTML.

A walkthrough of the /doc skill: the four pillars, how the pipeline runs, what it writes, what it computes, and when to reach for it.

Three moves, every time.

/doc turns a messy markdown source into a self-contained HTML folder. It is one skill doing three jobs in sequence — and the second job is the most important and the easiest to skip.

Reads intent

Any markdown file you point it at, plus its own knowledge of vision-shaped, HLD-shaped, LLD-shaped, and learning-shaped docs.

Designs the doc

Not "which template fits." Which behaviors does this doc want? Which diagrams? Which computations? Which interactions? The agent answers per doc.

Composes & emits

Reaches into the starter visual vocabulary for the easy parts, invents computational behaviors for everything else, writes a 4-file folder.

The folder is the artifact. Each one stands alone — your 2026 doc reads the same in 2030 because the CSS and JS are pinned next to it at render time.

Interactive · Computational · Aesthetic · Warm.

Premise 4 of the design doc. All four, together, no subset. A doc that lands only three is a regression — record what is missing and fix it before declaring done.

Pillar 01 · Interactive

The doc reacts.

Click-to-explain, decision walkthroughs, drawers, glossary popovers, scroll-spy, focus mode. The reader does things; the doc responds.

Pillar 02 · Computational

The doc computes.

Parses inline CSV/JSON and renders charts. Walks decision trees from source data. Highlights jargon dynamically. The doc does math, not just describes it.

Pillar 03 · Aesthetic

Typography and restraint.

Layout discipline, visual hierarchy, paper tones, serif display. The warm-notebook palette handles this for free on prose-heavy parts; computational sections must be designed to fit it.

Pillar 04 · Warm

Calm and archive-worthy.

Serious, inviting to reopen, no chrome-junk. The kind of doc you read in a comfortable chair, not the kind you tab through and close.

This doc's pillar audit.

Computed from the doc you are reading right now. Bars are rendered live by runtime.js parsing the inline CSV next to this SVG — the chart you see is also a demonstration of the Computational pillar.

Live chart

Source: this doc's doc-source.json pillar audit · scale 0–10 · 2026-05-14.

From source to folder.

Click each stage. The whole pipeline is one shot of agent reasoning. There is no build step, no compile pass. The agent is the renderer — and the behavior author.

Interactive diagram

Read source

Load the markdown file. The H1 is the doc title. Every ## becomes a top-level section. Every ### is usually a card or a list item. Scan for numeric data, jargon, references to other docs, structures that want exposing.

What lands in the folder.

Each rendered doc folder is exactly four files. Portable — copy it to a USB stick, an email attachment, a different machine, and it still works.

index.html

Semantic HTML body. Topbar, hero, sections, footer. Loads style.css and runtime.js from the same folder. Uses contenteditable on title, lede, thesis, and pullquote for in-browser typo fixes.

Body
style.css

Warm-notebook stylesheet plus this render's per-doc extensions. Pinned at render time. Future kit updates do not touch it. That is archive permanence.

Style
runtime.js

UI chrome plus behavioral primitives: parseCsv, renderBarChart, clickToExplain, glossary. Per-doc primitives appended at render time and pinned.

Runtime
doc-source.json

Provenance manifest. Source path, source SHA-256, theme, components used, behaviors used, behaviors invented, pillar audit scores, folded sections, agent decisions, judgment notes.

Manifest

Cheap defaults for prose-heavy parts.

The warm-notebook stylesheet ships eleven pre-styled patterns. They handle the Aesthetic + Warm pillars for prose-heavy sections cheaply. Use them only when the section is genuinely prose-shaped; don't force a behavioral section into one of these molds.

  • Hero — title, lede, and a thesis card with metadata.
  • Eyebrow — small mono label above section titles.
  • Pullquote — one sentence that re-states the thesis. Sparingly.
  • Note grid — 2-4 short comparison cards.
  • Principles — numbered cards for named principles.
  • Doc-types list — name + one-line summary + pill.
  • Flow — 3-6 step interactive workflow diagram.
  • Callout — clay tone for decisions, sage tone for non-goals.
  • Decision list — Q/A with details/summary.
  • Roadmap — 3-column phase grid (V0/V1/V2 style).
  • Clean list — plain ul for flat bullets.

The heart of the kit.

These are not pre-built templates. Each doc invents what it needs, drawing from runtime.js primitives plus per-doc inline code plus per-doc CSS extensions. Every render should include at least one. The starter vocabulary handles aesthetics; this list handles the Interactive + Computational pillars.

  • Chart. Parse inline CSV/JSON, render bar/line/scatter as SVG. Reach for it when the doc references numeric data — like the live audit chart above.
  • Architecture diagram. Clickable SVG or HTML diagram; clicking a node opens an explanation panel. Reach for it when the doc has system structure to explain.
  • Decision walk. Branching tree; user clicks through choices. Reach for it when the doc walks a "should I do X" thinking process.
  • Timeline. Dated events on a horizontal axis, click to expand. Reach for it when chronology matters.
  • Comparison. Multi-axis side-by-side with swappable items. Reach for it when comparing options or approaches.
  • Glossary. Underline defined terms; click reveals definition popover. Try clicking any underlined term in this doc — that is the glossary behavior running live.
  • Quiz. Recall prompts that reveal on click. Reach for it in learning notes.
  • Drawer. Progressive disclosure for optional depth. Reach for it for appendix-shaped content.
  • Runnable code. Inline JS that runs in the page where safe. Reach for it when explaining an algorithm or showing live output.
  • Invent. Whatever the doc earns. Default mode — every doc adds at least one new behavior.
How invention works in V0

When a doc needs a primitive not yet in runtime.js, the agent adds it during this render and pins the resulting runtime.js into the folder. The primitive lives forever with the doc that needed it. After it appears in 2+ docs, V1 graduates it into a shared doc-kit/.

Reach for it when the doc will be re-read.

Reach for /doc for
  • Vision docs — beliefs, goals, non-goals.
  • HLDs — system overview, components, data flow.
  • LLDs — APIs, schemas, edge cases, test plans.
  • Learning notes — concept maps, mental models.
  • Decision records — named decisions and reasoning.
  • Anything with structure that markdown flattens.
Leave it markdown for
  • A three-line note.
  • A scratch TODO list.
  • READMEs and contributing guides in a larger ecosystem.
  • Anything you will only read once.
If you will re-open it, render it. If not, leave it markdown.

What V0 deliberately does not do yet.

The current version is intentionally thin. Approach D — the full Living Doc Kit — is what V0 grows into, not what it ships as.

No shared doc-kit/ package

Components and behaviors are inlined per doc in V0. V1 extracts a pattern into doc-kit/ only after it recurs in 2+ docs. V1 picks the variant that actually worked, not the one that was planned.

No taste.json

A learned model of your preferences across docs. V2. For now, taste lives in the SKILL.md prompt and your feedback per render.

No archive index (docs/index.html)

A browseable map of every doc you have rendered. V1. Today the archive is just folders on disk under docs/.

No cross-doc memory

Doc N referencing decisions made in docs 1..N-1. V2. Cross-doc visual cohesion in V0 comes from the shared warm-notebook theme and the stable brand mark.

No /doc revise <slug>

Re-render an existing doc from its source while keeping the slug stable. V1. In V0 you re-run /doc render and overwrite the folder — which is exactly how this doc got course-corrected.

No two-way revise

Edit the HTML and have changes flow back to the markdown source. V2 research stretch. The one-way contract — markdown is the seed, HTML is the artifact — is sufficient through V1.

What V0 originally got wrong

The first draft narrowed the kit into a fixed menu of 11 visual templates, framed as "pick one per ## section." That reversed premise 3 ("computational behaviors, not doc types") and the original premise 4 ("Warm AND computational"). The course-correction made computational behaviors first-class, made "invent" the default mode, and refined premise 4 into four co-equal pillars. This rendered doc is the dogfood proof.

Three layers. One exists today.

Layer 1 — Renderer Agent

Shipped

  • The inkling skill at ~/.claude/skills/inkling/SKILL.md.
  • Reads markdown intent, designs what the doc needs, writes 4-file folders.
  • Components and behaviors inlined per doc; warm-notebook theme baseline.

Layer 2 — Doc Kit

V1

  • Shared doc-kit/components/ with versioned patterns.
  • Themes folder (warm-notebook, plus earned alternates).
  • Prompts per component, refined as docs accumulate.

Layer 3 — Doc Archive

V1+

  • Browseable map: docs/index.html.
  • Machine-readable manifest: docs/index.json.
  • Cross-doc memory loaded per render (V2).
The agent owns all three layers

You stay in the writing lane forever. The kit, the archive, and the renderer are all agent-maintained.

Try it on your next doc.

Three ways to invoke. Pick whichever feels natural — the agent figures out the rest.

  • Simple. Render path/to/idea.md through /doc.
  • With a doc-type hint. /doc render path/to/idea.md as HLD.
  • Conversational. Turn this markdown into an HTML doc.
Where the output lands

<source-dir>/docs/<YYYY-MM-DD>-<slug>/. The agent prints the exact open command when the render is done — and self-audits the four pillars before declaring done.