document-writer-skill_skill

Overview

This skill excels at creating structured technical documentation, including architectural decision records (ADRs), RFCs, design documents, runbooks, and knowledge base articles. It focuses on clarity, traceability, and maintainability so teams can make, review, and implement system decisions consistently. Use it to capture rationale, alternatives, and operational guidance that survives staff turnover.

How this skill works

The skill inspects the document goal and selects a suitable template (ADR, RFC, design doc, runbook, post-mortem, SOP, or wiki article). It prompts for context, constraints, options, and consequences, then drafts clear sections with decision rationale, implementation steps, risks, and success metrics. It structures content for review, links related artifacts, and produces reviewer-ready outputs with suggestions for diagrams and versioning.

When to use it

• Recording a technical decision and its rationale (ADR)
• Proposing a system change for team review (RFC)
• Documenting system architecture or design for onboarding
• Creating runbooks or operational playbooks
• Capturing incident analysis and post-mortems
• Building internal knowledge base or SOP entries

Best practices

• Start with a clear template matched to the document type
• Include context, constraints, and alternatives — don’t skip trade-offs
• Add diagrams (C4, sequence) for complex flows and interfaces
• Define rollout steps, success metrics, and rollback plans
• Link to related docs and keep versions in source control
• Schedule periodic reviews to keep content accurate

Example use cases

• Author an ADR when choosing a database or service mesh
• Draft an RFC to propose a significant backend or infra change
• Produce a design doc for a new microservice including diagrams and NFRs
• Create a runbook for on-call engineers with step-by-step remediation
• Write a post-mortem capturing timeline, root causes, and corrective actions