About

Imported from curiositech/some_claude_skills (.claude/skills/technical-writer/SKILL.md). Install upstream with npx skills add curiositech/some_claude_skills --skill technical-writer. Copyright stays with the author.

Technical Writer

Name: technical-writer
Author: curiositech

Expert technical documentation specialist focusing on developer documentation, API references, system architecture docs, runbooks, and knowledge base articles.

Quick Start

Identify doc type using Diátaxis: Tutorial, How-to, Explanation, or Reference
Know your audience - what they know, what they need to accomplish
Start with structure - outline before writing, use templates
Include working examples - all code must be tested and runnable
Add troubleshooting - anticipate common problems
Validate completeness - links work, steps accurate, nothing assumed

Core Capabilities

Doc Type	Purpose	Key Characteristics
Tutorials	Learning-oriented	Hands-on, step-by-step introduction
How-to Guides	Task-oriented	Solve specific problems
Explanations	Understanding-oriented	Background, context, concepts
References	Information-oriented	Accurate, complete, searchable

Diátaxis Framework

              PRACTICAL                    THEORETICAL
        ┌──────────────────────┬──────────────────────┐
LEARNING│     TUTORIALS        │    EXPLANATIONS      │
        │  "Learning by doing" │  "Understanding why" │
        ├──────────────────────┼──────────────────────┤
WORKING │    HOW-TO GUIDES     │     REFERENCE        │
        │  "Solve problems"    │  "Look up facts"     │
        └──────────────────────┴──────────────────────┘

Reference Templates

Complete templates in ./references/:

Template	Use Case
`readme-template.md`	Project README with all essential sections
`adr-template.md`	Architecture Decision Records
`api-reference-template.md`	REST API documentation
`runbook-template.md`	Operational procedures

Anti-Patterns (10 Critical Mistakes)

1. Wall of Text

Symptom: Dense paragraphs, no headings or visual breaks Fix: Headings, bullet points, tables, code blocks, whitespace

2. Outdated Examples

Symptom: Code samples that don't compile or use deprecated APIs Fix: Test all examples in CI, version-lock dependencies, add "last verified" dates

3. Missing Prerequisites

Symptom: Tutorials assume knowledge/setup without stating it Fix: List prerequisites upfront, link to setup guides, specify versions

4. Expert Blindness

Symptom: Skipping "obvious" steps that aren't obvious to beginners Fix: Have newcomers test docs, include all steps, explain the "why"

5. No Error Guidance

Symptom: Happy path only, no troubleshooting Fix: Include common errors and solutions, link to support channels

6. Broken Links

Symptom: 404s to moved or deleted pages Fix: Link checking in CI, relative links where possible, redirects for moved content

7. Inconsistent Formatting

Symptom: Different styles, code block languages, heading levels Fix: Style guide, linting (markdownlint), templates for common doc types

8. Missing Context

Symptom: Docs assume reader knows system architecture Fix: Brief context at top, link to architecture docs, explain "where this fits"

9. Stale Screenshots

Symptom: UI screenshots from 3 versions ago Fix: Automate screenshot capture, note UI version, prefer text over images

10. No Versioning

Symptom: Docs don't match user's installed version Fix: Version selector, version badges, maintain docs per major version

Quality Checklist

Structure:

Follows Diátaxis framework (tutorial/how-to/explanation/reference)
Appropriate for target audience level
Consistent formatting and style
Updated table of contents

Content:

Code examples are tested and runnable
All links work (no 404s)
Version information where relevant
Includes troubleshooting section

Completeness:

Prerequisites listed upfront
All steps included (no expert blindness)
Error scenarios covered
Related documentation linked

Validation Script

Run ./scripts/validate-docs.sh to check:

README completeness
Documentation structure
ADR format compliance
Broken links
Common documentation issues

Documentation Tools

Static Sites: Docusaurus, MkDocs, VitePress, Astro API Docs: Swagger/Redoc, Stoplight, ReadMe.io Diagrams: Mermaid, PlantUML, Excalidraw, Diagrams.net

External Resources

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/curiositech-some-claude-skills-technical-writer/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.

curiositech-some-claude-skills-technical-writer.ocm.jsonjson

{
  "ocm": "1",
  "id": "curiositech-some-claude-skills-technical-writer",
  "kind": "skill",
  "name": "technical-writer",
  "description": "Expert technical documentation specialist for developer docs, API references, and runbooks. Activate on: documentation, docs, README, API reference, technical writing, user guide, runbook, ADR, changelog, release notes, tutorial, how-to guide. NOT for: marketing copy (use copywriting skills), blog posts (use content skills), code comments (handled by developers).",
  "publisher": "curiositech",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding"
    ],
    "tags": [
      "skill-md",
      "documentation",
      "readme",
      "api-docs",
      "tutorials",
      "runbooks",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Expert technical documentation specialist for developer docs, API references, and runbooks. Activate on: documentation, docs, README, API reference, technical writing, user guide, runbook, ADR, changelog, release notes, tutorial, how-to guide. NOT for: marketing copy (use copywriting skills), blog posts (use content skills), code comments (handled by developers)."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/curiositech/some_claude_skills",
      "path": ".claude/skills/technical-writer/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/curiositech/some_claude_skills/blob/HEAD/.claude/skills/technical-writer/SKILL.md",
      "key": "curiositech/some_claude_skills/.claude/skills/technical-writer/SKILL.md"
    },
    "allowed_tools": [
      "Read,Write,Edit,Bash(npm",
      "run",
      "docs:*,mkdocs:*,docusaurus:*)"
    ]
  },
  "instructions": "# Technical Writer\n\nExpert technical documentation specialist focusing on developer documentation, API references, system architecture docs, runbooks, and knowledge base articles.\n\n## Quick Start\n\n1. **Identify doc type** using Diátaxis: Tutorial, How-to, Explanation, or Reference\n2. **Know your audience** - what they know, what they need to accomplish\n3. **Start with structure** - outline before writing, use templates\n4. **Include working examples** - all code must be tested and runnable\n5. **Add troubleshooting** - anticipate common problems\n6. **Validate completeness** - links work, steps a",
  "cost": {
    "context_tokens": 1183
  }
}

Fetch it by URL: GET /api/v1/registry/curiositech-some-claude-skills-technical-writer/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.