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
npx skills add curiositech/some_claude_skills --skill technical-writer -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/technical-writer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/technical-writer/
1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill technical-writer -a codex2Manually: put the files in place
.agents/skills/technical-writer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill technical-writer -a cursor2Manually: put the files in place
.cursor/skills/technical-writer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install curiositech/some_claude_skills .claude/skills/technical-writer2Manually: put the files in place
.github/skills/technical-writer/SKILL.md1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill technical-writer -a gemini-cli2Platform CLI
gemini skills install https://github.com/curiositech/some_claude_skills --path .claude/skills/technical-writerManually: put the files in place
.devin/skills/technical-writer/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill technical-writer -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.