Imported from practicalswan/agent-skills (documentation-authoring/SKILL.md). Install upstream with npx skills add practicalswan/agent-skills --skill documentation-authoring. Copyright stays with the author.

Documentation Authoring Master

Expert guidance for creating structured, high-quality documentation across all types of technical and business documents.

• Leverage native parallel subagent dispatch and 200k+ context windows where available.

Activation Conditions

Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.

Trigger Conditions:

• User mentions writing documentation: "write a doc", "draft a proposal", "create a spec", "write up"
• User mentions specific doc types: "PRD", "design doc", "decision doc", "RFC"
• User asks to "create an implementation plan", "document requirements", "plan a feature"
• Creating technical specifications or business requirements
• Starting a new product or feature development cycle
• Translating vague ideas into concrete technical specifications
• Stakeholders need unified "source of truth" for project scope

Part 2: Context Gathering

Initial Questions

Start by asking for meta-context about the document:

1. What type of document is this?

   • Technical spec, decision doc, proposal, RFC, PRD, knowledge base

2. Who's the primary audience?

   • Developers, executives, stakeholders, end-users? Understanding affects tone and depth

3. What's the desired impact when someone reads this?

   • Make a decision, implement a feature, understand a concept?

4. Is there a template or specific format to follow?

   • Company templates, industry standards, regulatory requirements

5. Any other constraints or context to know?

   • Deadlines, sensitive information, existing related documents

Inform them they can answer in shorthand or dump information however works best for them.

Template Handling

If user provides a template:

• Analyze structure and requirements
• Adapt co-authoring workflow to template format
• Ensure all required sections are covered

If user mentions editing an existing document:

• Fetch the existing document
• Understand current state and gaps
• Plan revisions strategically

Part 3: Refinement & Structure

Collaborative Building

Process:

1. Brainstorm each section together - let ideas flow without judgment
2. Organize and refine - structure ideas into coherent sections
3. Edit for clarity - improve readability and flow
4. Add professional polish - formatting, consistency, tone

Guiding Principles:

• Active voice: Use direct, clear language
• Show, don't just tell: Use examples and scenarios
• Progressive disclosure: Start with overview, then dive deeper
• Visual aids: Include diagrams, tables, and examples where helpful

Section-by-Section Approach

Work through document methodically:

## Recommended Section Structure

### 1. Executive Summary (for decision-makers)
- What is this about?
- Why does it matter?
- What are we recommending/deciding?

### 2. Background & Context (for implementers)
- What led us here?
- What problem are we solving?
- What constraints exist?

### 3. Requirements/Objectives
- What must we achieve?
- What are success criteria?
- What are non-goals?

### 4. Proposed Solution/Design
- What are we proposing?
- How does it work?
- What are alternatives considered?

### 5. Implementation Plan
- How do we build this?
- What are the steps?
- Who needs to do what?

### 6. Risks & Considerations
- What could go wrong?
- How do we mitigate?
- What decisions are still needed?

Part 4: Reader Testing

The Fresh Eye Test

Before finalizing, put yourself in the reader's shoes:

Test Questions:

1. Can I understand the goal without knowing context?
2. Are technical terms explained or linked?
3. Is there a logical flow from problem to solution?
4. Would a skeptical reader be convinced?
5. Is action clear - what should I do next?

Blind Spot Detection

Common issues to catch:

• Context assumptions: "We already discussed this" but wasn't documented
• Missing alternatives: Only one option presented (shows lack of thoroughness)
• Unanswered questions: Reader left with "what about X?"
• Unclear responsibilities: Who needs to do what is vague
• Missing examples: Abstract concepts without concrete illustration

Part 5: Product Requirements Document (PRD)

PRD Structure

When users specifically request PRDs or feature planning, use this structure:

# [Feature/Product Name] - PRD

## Executive Summary
**Goal**: [What problem are we solving?]
**Impact**: [Why does this matter now?]
**Success Metrics**: [How will we know it worked?]

