dev-docs-suite
npx machina-cli add skill nothingtosurprise/dev-docs-suite/dev-docs-suite --openclawDev Docs Suite
A skill for generating the four most time-consuming developer documents — fast, from minimal input, with consistent structure every time.
Supported Document Types
| What user says | Document type | Reference file |
|---|---|---|
| "write a post-mortem", "incident report", "outage report" | Post-Mortem | references/post-mortem.md |
| "create an ADR", "document this decision", "architecture decision" | ADR | references/adr.md |
| "document this API", "API contract", "endpoint docs", "OpenAPI" | API Contract Doc | references/api-contract.md |
| "onboarding docs", "readme for new devs", "how this codebase works" | Onboarding Doc | references/onboarding.md |
How to Use This Skill
Step 1 — Identify the document type
From the user's message, determine which of the four document types they need. If ambiguous, ask one clarifying question.
Step 2 — Read the reference file
Before generating anything, read the relevant reference file from references/. It contains the template, required fields, and quality checklist for that document type.
Step 3 — Gather missing info (minimal questions)
The goal is to ask as few questions as possible. Extract what you can from context. Only ask for what's truly missing — never ask more than 3-4 questions at once.
Step 4 — Generate the document
Produce the complete document using the template from the reference file. Output it as a well-formatted Markdown document ready to copy-paste or save.
Step 5 — Offer follow-ups
After generating, offer:
- Export as
.mdfile - Adjust tone (formal vs. casual)
- Fill in any placeholder sections the user skipped
General Quality Rules (apply to all doc types)
- Specific over vague: "Database connection pool exhausted at 847 connections" not "database issues"
- Action-oriented: Every section should help the reader do something or understand something
- Honest: Post-mortems especially — no blame, but no hiding what happened either
- Scannable: Use headers, bullet points, and tables where they add clarity
- Complete: Never leave a required section empty — if info is unknown, say "TBD — owner: [name]"
Triggering by example
If the user says any of these, activate immediately without asking for permission:
- "We had an outage last night, help me write it up"
- "I need to document why we chose PostgreSQL over MongoDB"
- "Write docs for our
/usersendpoint" - "New engineer joining next week, help me write something to get them up to speed"
Source
git clone https://github.com/nothingtosurprise/dev-docs-suite/blob/main/SKILL.mdView on GitHub Overview
Dev Docs Suite creates four essential software development documents quickly using minimal input. It leverages standardized templates from the references folder to ensure consistency across ADRs, post-mortems, API contracts/docs, and onboarding guides. This reduces turnaround time, prompts precise information capture, and delivers Markdown-ready outputs you can copy-paste or save.
How This Skill Works
It first identifies the document type from the user message and selects the corresponding reference template (ADR, post-mortem, API contract, or onboarding). It then gathers missing details with minimal clarifying questions and fills the template to produce a complete Markdown document. Finally, it presents the document with options to export, adjust tone, or fill any skipped placeholders.
When to Use It
- You need a post-mortem or incident/outage report after a disruption
- You're documenting a design decision with an Architecture Decision Record (ADR)
- You must document an API, including contracts, endpoint docs, or OpenAPI specs
- You want onboarding material for a new developer or a codebase walkthrough
- You want to standardize documentation for a software project and enforce a consistent structure
Quick Start
- Step 1: State which document you want (Post-Mortem, ADR, API Contract Doc, Onboarding Doc)
- Step 2: Provide minimal inputs (incident summary, design context, endpoints, or onboarding topics)
- Step 3: Review the generated Markdown and export as .md or tweak tone
Best Practices
- Identify the document type clearly in your initial message
- Provide essential context (timeline, impact, decisions) while keeping input concise
- Let the tool fill placeholders as 'TBD — owner: [name]'; replace later
- Review against the reference template and ensure all required sections are populated
- Keep tone consistent across documents (formal vs casual) and export to Markdown
Example Use Cases
- Post-mortem: wrote an outage report for last night's ProdX incident
- ADR: documented the decision to switch from MongoDB to PostgreSQL
- API Contract Doc: generated endpoint docs and OpenAPI-style contract for /users
- Onboarding Doc: created a codebase walkthrough for a new frontend team
- API docs: drafted API contracts with request/response schemas for /orders
