Repository Documentation Generator Skill

Repository Documentation Generator

Generate high-quality, consistent documentation following team standards.

Overview

Creates documentation that follows the tiered document requirements, uses proper status indicators, includes visual diagrams, and maintains cross-references between documents.

Document Tiers

Tier 1: Essential (All Projects)

| Document | Purpose | Location | |----------|---------|----------| | CLAUDE.md | AI assistant context for codebase | Root | | README.md | Project overview, quick start | Root | | ARCHITECTURE.md | System architecture with diagrams | docs/ | | DESIGN_DECISIONS.md | Technical rationale, axioms | docs/ |

Tier 2: Operational (Deployed Systems)

| Document | Purpose | Location | |----------|---------|----------| | DEPLOYMENT-[ENV].md | Environment-specific deployment | docs/ | | MONITORING.md | Observability, metrics, alerting | docs/ | | RELIABILITY.md | Fault tolerance, SLAs, recovery | docs/ | | TESTING-STRATEGY.md | Testing approaches, coverage | docs/ |

Tier 3: Supporting (As Needed)

| Document | Purpose | Location | |----------|---------|----------| | AI_ONBOARDING.md | AI assistant quick start | Root | | GITOPS-STRATEGY.md | CI/CD, automation | docs/ | | [TOPIC]-GUIDE.md | Deep-dives on topics | docs/ | | diagrams/README.md | Diagram rendering | docs/diagrams/ |

Universal Document Structure

Every document MUST begin with:

# Document Title

Brief 1-2 sentence description of what this document covers.

## Table of Contents

- [Section 1](#section-1)
- [Section 2](#section-2)

---

## Section 1

Status Indicators

Use consistently throughout all documents:

| Emoji | Meaning | Usage | |-------|---------|-------| | ✅ | Complete/Working | Feature complete, test passing | | ⚠️ | Partial/Warning | Needs attention, partial impl | | ❌ | Missing/Failed | Not implemented, blocker | | 📊 | Diagram/Visual | Cross-reference to visual |

Example:

| Component | Status | Notes |
|-----------|--------|-------|
| Auth Service | ✅ Complete | v2.1.0 deployed |
| Rate Limiter | ⚠️ POC Only | Production needs Redis |
| Circuit Breaker | ❌ Not Implemented | Required for prod |

Cross-Reference Pattern

Always link related documents:

> 📊 **Visual Diagram**: See [Architecture Overview](diagrams/architecture-overview.png)

For deployment details, see **[DEPLOYMENT-EKS.md](DEPLOYMENT-EKS.md)**.

**Related Documents:**
- [ARCHITECTURE.md](ARCHITECTURE.md) - System design
- [RELIABILITY.md](RELIABILITY.md) - Fault tolerance

Heading Depth Rules

Maximum 4 levels (# to ####)
Use ## for main sections
Use ### for subsections
Use #### sparingly
Use bold text instead of ##### or ######

Content Patterns

See PATTERNS.md for detailed content patterns:

Axioms Pattern (principles with rationale)
Trade-offs Pattern (pros/cons tables)
Command Examples Pattern (copy-paste ready)
Configuration Pattern (YAML with comments)
Troubleshooting Pattern (symptom-based)
Version History Pattern (evolution tracking)

Visual Standards

Required Diagrams

| Diagram Type | Purpose | Format | |--------------|---------|--------| | Architecture Overview | High-level system | Mermaid | | Component Interaction | Message/data flow | Mermaid Sequence | | Deployment Topology | Infrastructure | Graphviz DOT |

Mermaid Style Guidelines

graph TB
    subgraph "Kubernetes Cluster"
        API["API Container<br/>ASP.NET Core"]
        SM["Sidecar<br/>Go Service"]
    end

    RMQ["RabbitMQ<br/>Message Broker"]
    SM -->|publish| RMQ

    style API fill:#e1f5ff
    style SM fill:#ffe1f5
    style RMQ fill:#fff4e1

Colors:

Blue (#e1f5ff) - APIs
Pink (#ffe1f5) - Services
Yellow (#fff4e1) - Infrastructure

Document Templates

See TEMPLATES.md for complete templates:

CLAUDE.md template
README.md template
ARCHITECTURE.md template
DESIGN_DECISIONS.md template
MONITORING.md template
AI_ONBOARDING.md template

Quality Checklist

See CHECKLIST.md before finalizing any document.

Generation Process

Identify document type - Which tier and template?
Gather context - Read existing code/docs
Apply template - Use appropriate structure
Add diagrams - Mermaid for architecture
Cross-reference - Link related documents
Validate - Run through checklist

Agent Skills: Repository Documentation Generator

Skill Files