Document Specialist

Documentation Specialist Skill

Version: 3.3.0 Status: Production Ready (PDA-Compliant) Author: Created with Claude Code Last Updated: 2026-08-29

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:

skilz install SpillwaveSolutions_document-specialist-skill/documentation-specialist

Claude Code plugin

claude plugin marketplace add SpillwaveSolutions/document-specialist-skill
claude plugin install document-specialist

Grok Build plugin

Grok Build loads .claude-plugin/ zero-config. Optional pin:

.grok-plugin/plugin.json
.grok-plugin/marketplace.json

Codex plugin

.codex-plugin/plugin.json with "skills": "./skills/". Enable from the Codex plugin UI, or copy the repo into ~/.codex/plugins/.

Cursor plugin

.cursor-plugin/plugin.json. Optional: point .cursor/rules at SKILL.md.

Universal (Agent Plugins 1.0)

Root plugin.json follows https://agent-plugins.org/schemas/1.0.0/plugin.schema.json. Hosts that only speak Agent Plugins 1.0 load skills/documentation-specialist/SKILL.md.

See docs/HOSTS.md for the four-host matrix.

Manual Installation

Clone 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.git

Verify Installation

After installation, verify the skill is available:

# 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:

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 design-doc-mermaid skill, default):

• C4 Model: Context, Container, Component
• Flowcharts, sequence, class, ER, state

PlantUML Diagrams (via plantuml skill, leftover types only):

• Salt wireframes / UI mocks
• Use case, timing, ArchiMate, nwdiag, WBS
• Always PNG or SVG. GitHub wiki does not render PlantUML source.

---

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
|-- plugin.json                        # Agent Plugins 1.0 (universal)
|-- DESIGN_DOC.md                      # arc42 SDD of this skill
|-- README.md                          # This file
|-- USER_GUIDE.md                      # Comprehensive user guide
|-- .claude-plugin/                    # Claude Code plugin + marketplace
|-- .grok-plugin/                      # Grok Build plugin
|-- .codex-plugin/                     # Codex plugin
|-- .cursor-plugin/                    # Cursor plugin
|
|-- references/
|   |-- workflows/                     # On-demand workflow guides
|   |   |-- design-workflow.md        # arc42 DESIGN_DOC.md and C4 architecture.md
|   |   |-- 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/
|   |       |-- DESIGN_DOC.md         # arc42 SDD (default output name)
|   |       |-- architecture.md        # C4-first short architecture
|   |       |-- 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
|   |