Human Documentation Generator Skill

Human Documentation Generator

Purpose

This skill transforms detailed AI documentation stored in ai/ folder into human-friendly documentation in docs/ folder. It creates summaries, quick starts, and visual diagrams that enable humans to quickly understand and operate complex systems.

Key principle: ai/ folder remains the source of truth (detailed, comprehensive, for AI context). docs/ folder contains human-optimized extracts (summaries, diagrams, quick references).

When to Use This Skill

Use this skill when:

User needs human-readable documentation from AI context docs
AI documentation is too detailed for quick human consumption
System complexity requires visual diagrams for understanding
Need quick start guides or executive summaries
User specifically mentions difficulty following AI documentation
Creating onboarding materials for new team members
Extracting crucial information for operational quick reference

Trigger phrases:

"Create human docs for..."
"I can't follow the AI documentation"
"Make this easier to understand"
"Create a quick start guide"
"Add diagrams to explain..."
"Summarize the AI docs"

Core Principles

1. Parallel Structure Maintained

ai/                          docs/
├── architect/               ├── architect/
│   ├── app/                │   ├── app/
│   │   └── 01_DOC.md       │   │   └── 01_DOC_SUMMARY.md
│   └── src/                │   └── src/
│       └── 01_DOC.md       │       └── 01_DOC_QUICKSTART.md
├── backend/                ├── backend/
├── frontend/               ├── frontend/
└── testing/                └── testing/

Key rule: docs/ mirrors ai/ structure but contains human-optimized versions

2. Three Human-Friendly Formats

For each AI doc, create ONE or MORE of:

SUMMARY (*_SUMMARY.md)
- Executive summary (1-2 paragraphs)
- Key points (bullet list)
- Quick decision aids
- 20% of original length
QUICKSTART (*_QUICKSTART.md)
- Step-by-step getting started
- 5-minute read maximum
- Code examples
- Common pitfalls
- Success criteria
DIAGRAMS (*_DIAGRAMS.md)
- Visual representation with Mermaid.js
- Architecture diagrams
- Flow charts
- Sequence diagrams
- Entity relationships

3. Mermaid Diagram Guidelines

Always use Mermaid.js for diagrams (renders in GitHub, VS Code, most markdown viewers):

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]

Diagram types to use:

graph TD - Top-down flowcharts
sequenceDiagram - API/interaction flows
erDiagram - Database schemas
journey - User journeys
stateDiagram-v2 - State machines
gantt - Timelines/roadmaps

See references/mermaid_examples.md for templates

Workflows

Workflow 1: Create Summary from AI Doc

Input: Path to AI documentation file (e.g., ai/architect/app/02_BACKEND_REQUIREMENTS.md)

Process:

Read AI documentation thoroughly
Identify the 20% most crucial information
Create executive summary (2-3 paragraphs)
Extract key points (5-10 bullets)
Add quick reference table
Save to parallel location in docs/ with _SUMMARY.md suffix

Output: docs/architect/app/02_BACKEND_REQUIREMENTS_SUMMARY.md

Template: assets/templates/summary_template.md

Workflow 2: Create Quick Start Guide

Input: Path to AI documentation file

Process:

Read AI documentation
Identify "getting started" path
Create step-by-step instructions (numbered)
Add code snippets/commands
Include success criteria
Add "Next steps" section
Save to parallel location with _QUICKSTART.md suffix

Output: docs/architect/app/02_BACKEND_REQUIREMENTS_QUICKSTART.md

Template: assets/templates/quickstart_template.md

Workflow 3: Create Visual Diagrams

Input: Path to AI documentation file OR topic description

Process:

Read AI documentation
Identify visualizable concepts:
- System architecture
- Data flow
- User journeys
- Database schemas
- Decision trees
Create Mermaid diagrams (2-5 diagrams)
Add explanatory text for each diagram
Save to parallel location with _DIAGRAMS.md suffix

Output: docs/architect/app/02_BACKEND_REQUIREMENTS_DIAGRAMS.md

Template: assets/templates/diagrams_template.md

Workflow 4: Batch Process Entire Folder

Input: Path to AI documentation folder (e.g., ai/architect/app/)

Process:

List all markdown files in folder
For each file, determine best format(s):
- Architecture docs → SUMMARY + DIAGRAMS
- Implementation guides → QUICKSTART
- Specifications → SUMMARY + DIAGRAMS
Create human docs in parallel structure
Generate index README for docs/ folder
Report completion summary

Output: Complete docs/ folder structure

Workflow 5: Update Existing Human Docs

Input: Path to updated AI documentation

Process:

Check if human doc already exists in docs/
If exists, compare modification dates
If AI doc is newer, regenerate human doc
Preserve any manual additions (check for "Manual:" markers)
Save updated human doc

Output: Updated human documentation

Document Format Standards

SUMMARY Format

# [Original Title] - Summary

