Skip to main content
skill CX Codex

technical-writer · curiositech — Claude Code skill: what it does, how to install

technical-writer structures developer docs, API references, ADRs, and runbooks using the Diátaxis framework with working code examples.

MIT 221 installs ★ 274 updated 2026-09-06

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add curiositech/some_claude_skills --skill technical-writer -a claude-code
Open on GitHub

What technical-writer does

The skill organizes technical documentation around the Diátaxis framework. It separates content into tutorials, how-to guides, conceptual explanations, and references. The focus stays on testable code samples, explicit prerequisites, and concrete troubleshooting sections.

Bundled templates in ./references/ cover README files, architectural decision records, REST APIs, and operational runbooks. For quality checks, it uses ./scripts/validate-docs.sh to spot missing sections and broken links. Terminal execution is limited strictly to mkdocs:*, docusaurus:*, and npm run docs:*.

Promotional copy and blog posts are rejected entirely because the skill rules forbid marketing tasks. The tool handles only engineering documentation and system runbooks.

What it helps with

  • write Architecture Decision Records using the bundled ADR template
  • structure developer guides according to the Diátaxis framework
  • generate REST API references with troubleshooting steps
  • validate markdown links and structure with validate-docs.sh

Example prompts for the agent

  • Create an ADR for our database migration using adr-template.md
  • Write a step-by-step deployment how-to guide with an error handling section
  • Run validate-docs.sh to check the documentation for broken links

How to install technical-writer

1Skills CLI (Vercel)

npx skills add curiositech/some_claude_skills --skill technical-writer -a claude-code

2Manually: put the files in place

~/.claude/skills/technical-writer/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/technical-writer/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about technical-writer

How to install technical-writer in Claude Code?

Run npx skills add curiositech/some_claude_skills --skill technical-writer -a claude-code. The skill writes to ~/.claude/skills/technical-writer/SKILL.md.

What content is technical-writer designed for?

It generates developer-facing documentation, including API references, architecture decision records, runbooks, and project READMEs. It explicitly blocks marketing copy and blog posts.

Which terminal commands can technical-writer execute?

The skill has permissions to run npm run docs:*, mkdocs:*, and docusaurus:*, alongside file reading and editing tools.

Source text

SKILL.md · MIT
---
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).'
allowed-tools: Read,Write,Edit,Bash(npm run docs:*,mkdocs:*,docusaurus:*)
metadata:
  category: Content & Writing
  pairs-with:
  - skill: diagramming-expert
    reason: Visual documentation
  - skill: seo-visibility-expert
    reason: SEO for technical docs
  tags:
  - documentation
  - readme
  - api-docs
  - tutorials
  - runbooks
---

# Technical Writer

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

## Quick Start

1. **Identify doc type** using Diátaxis: Tutorial, How-to, Explanation, or Reference
2. **Know your audience** - what they know, what they need to accomplish
3. **Start with structure** - outline before writing, use templates
4. **Include working examples** - all code must be tested and runnable
5. **Add troubleshooting** - anticipate common problems
6. **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

- [Diátaxis Framework](https://diataxis.fr/)
- [Google Developer Documentation Style Guide](https://developers.google.com/style)
- [Write the Docs](https://www.writethedocs.org/)
- [Keep a Changelog](https://keepachangelog.com/)
- [ADR GitHub](https://adr.github.io/)

© curiositech · MIT · curiositech/some_claude_skills

Similar skills

All skills for Writing and docs →

technical-writer by other authors comes first.

technical-writer OneWave-AI technical-writer is a Claude Code skill that writes and reshapes technical documentation from a project’s code. It activates for README requests, guides, process docs, and codebase explanations. CX Codex +1 1,100installs technical-writing Rudolf S. technical-writing drafts architecture decision records, system architecture overviews, API references, and operations runbooks directly in your codebase. CX Codex +1 ★ 587repo stars agent-technical-writer Tony363 agent-technical-writer is a Claude Code skill for API docs, user guides, and technical content. It activates for technical writing, implementation guidance, and best-practice tasks. CX Codex +1 108installs documentation-writer official github documentation-writer — a skill that turns the agent into a technical writer following the Diátaxis framework: tutorials, how-to guides, reference, and explanation. Proposes structure before writing. CX Codex +1 27,757installs ns-docs-writer nextstage-brasil ns-docs-writer — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that produces human-facing project docs: README files, docs/ guides, runbooks, and contributor markdown. CX Codex +1 151installs Technical Documentation taste f Technical Documentation taste — a prompt defining standards for technical documentation for developers. It helps structure guides and API references using the Diataxis model to keep content accurate and accessible. GP ChatGPT ★ 178,201repo stars tech-docs-writer jarrodwatts tech-docs-writer explores unfamiliar codebases to generate and maintain technical documentation, README files, and API guides with verified code samples. CX Codex ★ 1,064repo stars

From the same set180

The whole set →
drizzle-migrations drizzle-migrations — a skill for schema work with Drizzle ORM on SQLite: tables, columns, indexes, migration generation and applying them. Fits projects where schema changes need to stay repeatable. CX Codex +1 226installs seo-visibility-expert seo-visibility-expert configures technical SEO, llms.txt files for AI scrapers, and schema markup. Useful when preparing web projects for launch. CX Codex +1 224installs mcp-creator mcp-creator is a Claude Code skill for building MCP servers that connect agents to external services. It activates on requests to create or develop an MCP server. CX Codex +1 222installs chatbot-analytics chatbot-analytics adds conversation monitoring and token usage tracking for AI chats while respecting HIPAA constraints. CX Codex +1 221installs reactive-dashboard-performance reactive-dashboard-performance sets up React dashboard performance patterns and speeds up async test suites. Helps replace spinners with skeletons and resolve test runner timeouts. CX Codex +1 220installs devops-automator devops-automator — a skill that turns your AI coder into a DevOps engineer: designs pipelines, writes Terraform and Kubernetes configs, sets up GitOps. Use it when building infrastructure or automating deployments. CX Codex +1 219installs bot-developer The bot-developer skill guides bot development for Discord, Telegram, and Slack, covering conversation state, API limits, and moderation. Use it when a bot needs multi-step interactions or automated rules. CX Codex +1 218installs prompt-engineer prompt-engineer — a skill for crafting and debugging prompts. Eliminates hallucinations, improves response consistency, and strengthens agent instructions through systematic optimization techniques. CX Codex +1 217installs

Project sponsors

Companies that keep this analytics open