# Document Specialist

Adopt this skill: https://proskills.md/skills/coding/document-specialist-skill

Page: https://proskills.md/skills/coding/document-specialist-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .gitignore
upstream: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/.gitignore

Content is not inlined in the catalog. Read the upstream file: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/.gitignore

## File: EXAMPLES_CREATION_SUMMARY.md
upstream: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/EXAMPLES_CREATION_SUMMARY.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/EXAMPLES_CREATION_SUMMARY.md

## File: PDA_COMPLETE_SUMMARY.md
upstream: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/PDA_COMPLETE_SUMMARY.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/PDA_COMPLETE_SUMMARY.md

## File: PDA_REORGANIZATION_PLAN.md
upstream: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/PDA_REORGANIZATION_PLAN.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/PDA_REORGANIZATION_PLAN.md

## File: README.md
upstream: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/README.md

````text
# 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](https://skillzwave.ai/skill/SpillwaveSolutions__document-specialist-skill__documentation-specialist__SKILL/):

```bash
skilz install SpillwaveSolutions_document-specialist-skill/documentation-specialist
```

### Claude Code plugin

```bash
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:

```text
.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](docs/HOSTS.md) for the four-host matrix.

### 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 | Complete | Technical design, architecture. Default file is DESIGN_DOC.md |
| **OpenAPI** 3.0 | OpenAPI Spec | Complete | REST API documentation |
| **Architecture** (C4 short) | C4 | Complete | Context, containers, sequence, deployment. Default file is docs/architecture.md |
| **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 `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
|   |
````

## File: RELEASE_NOTES_v2.1.0.md
upstream: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/RELEASE_NOTES_v2.1.0.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/RELEASE_NOTES_v2.1.0.md

## File: RELEASE_NOTES_v3.0.0.md
upstream: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/RELEASE_NOTES_v3.0.0.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/RELEASE_NOTES_v3.0.0.md

## File: SKILL.md
upstream: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/SKILL.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/SKILL.md

## File: USER_GUIDE.md
upstream: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/USER_GUIDE.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/USER_GUIDE.md

## File: references
upstream: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/references

Content is not inlined in the catalog. Read the upstream file: https://github.com/spillwavesolutions/document-specialist-skill/blob/HEAD/references