**Source:** Link to AI doc
**Last Updated:** Date
**Read Time:** X minutes

## Executive Summary

[2-3 paragraphs capturing essence]

## Key Points

- Point 1
- Point 2
- Point 3

## Quick Reference

| Aspect | Detail |
|--------|--------|
| Key 1  | Value  |

## When to Read Full Doc

- Scenario 1
- Scenario 2

[Link to full documentation]

QUICKSTART Format

# [Topic] Quick Start

**Time to complete:** X minutes
**Prerequisites:** List

## Step 1: [Action]

[Instructions + code/commands]

## Step 2: [Action]

[Instructions + code/commands]

## Success Criteria

✅ Checklist item
✅ Checklist item

## Next Steps

- Link to detailed docs
- Related quick starts

## Troubleshooting

**Issue:** Description
**Fix:** Solution

DIAGRAMS Format

# [Topic] Visual Guide

**Source:** Link to AI doc

## Overview Diagram

```mermaid
[diagram code]

Explanation: What this diagram shows

[Specific Aspect] Diagram

[diagram code]

Explanation: What this diagram shows

Legend

Symbol → Meaning


## Integration with Other Skills

**Use with architect skill:**
- Architect creates detailed specs in `ai/architect/`
- Human-docs creates summaries in `docs/architect/`

**Use with business skill:**
- Business creates use cases in `ai/business/`
- Human-docs creates executive summaries

**Use with executive skill:**
- Executive defines strategy
- Human-docs creates visual roadmaps

**Use with cleanup skill:**
- Cleanup organizes `ai/` folder
- Human-docs regenerates `docs/` structure

## Quality Standards

**Every human doc must have:**
✅ **Clarity** - Understandable without reading AI doc
✅ **Conciseness** - 20% or less of original length (summaries)
✅ **Actionable** - Clear next steps
✅ **Visual** - At least 1 diagram for complex topics
✅ **Navigable** - Links to source and related docs
✅ **Dated** - Last updated timestamp

**Minimum quality threshold: 8/10**

## File Naming Conventions

AI doc: ai/folder/FILE.md Summary: docs/folder/FILE_SUMMARY.md Quickstart: docs/folder/FILE_QUICKSTART.md Diagrams: docs/folder/FILE_DIAGRAMS.md


**Never:**
- Create files in `ai/` (only read from there)
- Replace AI documentation
- Duplicate information across formats

## Maintenance

**When AI docs are updated:**
1. Check `docs/` for corresponding human docs
2. Regenerate if AI doc is newer
3. Update "Last Updated" timestamp
4. Keep change history minimal (humans don't need full changelog)

**Index README regeneration:**
- Create `docs/README.md` with navigation to all human docs
- Group by folder structure
- Add "Quick Links" section

## Common Use Cases

### Use Case 1: New Team Member Onboarding

**Scenario:** New developer needs to understand GabeDA architecture

**Action:**
1. Generate SUMMARY for all `ai/architect/app/` docs
2. Generate DIAGRAMS for key architecture concepts
3. Create `docs/ONBOARDING.md` with curated path
4. Include quick starts for common tasks

### Use Case 2: Executive Review

**Scenario:** Executive needs high-level understanding

**Action:**
1. Generate executive SUMMARY from technical specs
2. Create visual DIAGRAMS of system architecture
3. 1-page maximum with Mermaid diagrams
4. No technical jargon

### Use Case 3: Quick Reference for Developers

**Scenario:** Developer forgets API endpoint structure

**Action:**
1. Create QUICKSTART from API documentation
2. Include code examples
3. Add common patterns
4. Link to full spec

## Examples

**Example 1: Architecture Summary**

Input: `ai/architect/app/02_BACKEND_REQUIREMENTS.md` (14,000 words)
Output: `docs/architect/app/02_BACKEND_REQUIREMENTS_SUMMARY.md` (2,000 words)

**Example 2: Quick Start**

Input: `ai/architect/app/05_CSV_UPLOAD_SPECIFICATION.md`
Output: `docs/architect/app/05_CSV_UPLOAD_QUICKSTART.md`
- 5 steps to implement CSV upload
- Code snippets
- 10-minute read

**Example 3: Visual Guide**

Input: `ai/architect/app/07_WORKFLOWS_AND_DATA_FLOW.md`
Output: `docs/architect/app/07_WORKFLOWS_DIAGRAMS.md`
- Already has diagrams, extract and simplify
- Add annotations
- Create simplified version

## Version History

**v1.0.0** (2025-11-01)
- Initial skill creation
- Support for SUMMARY, QUICKSTART, DIAGRAMS formats
- Mermaid diagram integration
- Parallel folder structure

---

**Last Updated:** 2025-11-01
**Skill Type:** Documentation transformation and visualization

Agent Skills: Human Documentation Generator

Install this agent skill to your local

Skill Files