Conciseness

The body is dense and teaches only what Claude cannot know — the Giotto JSON DSL and repo-specific workflow — assuming competence elsewhere ("the quoted <<'DOC' heredoc passes the JSON through untouched" is one brief justifying clause, not a tutorial). The 36-line JSON example is the core teaching device but a slightly trimmed version plus the pointer to the 13 example figures could save tokens, so it is not 'every token earns its place'.

Actionability

Guidance is fully executable and copy-paste ready: a complete working diagram JSON, "npx giotto export - path/to/out.svg <<'DOC'", "npx giotto spec out.svg", "python3 -m http.server 8777", the raw GitHub URL pattern, and the exact MDX snippet for the docs-site variant. Common cases, including the static/dark export, are all covered with concrete commands.

Workflow Clarity

The four steps (write → render → look → place) are clearly sequenced with an explicit mandatory validation step ("Look at it before you ship it — Always", with a two-screenshot loop to catch later beats) and error-recovery feedback ("warnings print on stderr: fix them"; a broken element reference "is an error: the export fails and writes nothing"). The operation is non-destructive, so the batch/destructive cap does not apply.

Progressive Disclosure

Sections are well organized and numbered, and external references (the FORMAT text in node_modules/giotto/lib/edit.js and the 13 figures in hindsight-docs/figures/) are clearly signaled and one level deep. However, the ~40-line inline format specification is the kind of reference material that could live in a separate bundle file, leaving a minor organization gap — there is no bundle to split into, so this is 'good structure' rather than optimal splitting.

Specificity

The description gives concrete specifics around the core action — "Draw an animated figure (boxes, arrows, moving data) as one self-contained SVG for a GitHub README, PR, issue or blog post" — naming the artifact, its parts, and exact destinations. It falls short of the 5 anchor because it describes one draw action rather than multiple distinct concrete actions.

Completeness

Both what and when are explicitly answered: the what is "one self-contained SVG" with named element types, and the when is an explicit "Use when" clause with concrete trigger scenarios ("how a request flows, what a background job does, what a feature changed") and user phrasings ("diagram, figure, animation or 'show it visually'").

Trigger Term Quality

Natural trigger phrases are well covered: "diagram", "figure", "animation", "show it visually", plus context terms (README, PR, issue, blog post). A few natural synonyms a user might say (chart, SVG, drawing, visualize) are missing, matching the 'good keyword coverage; a few natural terms missing' anchor rather than comprehensive coverage.

Distinctiveness Conflict Risk

The niche is clear and distinct — an animated SVG figure for markdown contexts — and it even disambiguates from the docs site's interactive player. Trigger words like "diagram" or "figure" could still overlap with charting or drawing skills, so minor overlap risk remains.