Document Specialist

# Documentation Specialist Skill **Version**: 3.0-PDA **Status**: Production Ready (PDA-Compliant) **Author**: Created with Claude Code **Last Updated**: 2025-01-13 Transform Claude Code into an expert software documentation specialist with **Progressive Disclosure Architecture (PDA)** for maximum efficiency. --- ## Installation ### One-Click Install via Skilz Marketplace Install this skill instantly from the [Skilz Marketplace](https://skillzwave.ai/skill/SpillwaveSolutions__document-specialist-skill__documentation-specialist__SKILL/): ```bash skilz install SpillwaveSolutions_document-specialist-skill/documentation-specialist ``` ### Manual Installation Clone directly into your Claude Code skills directory: ```bash # Navigate to your skills directory cd ~/.claude/skills # Clone the repository git clone https://github.com/SpillwaveSolutions/document-specialist-skill.git ``` ### Verify Installation After installation, verify the skill is available: ```bash # List installed skills ls ~/.claude/skills/document-specialist-skill # Or ask Claude Code # "List my installed skills" ``` --- ## Overview ### Two Primary Capabilities 1. **Greenfield Documentation**: Create professional documentation from templates for new projects 2. **Brownfield Documentation**: Reverse-engineer documentation from existing codebases ### PDA Architecture (54% Token Reduction) This skill uses **Progressive Disclosure Architecture** to minimize token consumption while maintaining full functionality: - **Core** (Auto-loaded): `SKILL.md` (~2,500 tokens) - Routing, execution logic, and quick start - **On-demand**: Workflow guides, templates, mappings (~10,000 tokens, loaded selectively) **Typical Token Load**: 2,500 tokens (just SKILL.md) to 5,000 tokens (with workflow) = **44-72% reduction vs v1.0** --- ## Key Features ### 1. Template-Based Creation (Greenfield) Create professional documentation from scratch using industry-standard templates: | Document Type | Standard | Status | Use Case | |---------------|----------|--------|----------| | **SRS** (Software Requirements Specification) | IEEE 830 | Complete | Formal requirements, compliance, contracts | | **PRD** (Product Requirements Document) | Agile/Modern | Complete | Feature planning, sprint planning | | **SDD** (Software Design Document) | arc42 | Template | Technical design, architecture | | **OpenAPI** 3.0 | OpenAPI Spec | Complete | REST API documentation | | **User Guides** | - | Template | End-user documentation | | **Deployment Docs** | - | Template | DevOps, infrastructure | ### 2. Code-to-Docs Reverse Engineering (Brownfield) Automatically generate documentation from existing code: **Backend Frameworks:** - **Spring Boot** (Fully mapped) - Controllers to OpenAPI, Entities to ER diagrams, Services to SDD - FastAPI, Express.js, Django, Flask (Planned) **Infrastructure:** - **Pulumi** (Fully mapped) - Resources to deployment docs, architecture diagrams - Terraform, AWS CDK (Planned) **Frontend:** - React, Next.js, Vue.js (Planned) **Data and CLI:** - Python ETL, Apache Airflow, CLIs (Planned) ### 3. Documentation Audit and Quality Control - Automated quality checklists (SRS, PRD, SDD, OpenAPI, User Docs) - Gap analysis and completeness scoring - Best practices validation (IEEE, OpenAPI, WCAG) - Improvement recommendations with examples - Automated fixes for common issues ### 4. Multi-Format Output - **Markdown** (Primary format, Git-friendly) - **DOCX** (Microsoft Word via `docx` skill) - **PDF** (Professional documents via `pdf` skill) - **Diagrams** (Mermaid, PlantUML via skills) ### 5. Visual Documentation **Mermaid Diagrams** (via `mermaid-architect` skill): - C4 Model: Context, Container, Component - Flowcharts and decision trees **PlantUML Diagrams** (via `plantuml` skill): - UML: Class, Sequence, Activity, State Machine - ER Diagrams (database schema) - Deployment diagrams --- ## Quick Start ### Example 1: Create a Requirements Document ``` Create a Software Requirements Specification for a payment processing system ``` **Generates**: IEEE-compliant SRS with functional requirements, NFRs, acceptance criteria ### Example 2: Document Existing Spring Boot App ``` Document my Spring Boot application at ~/projects/ecommerce-api ``` **Generates**: SDD (arc42), OpenAPI spec, C4 diagram, ER diagram, Component diagram ### Example 3: Audit API Documentation ``` Audit my OpenAPI specification at docs/api/openapi.yaml ``` **Generates**: Audit report with quality score, gap analysis, recommendations ### Example 4: Convert to Multiple Formats ``` Convert docs/requirements/billing-srs.md to Word format ``` **Generates**: Professionally styled DOCX with TOC, styles, formatting ### Example 5: Generate Architecture Diagrams ``` Create a C4 container diagram for my e-commerce microservices platform ``` **Generates**: C4 container diagram showing services, databases, external systems --- ## Directory Structure (PDA v3.0) ``` documentation-specialist/ |-- SKILL.md # Core routing logic + quick start (2,500 tokens) |-- README.md # This file |-- USER_GUIDE.md # Comprehensive user guide | |-- references/ | |-- workflows/ # On-demand workflow guides | | |-- greenfield-workflow.md # Template-based creation (1,500 tokens) | | |-- brownfield-workflow.md # Code-to-docs extraction (1,500 tokens) | | |-- audit-workflow.md # Documentation review (1,000 tokens) | | |-- convert-workflow.md # Format conversion (750 tokens) | | |-- diagram-workflow.md # Diagram generation (1,000 tokens) | | |-- user-docs-workflow.md # User documentation | | |-- tutorial-workflow.md # Tutorial creation | | |-- runbook-workflow.md # Operational runbooks | | +-- TOC.md # Navigation index | | | |-- templates/ # Document templates | | +-- markdown/ | | |-- requirements-srs.md # IEEE SRS (600+ lines) | | |-- requirements-prd.md # Agile PRD (500+ lines) | | |-- api-openapi.yaml # OpenAPI 3.0 (800+ lines) | | |-- user-manual.md # User manual template | | |-- howto-guide.md # How-to guide template | | |-- getting-started.md # Getting started template | | |-- developer-tutorial.md # Developer tutorial | | +-- runbook.md # Runbook template | | | |-- mappings/ # Code-to-docs mappings | | +-- backend/ | | |-- spring-boot-mapping.yaml # Complete | | +-- fastapi-mapping.yaml # Complete | | | |-- reference/ # Reference guides | | |-- comprehensive-guide.md # Navigation to all 27 guides | | +-- 01-philosophy.md # Docs-as-code principles | | | +-- examples/ # Example documentation | |-- TOC.md # Navigation to all examples | |-- greenfield/ # Template-based examples | +-- brownfield/ # Code-to-docs examples ``` --- ## How It Works (PDA Flow) ### User Request Flow **Example**: "Create an SRS for a billing system" 1. **Auto-Load**: `SKILL.md` classifies intent as CREATE_NEW (2,500 tokens) 2. **Selective Load**: - `workflows/greenfield-workflow.md` (1,500 tokens) - `templates/markdown/requirements-srs.md` (500 tokens) 3. **Execute**: Generate customized SRS 4. **Total Tokens**: 4,500 (vs 9,000 in v1.0) = **50% reduction** ### Intent Classification The skill automatically classifies your request into one of eight intents: | Intent | Trigger Keywords | Workflow Loaded | Typical Tokens | |--------|-----------------|----------------|----------------| | **CREATE_NEW** | "create", "generate", "write" + doc type | greenfield-workflow.md | ~4,000 | | **CODE_TO_DOCS** | "document", "extract", path reference