Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add skills/avinava/document-design-system/writing-documentsnpx skills add Avinava/document-design-system --skill writing-documentsgit clone --depth 1 https://github.com/Avinava/document-design-systemWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/avinava/document-design-system/writing-documents)<a href="https://agentmods.dev/skills/avinava/document-design-system/writing-documents"><img src="https://agentmods.dev/badge/skills/avinava/document-design-system/writing-documents.svg" alt="Measured on agentmods" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.00164 | $0.02426 |
| Opus 5 | $0.00082 | $0.01213 |
| Sonnet 5 | $0.00033 | $0.00485 |
| Haiku 4.5 | $0.00016 | $0.00243 |
Grade A, and why
writing-documents scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 3d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 180 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Writing Documents
A technical document exists to get a reader to a decision, or to a working understanding, without them having to reconstruct the author's thinking.
The failure mode is not ugliness. It is a document that is complete, accurate, and unreadable — where the reader cannot find the decision, cannot tell what is settled versus proposed, and cannot see what changed since they last read it.
This skill is two layers. Do not glue them together.
- Writing (default) — pick the type, load its shape, write from evidence. Output is Markdown in the user's tree.
- Design system (opt-in) — tokens, themes, print, self-contained HTML. Load
core/only when the user asked for HTML, PDF, print, a designed page, or "use the design system".
Format first
format = markdown, unless the user asked for html, pdf, print, designed, themed, or "use the design system".
| Format | Load | Do not load |
|---|---|---|
markdown |
this file, the type file, references/writing.md, references/evidence.md |
core/, themes, templates/longform.html, print.css, build_document.py |
html / pdf |
the above plus references/output.md and core/ |
— |
both |
Markdown first (canonical in-repo), then HTML from that source | — |
Full dial, conventional paths, and HTML assembly: references/output.md.
On the Markdown path, leave Mermaid as fenced blocks. Prerender to themed SVG only on the HTML path.
State the assumption in one line. Do not quiz.
Writing
docs/adr/adr-014.mdas typeadr(markdown). Designed HTML on request.
Ask only when the slug is actually ambiguous, the request conflicts with another skill, or they asked for HTML and no theme is set (field-notes is the default).
Never offer a designed HTML version unprompted.
Pick the type
Load references/type-index.md if the slug is unclear. Then load one references/type-<slug>.md before writing.
| Slug | Reader's question | Shape |
|---|---|---|
design-doc |
Should we do this, and is the approach sound? | Context → Problem → Goals / non-goals → Design → Alternatives → Cross-cutting → Risks → Rollout → Open questions |
adr |
Why is it like this? | Status → Context → Decision → Consequences. One decision, immutable once accepted |
spec |
What exactly must I build, and how do I know I am done? | Scope → Definitions → Normative requirements → Examples → Compliance |
api-contract |
How do I call this correctly, and what happens when I do it wrong? | Companion to OAS/RAML, not a second copy of the spec |
architecture |
How is it arranged today? | Living current-state (C4 context/container), not a change proposal |
handoff |
What do I run, change, and not break after you leave? | Status, how to run, in-flight work, tripwires |
design-handoff |
What do I build, in every state? | Screens, states, components, acceptance criteria |
discovery |
What did we learn, and should we proceed? | Evidence, opportunities, go / stop / reframe |
test-report |
Can we ship, on this build? | Verdict first; counts with denominators |
postmortem |
What happened, why, and what stops it recurring? | Summary → Impact → Timeline → Root cause → Action items. Blameless |
proposal |
Should I approve this? | The ask → Rationale → Cost → Alternatives → Decision needed |
runbook |
What do I do right now? | Preconditions → Steps → Verification → Rollback → Escalation |
onboarding |
How do I get it running and prove it works? | Prerequisites, commands from CI, one validation |
tutorial |
Can I learn this by doing it once? | Diátaxis lesson — one successful path |
how-to |
How do I get this job done? | Diátaxis recipe for a competent user |
reference |
What is the exact fact? | Diátaxis lookup — mirrors the product |
explanation |
Why is it like this? | Diátaxis study — context, not a procedure |
mulesoft |
What does this Mule app do? | Suite: README, architecture, and conditional extras |
What ships with it
23 files beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.
- references/evidence.md 2.8 KB
- references/output.md 3.2 KB
- references/suites.md 1.1 KB
- references/type-adr.md 1.8 KB
- references/type-api-contract.md 1.8 KB
- references/type-architecture.md 1.7 KB
- references/type-design-doc.md 2.6 KB
- references/type-design-handoff.md 1.8 KB
- references/type-discovery.md 1.9 KB
- references/type-explanation.md 1.1 KB
- references/type-handoff.md 2.0 KB
- references/type-how-to.md 1.1 KB
- references/type-index.md 2.9 KB
- references/type-mulesoft.md 2.2 KB
- references/type-onboarding.md 1.4 KB
- references/type-postmortem.md 1.8 KB
- references/type-proposal.md 1.6 KB
- references/type-reference.md 1.2 KB
- references/type-runbook.md 1.5 KB
- references/type-spec.md 1.8 KB
- references/type-test-report.md 1.7 KB
- references/type-tutorial.md 1.3 KB
- references/writing.md 3.2 KB
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 3d ago First seen · 180 lines · 164 tokens per session scan A 942bdc3022cf
writing-documents is a skill published in the GitHub repository Avinava/document-design-system (2 stars, last pushed 8d ago), licensed MIT. It adds 164 tokens to every session and 2,426 once invoked, about $0.0008 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.
Other skills, from other repositories
chart-description-writer
Writes a precise, accessible text description of a data visualization — covering the chart type, what it shows, the key finding, and the data range — suitable for publication as a caption, alt-text, or standfirst alongside the chart.
web-design-guidelines
Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
seo
Optimize for search engine visibility and ranking. Use when asked to "improve SEO", "optimize for search", "fix meta tags", "add structured data", "sitemap optimization", or "search engine optimization".
selecting-vizro-charts
Use this skill when choosing chart types, applying Plotly Express conventions, configuring colors, building KPI cards, or adding tables (AG Grid) to Vizro dashboards. Activate when the user asks which chart fits their data, needs custom chart functions, wants to set colors or palettes, is creating KPI metric cards, or…
release
Cut a sim-use release end-to-end. Use when the user runs /release or asks to "ship a release", "publish a version", "cut a release", or "release to homebrew". Drives scripts/local-release.sh; never reimplement its build/sign/tarball logic.
code-review
Review Semiotic pull requests for behavioral bugs, regressions, contract drift, and missing evidence. Use for GitHub Copilot code review of TypeScript/React charts, Stream Frames, canvas and browser interactions, SSR, public exports, docs/examples, AI schemas and tooling, generated contracts, tests, CI baselines, and…