Name: documentation
Author: mcollina

About

Imported from mcollina/skills (skills/documentation/SKILL.md) via skills.sh. Install upstream with npx skills add mcollina/skills --skill documentation. Copyright stays with the author.

When to use

Use this skill when you need to create, review, or improve technical documentation following the Diátaxis framework. Examples include:

Creating user guides
API documentation
Tutorial content
Restructuring existing documentation to better serve different user needs and contexts

Instructions

Organize documentation into four distinct types — tutorials, how-to guides, reference material, and explanations — each serving different user needs and contexts.

Always ask clarifying questions about the user's context, audience, and goals before creating documentation.

Step 1 — Identify the documentation type

Use the following decision checklist based on user signals:

User signal	Documentation type
"I'm new to X and want to learn it" / "walk me through"	Tutorial
"How do I…?" / "I need to accomplish X"	How-to guide
"What are the parameters/options/syntax for X?"	Reference
"Why does X work this way?" / "Help me understand X"	Explanation

Quick decision tree:

Is the user learning by doing for the first time? → Tutorial
Do they need to solve a specific problem they already understand? → How-to guide
Do they need technical facts to look up? → Reference
Do they want conceptual background? → Explanation

Step 2 — Apply type-specific patterns

Tutorials (learning-oriented)

Title pattern: Start with a verb — "Build your first X", "Create a Y from scratch"
Structure: Goal → Prerequisites → Numbered steps → Immediate verifiable result at each step → Final outcome
Minimise explanation; maximise doing
Every step must produce a visible, testable result
Validation: A beginner must be able to complete the tutorial without external help

Example intro:

"In this tutorial, you will build a simple REST API using Express. By the end, you will have a running server that responds to GET requests. No prior Express experience is needed."

How-to guides (problem-oriented)

Title pattern: Frame as a task — "How to configure X", "How to deploy Y to Z"
Structure: Goal statement → Assumptions/prerequisites → Numbered steps → Expected result
Assume baseline knowledge; skip conceptual explanations
Allow for variation; note alternatives where they exist
Validation: An experienced user can complete the task without confusion or backtracking

Example intro:

"This guide shows how to add JWT authentication to an existing Express app. It assumes you have a working Express server and basic familiarity with middleware."

Reference (information-oriented)

Title pattern: Name the thing — "Configuration options", "API endpoints", "CLI flags"
Structure: Consistent repeatable format per entry (name → type → default → description → example)
State facts; avoid instruction beyond minimal usage examples
Keep current; version-stamp if needed
Validation: A user can look up a specific fact in under 30 seconds without reading surrounding content

Example entry:

timeout (integer, default: 5000) Maximum time in milliseconds to wait for a response before the request fails. Example: { timeout: 3000 }

Explanations (understanding-oriented)

Title pattern: Frame as a concept — "How X works", "Understanding Y", "Why Z is designed this way"
Structure: Context → Core concept → Alternatives/trade-offs → Higher-level perspective
Avoid step-by-step instruction or technical specification
Validation: After reading, the user can explain the concept in their own words and understands the rationale behind design decisions

Example intro:

"Authentication and authorisation are often confused. This page explains the distinction, why both matter, and how common patterns (sessions, tokens, OAuth) approach each concern differently."

Step 3 — Maintain separation and integration

Keep each document a single type — don't mix tutorial steps with reference tables or conceptual digressions
Cross-link between types: a tutorial can link to the relevant reference page; a how-to guide can link to an explanation for background
Use consistent headings and terminology across all types so users can navigate the full documentation system

Step 4 — Validate before delivering

Type	Validation check
Tutorial	Can a beginner complete it end-to-end without external help?
How-to guide	Does it solve the stated problem for an experienced user?
Reference	Can the user find a specific fact in under 30 seconds?
Explanation	Does the user understand the why, not just the what?

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/mcollina-skills-documentation/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

mcollina-skills-documentation.ocm.jsonjson

{
  "ocm": "1",
  "id": "mcollina-skills-documentation",
  "kind": "skill",
  "name": "documentation",
  "description": "Creates, structures, and reviews technical documentation following the Diátaxis framework (tutorials, how-to guides, reference, and explanation pages). Use when a user needs to write or reorganize docs, structure a tutorial vs. a how-to guide, build reference docs or API documentation, create explanation pages, choose between Diátaxis documentation types, or improve existing documentation structure. Trigger terms include: documentation structure, Diátaxis, tutorials vs how-to guides, organize docs, user guide, reference docs, technical writing.",
  "publisher": "mcollina",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding"
    ],
    "tags": [
      "skill-md",
      "documentation",
      "technical-writing",
      "tutorials",
      "guides",
      "reference",
      "diataxis",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Creates, structures, and reviews technical documentation following the Diátaxis framework (tutorials, how-to guides, reference, and explanation pages). Use when a user needs to write or reorganize docs, structure a tutorial vs. a how-to guide, build reference docs or API documentation, create explanation pages, choose between Diátaxis documentation types, or improve existing documentation structure. Trigger terms include: documentation structure, Diátaxis, tutorials vs how-to guides, organize docs, user guide, reference docs, technical writing."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/mcollina/skills",
      "path": "skills/documentation/SKILL.md",
      "ref": "HEAD",
      "url": "https://www.skills.sh/mcollina/skills/documentation",
      "key": "mcollina/skills/skills/documentation/SKILL.md"
    }
  },
  "instructions": "## When to use\n\nUse this skill when you need to create, review, or improve technical documentation following the Diátaxis framework. Examples include:\n- Creating user guides\n- API documentation\n- Tutorial content\n- Restructuring existing documentation to better serve different user needs and contexts\n\n## Instructions\n\nOrganize documentation into four distinct types — tutorials, how-to guides, reference material, and explanations — each serving different user needs and contexts.\n\nAlways ask clarifying questions about the user's context, audience, and goals **before** creating documentation.\n\n--",
  "cost": {
    "context_tokens": 1178
  }
}

Fetch it by URL: GET /api/v1/registry/mcollina-skills-documentation/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.