| name | using-technical-writer |
| description | Use when writing or improving documentation - ADRs, APIs, runbooks, READMEs, architecture docs, security/compliance docs, post-mortems, register review or translation (technical/policy/government/public-facing/executive/academic), fact-checking research papers, or surgical edits on large (>=2000 line) files |
Using Technical Writer
Overview
This meta-skill routes you to the right technical writing skills based on your documentation task. Load this skill when you need to create, improve, or organize documentation but aren't sure which specific writing skill to use.
Core Principle: Different document types and audiences require different skills. Match your situation to the appropriate skill, load only what you need.
When to Use
Load this skill when:
- Starting any documentation task
- User mentions: "document", "write docs", "README", "API docs", "ADR", "runbook"
- Creating technical content for any audience
- Improving or reorganizing existing documentation
Don't use for: Non-technical writing (marketing copy, blog posts, creative content)
How to Access Reference Sheets
IMPORTANT: All reference sheets are located in the SAME DIRECTORY as this SKILL.md file.
When this skill is loaded from:
skills/using-technical-writer/SKILL.md
Reference sheets like documentation-structure.md are at:
skills/using-technical-writer/documentation-structure.md
NOT at:
skills/documentation-structure.md ← WRONG PATH
When you see a link like [documentation-structure.md](documentation-structure.md), read the file from the same directory as this SKILL.md.
Routing by Document Type
Architecture Decisions (ADRs)
Symptoms: "Document why we chose X", "Record this architectural decision", "Explain technology choice"
Route to: documentation-structure.md
Key Pattern: ADRs document Context → Decision → Consequences
Example: "Document why we chose PostgreSQL over MongoDB" → Load documentation-structure.md
API Documentation
Symptoms: "Document this API", "Create API reference", "Explain endpoints"
Route to:
- documentation-structure.md (API reference pattern)
- clarity-and-style.md (examples, precision)
Example: "Document REST API for user management" → Load both skills
Runbooks & Procedures
Symptoms: "Write deployment procedure", "Create incident runbook", "Document how to..."
Route to:
- documentation-structure.md (runbook pattern)
- clarity-and-style.md (step-by-step clarity)
Example: "Create deployment runbook" → Load both skills
README Files
Symptoms: "Add a README", "Quick start guide", "Installation instructions"
For Complex Projects:
Route to: documentation-structure.md (README pattern)
For Simple Utilities:
Route to: NONE - basic technical writing sufficient
Decision Point: Complex (>100 lines, multiple features, deployment) vs Simple (script, single function)
Security Documentation
Symptoms: "Document threat model", "Security controls", "Document security decisions"
Route to (Cross-Faction):
ordis/security-architect/documenting-threats-and-controls (security content)- documentation-structure.md (ADR format, organization)
- clarity-and-style.md (explain to non-experts)
Key Insight: Security docs need BOTH content expertise (Ordis) AND writing skills (Muna)
Example: "Document authentication security decisions" → Load all three skills
Routing by Audience
Audience vs Register: Audience (who-receives) and register (how-text-operates) are orthogonal. A document has both. Audience determines what information to include; register determines how to express it. For register-specific requests (institutional voice, policy language, writing conventions), see Routing by Register below.
Developer Audience
What They Need: Architecture diagrams, code examples, API references, technical depth
Route to:
Example: "Write docs for internal developers" → Load all three
Operator Audience
What They Need: Runbooks, troubleshooting, deployment procedures, configuration guides
Route to:
Example: "Create SRE runbook" → Load both skills
Executive Audience
What They Need: High-level summaries, business impact, risks, costs (minimal technical detail)
Route to:
Example: "Executive summary of migration plan" → Load clarity-and-style.md only
Mixed/Public Audience
What They Need: Progressive disclosure (quick start → advanced topics), multiple entry points
Route to:
Example: "Public documentation for open-source project" → Load all three
Routing by Register
Register routing applies AFTER audience determination. Use register routing when the user asks about institutional voice, writing conventions, or adapting a document for a specific institutional context.
Keywords: "register", "editorial", "policy language", "government style", "translate to [register]", "adapt for government", "public-facing version", "review style", "writing register"
Priority rule: Register-specific requests route to editorial-registers + editorial-reviewer agent. Generic style and audience requests ("write for executives", "make this clearer") continue to route to clarity-and-style as before.
Register Review / Detection
Symptoms: "What register is this?", "Review the style", "Is this appropriate for government?", "Check the tone"
Route to:
Example: "Is this policy document written in the right register?" → Load editorial-registers, use editorial-reviewer agent
Register Translation
Symptoms: "Rewrite for public audience", "Adapt this for executives", "Translate from technical to government register"
Route to:
Example: "Rewrite this technical spec for a public-facing FAQ" → Load editorial-registers, use editorial-reviewer agent in translate mode
Complex Edits in Large Files
Symptoms: "Edit this 5000-line spec", "Rename X across this module and update all the callers", "Merge sections 4 and 5 and renumber the rest", "Refactor error handling in this 3000-line file", "Update all 30 endpoints in the API reference"
Route to:
complex-writer agent (surgical edit with pre-work assessment)complex-reviewer agent (independent verification of the edit)
Key Pattern: Survey → Pre-work assessment (complexity / blast radius / risk / mitigations) → caller confirms → Plan → Edit → Verify → paired review.
Cross-language: The pair handles both documentation AND source code (Markdown, Python, Rust, TypeScript, Go, etc.). For language-specific idiomatic code review (after the edit is verified correct), prefer the language-specific reviewer (rust-code-reviewer, python-code-reviewer, etc.) — complex-reviewer verifies the edit landed correctly, not whether the code is idiomatic.
Example: "Rename all uses of legacy_handler in this 4000-line service module" → complex-writer produces a pre-work assessment showing 47 call sites and TOC-of-handlers update needed; caller confirms; writer applies edits; complex-reviewer verifies zero hits of the old name and all 47 sites updated correctly.
When NOT to use: Single-file changes <500 lines, simple typo fixes, or multi-file feature work (this pair is single-file scoped — for multi-file, use planning skills + subagent-driven-development).
Fact-Checking & Verification
Symptoms: "Fact-check this paper", "Verify claims in this document", "Check if these citations are accurate"
Route to: /fact-check <file-paths> (slash command — this skill is token-intensive and should be invoked explicitly)
Key Pattern: Four-phase pipeline — extract claims, dual-verify with independent web-search agents, reconcile, output structured results + exception report
Example: "Fact-check my research paper at docs/paper.md" → Invoke /fact-check docs/paper.md
Note: This is an expensive operation. Only route here when the user explicitly asks for fact-checking or claim verification. Do not invoke speculatively.
Cross-Faction Documentation
Security + Documentation
When: Documenting threat models, security controls, classified systems, compliance
Route to:
Example: "Document MLS security architecture" → Load all four skills
Compliance + Documentation
When: Audit documentation, SSP/SAR, compliance mappings
Route to:
Example: "Create SOC2 compliance documentation" → Load all three skills
Incident Response + Documentation
When: Post-mortem reports, incident runbooks, response procedures
Route to:
Example: "Write post-mortem for outage" → Load all three skills
Documentation Workflow
Standard Flow
1. Determine document type → Route to structure skill
2. Write content → Apply clarity/style skill
3. Add diagrams if needed → Use diagram conventions
4. Test documentation → Use documentation-testing
Quick Reference
| Task | Load |
|---|
| "Why did we choose X?" | documentation-structure (ADR) |
| "Document API" | documentation-structure + clarity-and-style |
| "Deployment runbook" | documentation-structure + clarity-and-style |
| "README for utility" | NONE (simple) or documentation-structure (complex) |
| "Security docs" | documenting-threats + documentation-structure + clarity |
| "Developer guide" | documentation-structure + diagram-conventions + clarity |
| "Executive summary" | clarity-and-style only |
| "Fact-check paper" | /fact-check <paths> (slash command) |
| "Edit this large file" / "rename across this module" | complex-writer + complex-reviewer agents |
When NOT to Load Documentation Skills
Don't load skills for:
- Simple utility README (<50 lines, single purpose, obvious usage)
- Code comments (use standard practices)
- Commit messages (use conventional commits)
- Chat/email (conversational writing)
- First drafts where you're exploring (capture ideas first, structure later)
Example: "Add README to hello-world script" → No special skills needed
Core vs Extension Skills
Core Skills (Universal - Any Project)
Use for any project:
- documentation-structure.md - ADRs, APIs, runbooks, READMEs, architecture docs
- clarity-and-style.md - Active voice, concrete examples, audience adaptation
- diagram-conventions.md - System diagrams, data flows, architecture visuals
- documentation-testing.md - Verify docs are accurate, complete, findable
Extension Skills (Specialized Contexts)
Use only when context requires:
Decision: If unsure whether context is "specialized", start with core skills. Specialized needs will be explicit.
Common Routing Patterns
Pattern 1: ADR for Architecture Decision
User: "We chose to use REST instead of GraphQL. Document this."
You: Loading [documentation-structure.md](documentation-structure.md) (ADR pattern)
Pattern 2: API Documentation
User: "Document our user management API."
You: Loading [documentation-structure.md](documentation-structure.md) + [clarity-and-style.md](clarity-and-style.md)
Pattern 3: Security Documentation (Cross-Faction)
User: "Document the threat model for authentication."
You: Loading ordis/security-architect/documenting-threats-and-controls +
[documentation-structure.md](documentation-structure.md) +
[clarity-and-style.md](clarity-and-style.md)
Pattern 4: Simple README
User: "Add README to this backup script."
You: [Check script complexity]
Simple utility → No skills needed
OR
Complex tool → Loading [documentation-structure.md](documentation-structure.md)
Pattern 5: Operator Runbook
User: "Create runbook for database failover."
You: Loading [documentation-structure.md](documentation-structure.md) (runbook) +
[clarity-and-style.md](clarity-and-style.md) (step-by-step clarity)
Decision Tree
Starting documentation task?
├─ What type?
│ ├─ Architecture decision → documentation-structure (ADR)
│ ├─ API documentation → documentation-structure + clarity-and-style
│ ├─ Runbook/procedure → documentation-structure + clarity-and-style
│ ├─ README → Complex? documentation-structure : None
│ └─ Security/compliance → Cross-faction (Ordis + Muna)
│
├─ Who's the audience?
│ ├─ Developers → Add diagram-conventions
│ ├─ Operators → Focus on runbook patterns
│ ├─ Executives → clarity-and-style only (progressive disclosure)
│ └─ Mixed → All core skills
│
├─ What register/institutional context?
│ ├─ Policy conventions → editorial-registers + editorial-reviewer
│ ├─ Government/regulatory → editorial-registers + editorial-reviewer
│ ├─ Public-facing prose → editorial-registers + editorial-reviewer
│ ├─ Academic/research → editorial-registers + editorial-reviewer
│ ├─ Executive (register, not audience) → editorial-registers + editorial-reviewer
│ └─ Technical (default for dev docs) → No additional routing needed
│
└─ Specialized context?
├─ Sensitive data → ADD: security-aware-documentation
├─ Incident response → ADD: incident-response-documentation
├─ Government/compliance → ADD: operational-acceptance-documentation
└─ None → Core skills sufficient
Quick Reference Table
| Document Type | Primary Skill | Additional Skills | Cross-Faction? |
|---|
| ADR | documentation-structure | clarity-and-style | No |
| API docs | documentation-structure | clarity-and-style | No |
| Runbook | documentation-structure | clarity-and-style | No |
| README (complex) | documentation-structure | clarity-and-style, diagram-conventions | No |
| README (simple) | NONE | NONE | No |
| Security docs | documenting-threats-and-controls | documentation-structure, clarity-and-style | Yes (Ordis) |
| Compliance | operational-acceptance-documentation | documentation-structure | Yes (Ordis) |
| Developer guide | documentation-structure | diagram-conventions, clarity-and-style | No |
| Operator guide | documentation-structure | clarity-and-style | No |
| Executive summary | clarity-and-style | NONE | No |
| Post-mortem | incident-response-documentation | documentation-structure, clarity-and-style | No |
| Register review | editorial-registers | editorial-reviewer agent | No |
| Register translation | editorial-registers | editorial-reviewer agent | No |
Common Mistakes
❌ Loading All Skills for Every Task
Wrong: Load all 8 Muna skills for every documentation task
Right: Load only skills your situation needs (use decision tree)
❌ Missing Cross-Faction Needs
Wrong: Document security with only Muna skills (missing security content expertise)
Right: Load Ordis skills for content + Muna skills for structure/clarity
❌ Over-Engineering Simple Docs
Wrong: Load documentation-structure for 10-line README
Right: Simple docs don't need special skills (just write clearly)
❌ Not Considering Audience
Wrong: Same documentation for developers and executives
Right: Adapt content and skills based on audience needs
Examples
Example 1: Documenting Database Choice
User: "We decided on PostgreSQL. Document why."
Your routing:
1. Recognize: Architecture decision → ADR format
2. Load: [documentation-structure.md](documentation-structure.md)
3. Create: ADR with Context, Decision, Consequences
Example 2: Security Threat Model Documentation
User: "Document the threat model for our API gateway."
Your routing:
1. Recognize: Security content (need Ordis) + Documentation (need Muna)
2. Load: ordis/security-architect/documenting-threats-and-controls (threats content)
3. Load: [documentation-structure.md](documentation-structure.md) (ADR for security decisions)
4. Load: [clarity-and-style.md](clarity-and-style.md) (explain to non-security team)
5. Create: Threat model doc with STRIDE analysis + mitigations + clear explanations
Example 3: Simple Utility README
User: "Add README to this file-copy script."
Your routing:
1. Recognize: Simple utility (single function, obvious usage)
2. Decision: No special skills needed
3. Create: Basic README with usage example, no complex structure
Summary
This skill maps documentation tasks → specific writing skills to load.
- Identify document type (ADR, API, runbook, README, security)
- Use decision tree to find applicable skills
- Load core skills for universal needs
- Add extension skills for specialized contexts
- Cross-reference Ordis for security/compliance content
- Don't load skills when not needed (simple docs)
Meta-rule: When in doubt about document type, start with documentation-structure.md - it covers most common patterns (ADR, API, runbook, README).
Technical Writer Specialist Skills Catalog
After routing, load the appropriate specialist skill for detailed guidance:
Core Skills (Universal)
- documentation-structure.md - ADR format, API reference patterns, runbook templates, README structure, architecture documentation
- clarity-and-style.md - Active voice, concrete examples, progressive disclosure, audience adaptation, step-by-step clarity
- diagram-conventions.md - System diagrams, data flow visuals, architecture overviews, C4 model, consistent notation
- documentation-testing.md - Verify accuracy, completeness, findability, test examples, validate links
Extension Skills (Specialized Contexts)
- security-aware-documentation.md - Sanitizing sensitive data, classification marking, redacting examples, security-conscious writing
- incident-response-documentation.md - Post-mortem templates, incident runbooks, RCA structure, timeline documentation
- itil-and-governance-documentation.md - ITIL processes, change management, governance frameworks, policy documentation
- operational-acceptance-documentation.md - SSP/SAR structure, POA&M templates, government authorization, compliance artifacts
- editorial-registers.md - Writing register definitions (technical, policy, government, public-facing, executive, academic), register relationships, custom register template
Leaf Skills (Invoked Explicitly)
fact-checking (sibling skill) - Dual-verified fact-checking of research papers / documents. Invoked via /fact-check <file-paths> slash command. Token-intensive; do not invoke speculatively.
