Skip to content
Skills Library
Documents & office · Writing

diataxis-write-docs

/diataxis-write-docs

Draft or revise project documentation for the reader's purpose using Diataxis. Use for writing tutorials, how-to guides, reference, or explanation; use diataxis-organize-docs for reorganizing an existing documentation collection.

Repository
agentskills ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Draft or revise project documentation for the reader's purpose using Diataxis. Use for writing tutorials, how-to guides, reference, or explanation; use diataxis-organize-docs for reorganizing an existing documentation collection.

Original author description

Draft or revise project documentation for the reader's purpose using Diataxis. Use for writing tutorials, how-to guides, reference, or explanation; use diataxis-organize-docs for reorganizing an existing documentation collection.

How it works

  1. Choose the Reader Need
  2. Establish the Evidence
  3. Draft or Revise
  4. Place and Connect
  5. Verify and Deliver
Original SKILL.md headings · 47 lines, 549 words
SKILL.md preview
---
name: diataxis-write-docs
description: Draft or revise project documentation for the reader's purpose using Diataxis. Use for writing tutorials, how-to guides, reference, or explanation; use diataxis-organize-docs for reorganizing an existing documentation collection.
allowed-tools:
  - Read
  - Write
---

# Diataxis Documentation Writing

Write documentation that answers a specific reader need and reflects the project's actual behavior. This workflow works independently of documentation reorganization.

## Choose the Reader Need

Identify the audience, assumed knowledge, desired outcome, and requested scope from the task and available material. Ask only when missing information would materially change the document.

Choose by purpose, not topic difficulty or the presence of code. Read the matching reference when drafting or revising that type; load additional references only for additional requested document types.

| Reader need | Document type | Writing guidance |
|-------------|---------------|------------------|
| Learn through a guided exercise | Tutorial | [Tutorial writing](references/tutorial.md) |
| Accomplish a particular task | How-to | [How-to writing](references/how-to.md) |
| Look up precise information | Reference | [Reference writing](references/reference.md) |
| Understand a concept or rationale | Explanation | [Explanation writing](references/explanation.md) |

For a mixed request, give each document a primary purpose and connect related material with links. Preserve the user's requested deliverables. A request to draft a page does not require reorganizing the collection first.

## Establish the Evidence

Inspect the relevant implementation, schemas, tests, existing documentation, and maintained project examples. Match external documentation to the project's version and dependencies. Use available project discovery tools when provided.

Resolve conflicting sources before making a definitive claim. Distinguish implemented behavior from proposals, intentions, and assumptions. Do not invent commands, API signatures, defaults, output, or design rationale to complete a draft. Narrow unsupported claims or ask for the missing information when it prevents a useful result.

## Draft or Revise

Apply the selected reference's writing guidance and anti-pattern checks. Make the title and opening identify the reader's goal, then include the detail needed to achieve it. Preserve useful existing content and project terminology during revision.

Keep instructions and generated documentation free of manually maintained totals and numbered section references. Use descriptive headings and named links. For actual ordered procedures, write every Markdown list marker as `1.` so the renderer maintains numbering. Preserve necessary numeric facts such as versions, limits, and measured values.

## Place and Connect

Honor the requested destination and existing documentation conventions. For a new documentation collection without an established layout, use `docs/tutorial/`, `docs/how-to/`, `docs/reference/`, and `docs/explanation/`, with `docs/README.md` as the navigation hub. Create only the directories the requested documents need.

Add relevant navigation links when maintaining the collection is within scope, and repair links affected by your edits. Link only to known destinations. When draft pages have no assigned paths, report suggested cross-references in the delivery note instead of adding speculative paths or cross-document anchors. Leave unrelated files and organization alone. Use `diataxis-organize-docs` when the user also requests collection restructuring.

## Verify and Deliver

- Check claims, identifiers, and example inputs against the evidence and declared version.
- Exercise executable examples when available tools, environment, and authorization permit. Otherwise inspect them against source and report that they were not run. Label conceptual snippets as illustrative when readers could mistake them for executable examples.
- Check affected links, anchors, and any applicable documentation build using available tools.
- Confirm the document satisfies the selected reader need without unnecessary digressions.

Deliver the requested documentation with a concise account of verification and any remaining evidence gaps. Do not present static inspection as execution or a proposed design as shipped behavior.
Files in this package (5)
  • SKILL.md 4 KB
  • references/explanation.md 1 KB
  • references/how-to.md 1 KB
  • references/reference.md 1 KB
  • references/tutorial.md 1 KB

Versions

The database has no other skills named diataxis-write-docs.

Database snapshot: 13.11.2026 · package version ea2b6f941522 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100diataxis
    Four-quadrant documentation framework. Produces tutorials (learning by doing), how-to guides (goal-oriented tasks), reference documentation (authoritative description), and explanation (conceptual understanding) using the Diataxis methodology. Invoke when creating new…
  • 100diataxis
    Helps maintain documentation pages based on the Diataxis method. Analyzes existing docs, classifies pages into tutorials/how-to/explanation/reference categories, identifies gaps, and helps create or restructure documentation following Diataxis principles. Use when user mentions…
  • 100make-docs
    Create, edit, and validate technical documentation using the Diataxis framework. Use when writing tutorials, how-to guides, reference docs, or explanations. Use when reviewing or auditing existing documentation for structural correctness. Use when deciding what type of document…
  • 100diataxis
    Structure, classify, and write documentation using the Diátaxis framework. Use when writing docs, README files, guides, tutorials, how-to guides, API references, or organizing documentation architecture. Also use when asked to improve documentation, restructure docs, decide what…
  • 100diataxis-docs
    Generate a complete Diátaxis documentation set (tutorials, how-to guides, reference, explanation) from a codebase. Use ONLY when the user explicitly invokes /diataxis-docs or asks for this skill by name — never for incidental documentation requests like editing a README.
  • 90writing-documentation-with-diataxis
    Applies the Diataxis framework to create or improve technical documentation. Use when being asked to write high quality tutorials, how-to guides, reference docs, or explanations, when reviewing documentation quality, or when deciding what type of documentation to create. Helps…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.