documentation-authoring
/documentation-authoring
Tworzy od zera ustrukturyzowane dokumenty: PRD, specyfikacje techniczne, design docs, rejestry decyzji i bazy wiedzy.
- Autor
- PracticalSwan ↗
- Repozytorium
- agent-skills ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 19.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 7
- Skrypty
- 1
- Komentarze HTML
- 4
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 19.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
- SKILL.md zawiera komentarze HTML (4). Nie widać ich w podglądzie Markdown, a model je czyta.
Skrypty: scripts/doc-structure-validator.py
Co robi i kiedy
Tworzy od zera ustrukturyzowane dokumenty: PRD, specyfikacje techniczne, design docs, rejestry decyzji i bazy wiedzy.
Oryginalny opis (EN)
Create structured docs from scratch — PRDs, technical specs, design docs, decision records, knowledge bases. Use when drafting documentation, writing proposals, defining requirements, or planning features.
Jak działa
- Activation Conditions
- Part 2: Context Gathering
- Part 3: Refinement & Structure
- Part 4: Reader Testing
- Part 5: Product Requirements Document (PRD)
- Proposed Solution
- Implementation Plan
- Risk Analysis
- Alternatives Considered
- Success Criteria
Podgląd SKILL.md
--- name: documentation-authoring version: "2.0" last_updated: 2026-09-08 tags: [documentation, authoring, docs, writing, quality] description: "Create structured docs from scratch — PRDs, technical specs, design docs, decision records, knowledge bases. Use when drafting documentation, writing proposals, defining requirements, or planning features." --- # 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: ```markdown ## 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: ```markdown # [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 | Phase | Tasks | Owners | Timeline | |-------|--------|---------|----------| | Phase 1 | | | | | Phase 2 | | | | ### Dependencies - [ ] External APIs or services - [ ] Other teams or systems - [ ] Third-party libraries ## Risk Analysis | Risk | Impact | Probability | Mitigation | |-------|---------|--------------|-------------| | [Risk] | High/Med/Low | High/Med/Low | [Mitigation] | ## Alternatives Considered | Option | Pros | Cons | Why Not Chosen | |--------|-------|-------|-----------------| | Alt 1 | | | | ## 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](../documentation-patterns/SKILL.md#shared-documentation-stack): 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. <!-- MCP:START --> <!-- PORTABILITY:START --> ## 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. <!-- PORTABILITY:END --> ## MCP Availability And Fallback Preferred MCP Server: None required - Fallback prompt: "Use the Documentation Authoring Master skill without MCP. Rely on its local instructions, bundled resources, standard shell or editor tools, and direct verification. Show the evidence used before concluding." - Do not claim an MCP operation was used when the active host does not expose it. - Treat local files, tests, rendered outputs, logs, or screenshots as the fallback evidence path. <!-- MCP:END --> ## 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](./references/document-templates.md) — Templates for PRD, RFC, ADR, Tech Spec, Design Doc, Runbook, Postmortem, KB Article - [Writing Style Guide](./references/writing-style-guide.md) — Technical writing best practices, formatting conventions, and readability ### Scripts - [Doc Structure Validator](./scripts/doc-structure-validator.py) — Python script to validate markdown document quality ### Examples - [PRD Example](./examples/prd-example.md) — 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](../documentation-patterns/SKILL.md) when the structure or template is the main decision. - Finish with [documentation-quality](../documentation-quality/SKILL.md) when the draft needs an explicit review against quality bars. ## Agent Prompt Template ```text 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. ``` ## Related Skills - [documentation-patterns](../documentation-patterns/SKILL.md): Use it when the workflow also needs reusable documentation structures and templates. - [documentation-quality](../documentation-quality/SKILL.md): Use it when the workflow also needs documentation review standards and quality gates. - [documentation-verification](../documentation-verification/SKILL.md): Use it when the workflow also needs final documentation validation before publishing. - [notion-docs](../notion-docs/SKILL.md): Use it when the workflow also needs Notion page and database publishing workflows.
Pliki w paczce (7)
- CHANGELOG.md 7 KB
- LICENSE.txt 1 KB
- SKILL.md 15 KB
- examples/prd-example.md 12 KB
- references/document-templates.md 13 KB
- references/writing-style-guide.md 11 KB
- scripts/doc-structure-validator.py 15 KB
Wersje
W bazie nie ma innych skilli o nazwie documentation-authoring.
Migawka bazy z 13.11.2026 · wersja paczki 8bb77e734c41 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100agent-technical-writer
Specjalizuje się w dokumentacji technicznej: Architecture Decision Records, dokumentacja API, przewodniki migracji, runbooki i bazy wiedzy. - 100docs-coauthor
Współtworzy ustrukturyzowane dokumenty, takie jak specyfikacje, PRD, RFC i propozycje, w trzech etapach: zebranie kontekstu, szkic i test z czytelnikiem. - 100doc-coauthoring
Pomaga pisać dokumentację, propozycje i specyfikacje w uporządkowanym procesie, w którym użytkownik przekazuje kontekst, a treść jest poprawiana iteracyjnie i sprawdzana pod kątem czytelnika. - 95technical-writing
Pisze zrozumiałą dokumentację techniczną: specyfikacje, dokumenty architektury, runbooki, dokumentację API, przewodniki operacyjne i dokumentację dla deweloperów. - 100reference-docs
Opisuje wzorce dokumentacji referencyjnej dla API i symboli: dokumenty referencyjne, tabele parametrów i specyfikacje techniczne. - 100doc-coauthoring
Prowadzi przez wspólne tworzenie dokumentacji: aktualizacja README, dokumenty architektury, propozycje, specyfikacje techniczne, dokumenty decyzyjne, dokumentacja API i opis kodu.