Agent Skills: Document Writer

Document Writer

Use this skill to create or improve technical documentation by matching the document to the reader's actual need. The operating model is Diataxis-first: classify the reader need before choosing structure, tone, examples, tables, or diagrams.

Default Behavior

• Write documentation in Korean unless the user explicitly requests another language.
• Keep code, commands, identifiers, and code comments in English.
• Default to compact, structured documentation: descriptive headings, labeled bullets, numbered steps, and tables. Assume readers may review it together over screen sharing; minimize prose unless a short paragraph communicates the meaning more clearly.
• Compress presentation, not substance. Preserve all scope-relevant facts, reasoning, conditions, exceptions, trade-offs, examples, and evidence; do not turn a complete document into a lossy summary.
• Proactively add useful diagrams, charts, screenshots, or wireframes without waiting for an explicit request. Include each visual that materially improves understanding; choose by explanatory value, not a fixed count.
• In Korean documents, minimize English except where exact technical meaning requires it, such as code, commands, identifiers, API names, configuration keys, and product names. Prefer plain Korean over difficult Sino-Korean terms, translationese, or overly formal phrasing.
• If working inside a repository, inspect relevant source files, existing docs, configuration, or tests before writing factual technical content.
• Ask one concise clarification question only when the audience, use moment, or requested output is too ambiguous to choose a documentation mode safely. Otherwise, proceed and state assumptions at the end.
• Prefer the smallest useful documentation change when improving existing docs. Diataxis is a guide for better local decisions, not a reason to rewrite everything.

Diataxis Compass

Before drafting, classify the document or section with two questions:

1. Is the reader trying to act or think?
2. Is the reader acquiring new capability or applying existing capability?

| Need | Mode | Reader question | Use this when | | --- | --- | --- | --- | | Action + acquisition | Tutorial | "Can you teach me to...?" | The reader needs a safe, guided learning experience. | | Action + application | How-to guide | "How do I...?" | The reader is competent and needs to complete a real task. | | Cognition + application | Reference | "What is...?" | The reader needs exact facts while working. | | Cognition + acquisition | Explanation | "Why...?" | The reader needs context, background, or understanding. |

Do not treat README, API docs, runbooks, architecture docs, onboarding guides, design docs, or problem-analysis docs as primary modes. They are composite document patterns that may contain multiple Diataxis modes.

Workflow

1. Define the reader and use moment.

   • Identify who reads the document, what they already know, what they are trying to do or understand, and when they read it.
   • Capture constraints such as output path, language, product area, deadline, required sources, or style requirements.

2. Classify the mode.

   • For a simple document, choose one primary mode.
   • For a composite document, classify each major section independently.
   • If helpful, create a compact section map: Section | Reader need | Diataxis mode | Source material.

3. Gather source material.

   • Use existing code, configuration, tests, API schemas, design notes, incidents, tickets, or prior docs as evidence.
   • Prefer links and citations to duplicated facts when duplication would become stale.
   • Do not invent commands, API fields, system behavior, ownership, SLAs, or operational procedures.

4. Choose the representation, then draft or revise with mode-specific rules.

   • For each substantial section, identify the information shape before choosing its format: connected rationale or context, independent conditions, ordered actions, repeated attributes, relationships or flow, user interaction, or concrete system behavior.
   • Start with labeled bullets for facts and reasoning, numbered steps for ordered actions, and tables for comparisons or repeated short attributes. Keep causes, conditions, and consequences explicit within each point or through a clear sequence of points. Use a short paragraph only where these forms would obscure the argument.
   • Actively look for visual opportunities in each substantial section: diagrams for relationships, flow, or state; charts for supported quantitative comparisons or trends; and example screens or wireframes for spatial layout or user interaction. Add them where they make the subject easier to understand, alongside runnable examples with expected output when readers need to recognize correct behavior.
   • Use multiple focused visuals when they answer different reader questions. Keep necessary explanation, exact constraints, and evidence beside them; remove redundant narration, not details that the visual cannot convey.
   • Use a clearly labeled wireframe when a verified product capture is unavailable. Do not present an invented interface as the actual product.
   • Use references/diataxis-mode-guide.md for non-trivial tutorial, how-to, reference, or explanation work.
   • Use references/composite-doc-patterns.md when the user asks for README, API docs, runbook, architecture, onboarding, design, or problem-analysis docs.
   • Keep each section locally pure. If a section needs a different mode, split it or link to a better location.

5. Verify functional quality.

   • Check accuracy, completeness for the chosen scope, executable examples, terminology consistency, prerequisites, version assumptions, and staleness risks.
   • Run commands or tests when feasible and safe. If not feasible, clearly state what was not verified.