## Background
**Current State**: [What's the situation today?]
**Problem Statement**: [What pain points exist?]
**Constraints**: [Budget, timeline, tech stack limitations?]

## Requirements

### Functional Requirements
- User stories with acceptance criteria
- Core features and capabilities
- Integration requirements

### Non-Functional Requirements
- Performance requirements
- Security requirements
- Compliance and regulatory needs

### User Stories

As a [persona], I want to [action], So that [benefit].

**Acceptance Criteria**:
- [ ] [Specific, measurable criterion]
- [ ] [Another criterion]

Proposed Solution

Architecture Overview

[High-level system architecture or approach]

Technical Specifications

[API contracts, data models, interfaces]

UI/UX Requirements

[Wireframes or flow descriptions if applicable]

Implementation Plan

Phases

Dependencies

• External APIs or services
• Other teams or systems
• Third-party libraries

Risk Analysis

Alternatives Considered

Success Criteria

Quantitative

• [Measurable metric: e.g., "reduce load time by 50%"]
• [Another metric]

Qualitative

• [User feedback threshold]
• [Stakeholder alignment]

Open Questions

• [Decision still needed]
• [Information to gather]

### PRD Creation Workflow

**Phase 1: Discovery (The Interview)**
Before writing a single line, you **MUST** interrogate user to fill knowledge gaps. Do not assume context.

**Ask about:**
- **The Core Problem**: Why are we building this now?
- **Success Metrics**: How do we know it worked?
- **Constraints**: Budget, tech stack, or deadline?
- **Stakeholders**: Who needs to approve? Who will use?

**Phase 2: Analysis & Scoping**
Synthesize user input. Identify dependencies and hidden complexities.
- **Map out User Flow**
- **Define Non-Goals** to protect timeline

**Phase 3: Technical Drafting**
Generate document using strict structure above.

---

## Part 6: Common Document Types

### Implementation Plans

**Purpose**: Guide building process with clear phases, responsibilities, and timeline.

**Structure:**
- **Overview**: What are we building and why?
- **Phases**: Break into logical chunks with dependencies
- **Tasks**: Trackable, specific implementation items
- **Timeline**: Realistic dates with buffers
- **Dependencies**: What must happen before what?

### Design Docs

**Purpose**: Document technical decisions and architecture.

**Structure:**
- **Problem Statement**: What problem are we solving?
- **Alternatives**: What did we consider?
- **Decision**: What did we choose and why?
- **Implications**: What does this mean for the system?
- **Risks**: What could go wrong?

### Decision Records

**Purpose**: Capture important decisions for future reference.

**Template:**
```markdown
### Decision - [DATE]
**Decision**: [What was decided]
**Context**: [Situation and driving data]
**Options**: [Alternatives with pros/cons]
**Rationale**: [Why selected option is superior]
**Impact**: [Anticipated consequences]
**Review**: [Reassessment conditions/trigger]

Knowledge Base Articles

Purpose: Reusable reference material, not project-specific docs.

Structure:

• Quick Reference: TL;DR summary at top
• Problem: What question does this answer?
• Solution: How do you solve it?
• Examples: Concrete, runnable examples
• Common Pitfalls: What mistakes do people make?
• Related Topics: Links to related info

Part 7: Best Practices

For All Documentation

✅ DO:

• Use active voice and clear language
• Structure information progressively (simple to complex)
• Include examples and concrete scenarios
• Define terms before using them
• Add diagrams for complex systems
• Maintain consistent formatting and style

❌ DON'T:

• Write without clear audience in mind
• Mix jargon without explanation
• Skip alternatives or trade-offs analysis
• Assume readers have context they don't
• Create long paragraphs without breaks

For Technical Docs

• Include code snippets that actually run
• Link to external references for deeper dives
• Use standard terminology when possible
• Version specific code/commands (e.g., "for node v16+")

For Business/Stakeholder Docs

• Start with executive summary
• Use business impact metrics
• Hide unnecessary technical detail
• Include clear next steps or approvals needed
• Highlight risks and mitigations prominently

Part 8: Action Documentation Format

Use this format for tracking implementation work and decisions:

[TYPE] - [ACTION] - [TIMESTAMP]

Objective: [Goal being accomplished]

Context: [Current state, requirements, reference to prior steps]

Decision: [Approach chosen and rationale]

Execution: [Steps taken with parameters and commands]

Output: [Complete results, logs, metrics]

Validation: [Success verification and results]

Next: [Continuation plan to next action]

Part 9: Summary Formats

Streamlined Action Log (for changelogs)

[TYPE][TIMESTAMP] Goal: [X] → Action: [Y] → Result: [Z] → Next: [W]

Quick Summary (for updates)

What: [Brief description] Why: [Context/rationale] How: [Approach taken] Status: [Current state] Next: [Upcoming step]

Documentation Stack Reference

Inherit the shared stack from documentation-patterns: source-of-truth discovery, audience framing, structure selection, verification, and freshness checks. Keep this skill focused on drafting and refinement instead of restating the full stack.

Anti-Patterns

• Writing for the author instead of the reader: It bakes in unstated context and leaves the actual audience unsure what to do next.
• Skipping concrete examples or commands: Abstract guidance is easy to approve and hard to apply correctly.
• Letting links, screenshots, or versions drift: Polished formatting does not help if the instructions are no longer true.

Verification Protocol

Before claiming "skill applied successfully":

1. Pass/fail: The Documentation Authoring output identifies audience, purpose, source of truth, and freshness requirements.
2. Pass/fail: Shared documentation-stack guidance is referenced instead of duplicating another documentation skill.
3. Pass/fail: Claims, links, commands, examples, and screenshots are verified or explicitly marked unverified.
4. Pressure-test scenario: Apply the skill to a doc request with a stale command, missing owner, and conflicting audience.
5. Success metric: Zero undocumented assumptions; every reader-facing claim is sourced or scoped.

Documentation Quality Checklist

Completeness

• All required sections filled
• Context and background provided
• Alternatives considered where applicable
• Examples and diagrams included where helpful

Clarity

• Language is clear and direct
• Technical terms defined or linked
• Flowlogical and easy to follow
• Active voice used consistently

Accuracy

• Technical details are correct
• Links work and are up-to-date
• Code examples actually run
• No contradictory information

Accessibility

• Multiple levels of detail for different readers
• Executive summary for decision-makers
• Deep-dive sections for implementers
• Visual aids for complex concepts

References & Resources

Documentation

• Document Templates — Templates for PRD, RFC, ADR, Tech Spec, Design Doc, Runbook, Postmortem, KB Article
• Writing Style Guide — Technical writing best practices, formatting conventions, and readability

Scripts

• Doc Structure Validator — Python script to validate markdown document quality

Examples

• PRD Example — Complete PRD for Recipe Search Enhancement in Kitchen Odyssey

Cross-Skill Workflow

• Start in this skill when you need to draft or reshape the document itself.
• Pull in documentation-patterns when the structure or template is the main decision.
• Finish with documentation-quality when the draft needs an explicit review against quality bars.

Agent Prompt Template

Use the documentation-authoring skill to draft a [document type] for [audience].
Goal: [decision, rollout, implementation, or explanation target].
Required sections: [list].
Constraints: [scope, timeline, compliance, or tooling notes].
Include open questions, trade-offs, and next steps at the end.

Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.

• GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the workflow in project instructions when folder discovery is unavailable.
• Claude Code: keep the folder in a local skills directory or a compatible plugin source.
• Codex: install or sync the folder into $CODEX_HOME/skills/documentation-authoring and restart Codex after major changes.

MCP Availability And Fallback

Preferred MCP Server: None required

• Fallback prompt: "Use the Documentation Authoring Master skill without MCP. Rely on the local SKILL.md, bundled references or scripts, and manual verification. Show the exact commands, evidence, and final checks you used before concluding."
• If the current host does not expose a matching server, use the bundled references, scripts, native toolchain, and manual workflow already described in this skill.
• Treat direct local verification, rendered output, logs, tests, or screenshots as the fallback evidence path before completion.

Related Skills

• documentation-patterns: Use it when the workflow also needs reusable documentation structures and templates.
• documentation-quality: Use it when the workflow also needs documentation review standards and quality gates.
• documentation-verification: Use it when the workflow also needs final documentation validation before publishing.
• notion-docs: Use it when the workflow also needs Notion page and database publishing workflows.