Doc Author
Write internal documentation with consistent structure, style, and Diataxis classification.
Installation
- Make sure Claude is on your device and in your terminal.
Skills load from
~/.claude/skills/when Claude Code starts up β so you need it on your machine first. If you don't have it yet, install it once with the command below, then runclaudein any terminal to verify.One-time setupnpm i -g @anthropic-ai/claude-codeAlready have it? Skip ahead.
- Paste into Claude Code or into your terminal.
This copies the whole skill folder into
~/.claude/skills/dodaios-doc-author-dodaios/β the SKILL.md plus any scripts, reference docs, or templates the skill ships with. Works for every skill.What this command does
- Makes a new, empty temporary folder.
- Downloads the skill's folder,
dodaios/skills/builtin/dodaios-doc-author, fromgithub.com/Dodaios/Dodaios(branchmain), the GitHub repository it's listed from. You get the version that is there now, not a copy we keep. - Copies that folder to
~/.claude/skills/dodaios-doc-author-dodaios/. - Deletes the temporary folder.
Installing runs none of the skill's files; it only downloads and copies them. When you later use the skill, Claude follows its SKILL.md and may run scripts that come with it. Read them first.
Faster alternative (instruction-only skills)
Skips the clone and grabs only the SKILL.md file. Don't use this if the skill ships Python scripts, reference markdowns, or asset templates β they won't be downloaded and the skill will fail when it tries to load them.
Quick install (SKILL.md only)Sign up to copy - Restart Claude Code.
Quit and reopen Claude Code (or any other agent that loads from
~/.claude/skills/). New skills are picked up on startup. - Just ask Claude.
Skills auto-activate when your request matches the skill's description β no slash command needed. Trigger phrases live in the skill's own frontmatter; you can read them in the βWhat this skill doesβ section above.
Prefer to read the source first? Open on GitHub.
When Claude uses it
Authoritative skill for writing internal Personal-Jarvis docs under ``docs/`` and sibling directories. Enforces a Diataxis-compliant classification (concept/how-to/tutorial/reference/troubleshooting/adr), a uniform YAML frontmatter schema, a style canon (active voice, imperative instructions, English prose), and hard anti-patterns (no quadrant mixing, no filler intros, no "Click here"). Use when writing or fundamentally reworking any Markdown doc under ``docs/``.
What this skill does
Jarvis Doc Author
When a Jarvis doc is written, the rule is: classify first, then structure, then phrase, then self-check. Not the other way around.
This skill provides the scaffolding. It does not replace thinking β it enforces the discipline that separates a pile of internal Markdown files from a real doc layer (role models: Kubernetes doc site, Docker manuals, GitHub Docs).
When to trigger
Activate this skill when the user (via voice or chat) or a Sub-Jarvis explicitly or implicitly wants to write a new doc or structurally rework an existing doc. Concrete examples:
- "Schreib ein Doc ueber den BrainManager-Routing-Discipline-Mechanismus." (Write a doc about the BrainManager routing discipline mechanism.)
- "Leg ein ADR an fuer die Sub-Jarvis-Hard-Cap-Entscheidung." (Create an ADR for the Sub-Jarvis hard-cap decision.)
- "Dokumentiere wie man einen neuen Brain-Provider hinzufuegt." (Document how to add a new brain provider.)
- "Fass die Phase-6-Ergebnisse als Test-Report zusammen." (Summarize the Phase 6 results as a test report.)
- "Mach mir eine How-To fuer das Voice-Bridge-Setup." (Create a how-to for the voice-bridge setup.)
- A Sub-Jarvis receives the task from the main Jarvis "schreib das in
docs/...rein" (write this intodocs/...) β then the Sub-Jarvis consults this skill before writing.
Do NOT trigger on:
- Code comments, docstrings, type hints β those follow the AGENTS.md rule (code identifiers in English), but need no doc scaffold.
- Commit messages and PR descriptions β those are build artifacts.
- Memory entries β the
auto-memoryis responsible for those. - Skill authoring β the
skill-creatorskill exists for that. - Voice-output-filter templates or TTS prompts.
Workflow (5 phases)
1. Classify β which Diataxis quadrant?
Question: what does the reader who later opens this doc want to do or understand? Exactly one quadrant wins:
| Quadrant | When... | Example doc |
|---|---|---|
| concept (explanation) | Reader wants to understand why/what it is | "BrainManager-Routing-Discipline" |
| how-to | Competent reader wants to solve a task | "Adding a new brain provider" |
| tutorial | Learning reader needs a guided tour | "Bringing up Phase-6 Self-Healing from scratch locally" |
| reference | Reader looks for a fact | "EventBus event catalog", "jarvis.toml schema" |
| troubleshooting | Reader has a symptom | "TTS outputs SAPI5 robot voice instead of Cartesia" |
| adr | Architecture decision with consequences | "ADR-0009 Self-Healing-Worker-Critic" |
If unsure between tutorial and how-to: does the reader consult the doc
while working (time pressure, problem in mind) β how-to. Does the reader go through it
away from work to learn β tutorial. (Diataxis test, see
references/diataxis-quadrants.md.)
Hard Rule: A doc serves exactly one quadrant. If the doc threatens
to serve two, split it into two files with a cross-link. Quadrant mixing
is anti-pattern AP-D-1 (see references/templates.md).
2. Determine the path
By quadrant + component. The conventions in the repo (as of 2026-04-28):
| Quadrant | Default path |
|---|---|
| adr | docs/adr/NNNN-slug.md (NNNN = next free 4-digit number) |
| how-to | docs/{component}/howto-{slug}.md |
| concept / explanation | docs/{component}/concept-{slug}.md or docs/{component}/{slug}.md |
| reference | docs/{component}/reference-{slug}.md or docs/reference/{slug}.md |
| tutorial | docs/tutorials/{slug}.md |
| troubleshooting | docs/troubleshooting/{slug}.md or docs/{component}/troubleshooting-{slug}.md |
| Phase test report | docs/phase{N}-{slug}.md (special case, counts as a reference + concept hybrid; an existing convention overrides) |
The slug is always lowercase, kebab-case, English (router-discipline, not Router-Disziplin).
Never rename a slug β cross-links break otherwise.
For an ADR: check in docs/adr/ which number is next free
(ls docs/adr/). Currently ADR-0001 through ADR-0012 are in use; the next free
one is ADR-0013.
3. Fill in the frontmatter schema
Every Jarvis doc carries a YAML frontmatter with 7 mandatory fields:
---
title: "Concept: Router-Discipline" # display title, in quotes
slug: router-discipline # URL-stable, kebab-case, append-only
diataxis: explanation # tutorial|howto|reference|explanation|troubleshooting|adr
status: draft # draft|active|deprecated
owner: harald # who is responsible for correctness
last_reviewed: 2026-04-28 # ISO date YYYY-MM-DD
phase: 5 # master-plan phase: 0|1|1a|1c|2|3|4|5|6|7|L+P|A0..A5|-
---
Optional: tags, related (cross-refs as a list of slugs),
deprecates, deprecated_by, audience (developer/operator/end-user
β default developer for internal docs), next_review_due (computed from
last_reviewed + cadence from config).
Full field definitions + rationale + examples:
references/frontmatter-schema.md.
4. Insert the skeleton + write the content
Load the template for the chosen quadrant from
references/templates.md (all 6 skeletons, copy-paste-ready). Mandatory
and optional sections are marked. Fill in this order:
# H1=titlefrom frontmatter (no emoji, no Markdown in the title).- 1-2-sentence intro directly under H1, before any H2. Answers: what is the doc, who is it for, what does the reader take away? No "Welcome", no "This document describes..." β straight to the point.
- Quadrant-specific mandatory sections (see templates).
- Code blocks ALWAYS with a language tag (
```python,```bash,```toml,```yaml,```json). Never bare triple backticks. ## What's nextas a footer block, max 5 bullets, each with a cross-link to a follow-up doc (relative path, not an absolute URL).
Language rules (excerpt β full set in references/templates.md):
- Active voice + imperative in how-tos and tutorials. "Activate the
voice pipeline with
set JARVIS_VOICE=1" β not passive constructions. - You form β no "the user", no "we" when the reader is meant.
- Code identifiers in English (
BrainManager,jarvis.toml,EventBus), prose in English. Identifiers in backticks, never italics. - Spell out acronyms on first occurrence ("Speech-to-Text (STT)").
- No "obviously" / "simply" / "just" β it humiliates the reader who is struggling and is explicitly forbidden in the Microsoft + Google style guides.
- No "click here" / "see this link" β the link text describes the
target: "see
ADR-0011 Router-Discipline", not "see here".
5. Self-check before saving
Before the file is written, go through the quality checklist from
references/templates.md (15 points). The most critical points:
- Quadrant lock: Does the doc serve exactly one Diataxis quadrant?
- Frontmatter complete: All 7 mandatory fields set?
- Title length β€ 50 characters (max 60, user mandate 2026-04-29): The
frontmatter
titleis the display title in the DocsView sidebar and MUST stay fully readable there. A long explanation belongs in the body H1, not in the sidebar entry. Example: NOT"ADR-0009 β Self-Healing Worker-Critic-Loop with Action/Observation-Invariant"(76 characters), BUT"ADR-0009: Self-Healing Worker-Critic"(37). - Intro before H2: 1-2 sentences, no filler?
- Code language tags: Does every code block have a
languagetag? - Cross-links as relative paths:
docs/adr/0009-self-healing.md, nothttps://github.com/...? - What's next β€ 5 bullets: Does the footer block respect the K8s cap?
- Verification section in how-tos: Concrete pytest command, concrete log marker, concrete Computer-Use step? (Verify-before-ship mandate from AGENTS.md.)
- No TODO/FIXME/TBD in the body when
status: active? If it is a stub:status: draftin the frontmatter and mark it in the body.
When all 9 points are green: write the file. If a confirmation is
needed (risk policy write_doc_file), show the user the path +
frontmatter + first 20 lines of body, ask once, then write.
What the skill deliberately omits
Kept deliberately small β Personal-Jarvis is a single-user project. The following is not the job of this skill:
- Multi-version docs / i18n. All new docs are English (project policy); no translation workflow, no version switch.
- Card sorting / user tests. Single-user; the information architecture follows the maintainer's own intuition.
- Editorial review as a separate step. The self-check replaces that; linters catch 80%.
- Eval framework like
skill-creatorhas. Doc quality is qualitatively measurable; quantitative benchmarks would be overkill. - Auto-migration of all existing docs. Existing files follow different patterns; they are adapted opportunistically on re-review, not in a big bang.
Reference files
The detail definitions live in the sibling files. Read the reference file whose topic is currently being asked about β not all of them on spec.
references/diataxis-quadrants.mdβ deep definition of the 4 quadrants, tutorial-vs-how-to test, reference-vs-explanation test, mapping onto Jarvis modules.references/frontmatter-schema.mdβ all frontmatter fields (mandatory and optional), rationale, examples per doc type, slug rules.references/templates.mdβ complete skeletons for all 6 doc types, style canon (10 rules), anti-pattern catalog (12 points), quality checklist (15 points).
Anti-pattern quick view
Full list in references/templates.md. These are the five that
are broken most often:
- AP-D-1 Quadrant mixing (tutorial with a reference table).
- AP-D-2 Concept doc with code snippets without a clear purpose.
- AP-D-5 How-to without a prerequisites section.
- AP-D-7 Owner field empty (the doc rots).
- AP-D-12 A concept explained twice in different places (drift guaranteed β one place explains, all others link).
Trace
Skill execution emits SkillStarted -> SkillStepExecuted (1 step
per phase in the workflow) -> SkillCompleted. The write_doc_file step
records path + slug + Diataxis quadrant in the step payload, not
the full body (token protection; the body lands on disk and
is readable from there).
Related skills
Generative Code Art
anthropics
Create algorithmic art with p5.js using randomness and interactive parameters.
Poster & Visual Design
anthropics
Create original posters and visual art in PNG and PDF formats.
Claude API Helper
anthropics
Build, debug, and optimize Claude API applications with caching and model migration support.
MCP Server Builder
anthropics
Build protocol servers that connect language models to external APIs and services.