6. Review deep quality.

   • Check whether the document fits the reader's need, preserves flow, anticipates likely next questions, and avoids mode contamination.
   • Check whether the document works when read together on a shared screen: compact sections, visible structure, and low scanning effort.
   • Remove material that does not improve the reader's understanding, decision, or action, including ornamental openings, repeated conclusions, inflated importance, and unrelated background.
   • Recheck every substantial prose block for a clearer structured form. Preserve causal links, rationale, and trade-offs in labeled points or comparison tables; retain short prose where restructuring would lose meaning.
   • Compare the revision against the source material for omitted facts, qualifiers, exceptions, reasoning, and evidence. Check for missed visual opportunities as well as unnecessary visuals.
   • Remove visuals, tables, headings, or bullets that only repeat nearby content or fragment a simple idea.
   • For Korean documents, check whether English terms and difficult phrasing can be reduced without losing technical precision.
   • Use references/quality-checklists.md before finalizing substantial docs or documentation reviews.

7. Deliver the result.

   • Provide the document or apply the file edits requested by the user.
   • End with concise notes only when useful: sources checked, assumptions, verification performed, and open gaps.

Mode Quick Rules

| Mode | Optimize for | Include | Avoid | | --- | --- | --- | --- | | Tutorial | Successful learning experience | Guided steps, visible progress, expected output, things to notice | Options, digressions, troubleshooting matrices, broad explanation | | How-to guide | Real task completion | Preconditions, executable steps, branches, checks, rollback or next action when relevant | Teaching basics, exhaustive reference, product-feature tours | | Reference | Accurate lookup during work | Parameters, fields, commands, behavior, limits, defaults, errors, concise examples | Narrative, rationale, task walkthroughs, opinions | | Explanation | Understanding and context | Background, reasons, trade-offs, design intent, implications, alternatives | Step-by-step procedures, exhaustive option lists, operational checklists |

Composite Documents

Use document-type labels as practical patterns, not as substitutes for Diataxis classification.

• README: landing page plus selected tutorial, how-to, reference, and explanation sections.
• API documentation: mostly reference, with concise illustrative examples and links to task guides.
• Runbook: operational how-to, supported by brief reference facts and escalation criteria.
• Architecture document: mostly explanation, with diagrams or decision/reference tables only when they clarify the system.
• Onboarding guide: tutorial sequence plus explanation map and links to reference material.
• Design or problem-analysis document: explanation of context and trade-offs, plus decision reference and implementation follow-ups where needed.

Read references/composite-doc-patterns.md before drafting these document types from scratch.

Formatting Principles

• Prefer structured forms by default, then choose the one that matches the information shape. A request for compact writing changes presentation, not the required depth or coverage. Follow an explicitly requested narrative format when applicable.
• Choose headings that match the reader's task or question, not generic template slots.
• Keep shared-screen readability in mind: use short sections and shallow lists. Keep one main point per bullet, with its reason or condition attached; avoid paragraph-sized bullets, cryptic fragments, and deep nesting.
• Use concise labels such as Decision, Reason, Condition, Trade-off, or Evidence when they help scanning, translated into the document's language. Choose labels for the content instead of imposing a fixed template.
• When a sentence becomes hard to follow, clarify it first, then separate distinct claims while retaining their logical connections. Explanation mode requires connected reasoning, not long paragraphs.
• Use tables for compact comparisons, option matrices, API/field references, decision catalogs, and status summaries.
• Prefer tables when each item has several short attributes, such as status, owner, scope, default, constraint, option, or comparison point.
• Avoid tables for long rationale, code-heavy walkthroughs, nested detail, or prose that wraps heavily on mobile.
• If table cells require long rationale, move it into labeled bullets or a short explanation next to the table.
• Add visuals wherever they materially reduce cognitive load or reveal useful structure. Prefer Mermaid for architecture, sequence, flow, ER, state, and dependency diagrams when Markdown rendering supports it; otherwise use a supported image or text diagram.
• Place each visual near the content it explains, with a clear caption or short takeaway and meaningful labels. Verify diagrams against source facts and charts against supplied data; check rendering when possible and state when it was not verified. Provide alt text or a concise text equivalent so essential meaning remains accessible.
• Keep examples concrete and runnable. Show expected output when it helps the reader know they are on track.
• Do not add decorative markers, forced metadata, or boilerplate sections unless the user or repository convention requires them.

Anti-Patterns To Catch

• Mixing tutorial and how-to because both contain steps. A tutorial teaches; a how-to helps a competent user finish work.
• Turning a how-to guide into a product-feature tour. A how-to is organized around the user's goal, not the machinery.
• Expanding reference into explanation. Reference should describe facts with precision and consistency.
• Turning explanation into a procedure. Explanation should connect ideas and answer why, not instruct the reader through a task.
• Creating empty top-level Tutorials / How-to / Reference / Explanation boxes without evidence that the structure helps readers.
• Forcing a planning/design template onto every design problem.
• Adding diagrams, tables, examples, or decision catalogs because they look professional rather than because they improve use.
• Defaulting to long prose, including in explanation mode, when labeled bullets, a comparison table, or a visual would make the same reasoning easier to follow.
• Achieving compactness by dropping conditions, exceptions, causal links, evidence, or other scope-relevant details.
• Stopping after one overview diagram when another focused visual would clarify a distinct interaction, lifecycle, or comparison.
• Duplicating volatile technical facts across documents instead of linking to the authoritative source.