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.
Install this skill instantly from the Skilz Marketplace:
skilz install SpillwaveSolutions_document-specialist-skill/documentation-specialistClone directly into your Claude Code skills directory:
# Navigate to your skills directory
cd ~/.claude/skills
# Clone the repository
git clone https://github.com/SpillwaveSolutions/document-specialist-skill.gitAfter installation, verify the skill is available:
# List installed skills
ls ~/.claude/skills/document-specialist-skill
# Or ask Claude Code
# "List my installed skills"- Greenfield Documentation: Create professional documentation from templates for new projects
- Brownfield Documentation: Reverse-engineer documentation from existing codebases
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
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 |
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)
- 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
- Markdown (Primary format, Git-friendly)
- DOCX (Microsoft Word via
docxskill) - PDF (Professional documents via
pdfskill) - Diagrams (Mermaid, PlantUML via skills)
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
Create a Software Requirements Specification for a payment processing system
Generates: IEEE-compliant SRS with functional requirements, NFRs, acceptance criteria
Document my Spring Boot application at ~/projects/ecommerce-api
Generates: SDD (arc42), OpenAPI spec, C4 diagram, ER diagram, Component diagram
Audit my OpenAPI specification at docs/api/openapi.yaml
Generates: Audit report with quality score, gap analysis, recommendations
Convert docs/requirements/billing-srs.md to Word format
Generates: Professionally styled DOCX with TOC, styles, formatting
Create a C4 container diagram for my e-commerce microservices platform
Generates: C4 container diagram showing services, databases, external systems
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
Example: "Create an SRS for a billing system"
- Auto-Load:
SKILL.mdclassifies intent as CREATE_NEW (2,500 tokens) - Selective Load:
workflows/greenfield-workflow.md(1,500 tokens)templates/markdown/requirements-srs.md(500 tokens)
- Execute: Generate customized SRS
- Total Tokens: 4,500 (vs 9,000 in v1.0) = 50% reduction
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 | brownfield-workflow.md | ~5,000 |
| AUDIT | "audit", "review", "check", "improve" | audit-workflow.md | ~4,000 |
| CONVERT | "convert", "transform", "to Word/PDF" | convert-workflow.md | ~3,500 |
| DIAGRAM | "diagram", "C4", "sequence", "visualize" | diagram-workflow.md | ~4,200 |
| USER_DOCS | "user manual", "how-to", "getting started" | user-docs-workflow.md | ~3,500 |
| TUTORIAL | "tutorial", "API guide", "CLI docs" | tutorial-workflow.md | ~3,500 |
| RUNBOOK | "runbook", "procedure", "incident" | runbook-workflow.md | ~3,500 |
This skill seamlessly integrates with other Claude Code skills:
| Skill | Purpose | Auto-Invoked? | Use Case |
|---|---|---|---|
| docx | Word document creation/conversion | Yes when requested | MD to DOCX conversion, professional styling |
| PDF generation | Yes when requested | MD/DOCX to PDF, documentation packages | |
| plantuml | UML diagram generation | Yes for UML diagrams | ER, sequence, class, state machine diagrams |
| mermaid-architect | C4 diagram generation | Yes for C4 diagrams | System context, container, component diagrams |
Auto-invocation: The skill automatically calls these skills when needed, you do not need to invoke them manually.
This skill follows Docs-as-Code principles:
- Living Documentation: Update docs in the same commit as code changes
- Minimum Viable Documentation: Small, fresh, accurate docs over large stale docs
- The Bonsai Tree Principle: Alive but frequently trimmed
- Audience-Specific: Different docs for stakeholders, developers, users
- Git-Friendly: Markdown primary format, version controlled with code
Scenario: Building a new SaaS product, need documentation from day one.
Commands:
1. Create a PRD for a team collaboration platform with real-time messaging
2. Create an SRS for the billing module (high-risk, compliance-critical)
3. Generate an arc42 architecture document for microservices
4. Create OpenAPI spec for the REST API
Result: Complete documentation suite ready for development kickoff.
Scenario: Inherited a Spring Boot application with zero documentation.
Command:
Document my Spring Boot application at ~/projects/customer-api
Result:
- Software Design Document (arc42 format, 20+ pages)
- OpenAPI specification (extracted from @RestController classes)
- C4 Container diagram (shows architecture)
- Component diagram (shows layer structure)
- ER diagram (from @Entity classes)
- Sequence diagrams (for key workflows)
Scenario: Company needs formal documentation for SOC 2 compliance.
Commands:
1. Create a formal SRS for our payment processing system
2. Audit the SRS for completeness
3. Convert to Word format with professional styling
4. Generate PDF documentation package
Result: Enterprise-grade, audit-ready documentation.
Scenario: Need to document API for external developers.
Commands:
1. Extract OpenAPI spec from my FastAPI application at ~/api
2. Audit the OpenAPI spec for best practices
3. Create sequence diagrams for key API workflows
4. Convert to PDF for distribution
Result: Professional API documentation ready for developer portal.
Override default templates:
Use my custom SRS template at templates/my-company-srs.md for this project
The skill will use your template instead of the default.
To add support for a new framework:
- Create
mappings/{category}/{framework}-mapping.yaml - Define detection patterns, extraction rules
- Test with real codebase
See mappings/backend/spring-boot-mapping.yaml for a complete example.
Solution: Verify detection files exist:
# For Spring Boot:
ls pom.xml build.gradle
grep -r "@SpringBootApplication" src/If detection fails, manually specify:
Document this as a Spring Boot application at [path]
Solution: Provide more context in your request:
Generic:
Create an SRS for an app
Specific (Better):
Create an SRS for a HIPAA-compliant telemedicine app with video consultations,
prescription management, and EHR integration. Must support 10,000 concurrent users.
Solution: Ensure required skills are installed:
/skill mermaid-architect
/skill plantuml
Solution: Ensure format conversion skills are installed:
/skill docx
/skill pdf
| Metric | v1.0 | v3.0-PDA | Improvement |
|---|---|---|---|
| SKILL.md size | 954 lines | ~140 lines | 85% reduction |
| Typical token load | ~9,000 | ~4,140 | 54% reduction |
| Initial load | 4,770 tokens | 2,750 tokens | 42% reduction |
| Workflow files | 1 monolithic | 8 focused | Better organization |
- Complete React mapping
- Terraform infrastructure mapping
- Additional reference guides
- More brownfield examples
- Confluence integration
- Multi-language support (ES, FR, DE)
- Custom template system
- Documentation validation/linting
- Automated change detection
- Interactive documentation websites
- Documentation testing (docs as tests)
- AI-powered gap analysis
- Continuous documentation generation
To improve this skill:
- Add new mappings: Create YAML files in
mappings/ - Add examples: Contribute real-world brownfield examples
- Improve templates: Enhance templates in
templates/markdown/ - Improve guides: Update workflow guides in
workflows/ - Report issues: Document bugs and limitations
- Quick Start: See examples above
- User Guide:
USER_GUIDE.md(comprehensive feature documentation)
- PDA Architecture: Understand token optimization details
- Workflow Guides:
references/workflows/*.md(detailed execution workflows) - Reference Guides:
references/reference/*.md(best practices, philosophy)
- Mappings:
references/mappings/backend/spring-boot-mapping.yaml(code-to-docs example) - Templates:
references/templates/markdown/*.md(document structure examples)
| Task | Command Example |
|---|---|
| Create SRS | Create an SRS for [project description] |
| Create PRD | Create a PRD for [feature description] |
| Document code | Document my [framework] app at [path] |
| Extract API docs | Generate OpenAPI spec from [path] |
| Audit docs | Audit my [doc type] at [path] |
| Convert format | Convert [file] to [Word/PDF] |
| Create diagram | Create a [diagram type] for [system] |
| Package docs | Generate PDF package from all docs |
| Create user manual | Create a user manual for [product] |
| Create tutorial | Create a tutorial for [topic] |
| Create runbook | Create a runbook for [procedure] |
This skill synthesizes best practices from:
- Industry standards (IEEE, ISO, OpenAPI)
- Open-source documentation projects
- Enterprise documentation patterns
- Academic software engineering research
Created to solve a critical problem: software projects have poor or no documentation.
By combining:
- Industry-standard templates
- Automated code-to-docs extraction
- AI-powered content generation
- Multi-format output
- Progressive Disclosure Architecture
We make documentation a first-class citizen in the software development lifecycle.
- docx - Microsoft Word document creation
- pdf - PDF generation and manipulation
- plantuml - PlantUML diagram generation
- mermaid-architect - Mermaid diagram creation
Version: 3.0-PDA Last Updated: 2025-01-13 Minimum Claude Code Version: Latest PDA Compliant: Yes (54% token reduction)
Ready to generate world-class software documentation!