Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
ancoleman avatar

Generating Documentation

ancoleman/ai-design-components

  • 50 installs
  • 426 repo stars
  • Updated December 11, 2025
  • ancoleman/ai-design-components

generating-documentation is a Claude skill that generates technical documentation across API docs, code docs, doc sites, ADRs, and diagrams.

About

This skill generates technical documentation across five layers: API docs (OpenAPI/Swagger), code docs (TypeDoc/Sphinx), documentation sites (Docusaurus/MkDocs), Architecture Decision Records, and diagrams (Mermaid/PlantUML). A developer uses it when documenting APIs, libraries, or system architecture, or building developer-facing docs sites. It provides a layer decision framework, a tool-selection matrix, and quick-start templates.

  • Five documentation layers: API, code, sites, ADRs, and diagrams
  • Tool selection matrix (Docusaurus, Swagger/Redoc, TypeDoc, Sphinx, Mermaid)
  • Quick-start templates for OpenAPI, TypeDoc, Sphinx, and Docusaurus

Generating Documentation by the numbers

  • 50 all-time installs (skills.sh)
  • Ranked #809 of 1,879 Documentation skills by installs in the Skillselion catalog
  • Data as of Aug 5, 2026 (Skillselion catalog sync)
At a glance

generating-documentation capabilities & compatibility

Capabilities
documentation generation · api documentation · diagram generation · docs site setup
Use cases
documentation · api development
From the docs

What generating-documentation says it does

Generate comprehensive technical documentation across multiple layers: API documentation, code documentation, documentation sites, architecture decisions, and system diagrams.
SKILL.md
Technical documentation operates at five distinct layers
SKILL.md
npx skills add https://github.com/ancoleman/ai-design-components --skill generating-documentation

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs50
repo stars★ 426
Last updatedDecember 11, 2025
Repositoryancoleman/ai-design-components ↗

What it does

Generating API docs, code docs, doc sites, ADRs, and diagrams for developer-facing documentation.

Who is it for?

Documenting APIs, libraries, and architecture, and building developer-facing docs sites.

Skip if: Non-technical or marketing copy with no code or API to document.

When should I use this skill?

Documenting a REST/GraphQL API, generating code docs, building a docs site, or recording an ADR.

What you get

Generated documentation across the right layers with matching tools and starter templates.

  • OpenAPI spec
  • Code docs
  • Documentation site

By the numbers

  • 5 documentation layers
  • Tool selection matrix spanning Docusaurus, Swagger, TypeDoc, Sphinx, Mermaid

Files

SKILL.mdMarkdownGitHub ↗

Documentation Generation

Generate comprehensive technical documentation across multiple layers: API documentation, code documentation, documentation sites, architecture decisions, and system diagrams.

When to Use This Skill

Use this skill when:

  • Documenting REST or GraphQL APIs with OpenAPI specifications
  • Creating code documentation for libraries (TypeScript, Python, Go, Rust)
  • Building documentation sites for projects or products
  • Recording architectural decisions (ADRs) for system design choices
  • Generating diagrams to visualize system architecture or data flows
  • Setting up automated documentation pipelines in CI/CD

Documentation Layers Overview

Technical documentation operates at five distinct layers:

Layer 1: API Documentation - OpenAPI specs for REST/GraphQL APIs (Swagger UI, Redoc, Scalar) Layer 2: Code Documentation - Generated from code comments (TypeDoc, Sphinx, godoc, rustdoc) Layer 3: Documentation Sites - Comprehensive guides and tutorials (Docusaurus, MkDocs) Layer 4: Architecture Decisions - ADRs using MADR template format Layer 5: Diagrams - Visual architecture (Mermaid, PlantUML, D2)

See references/api-documentation.md, references/code-documentation.md, and references/documentation-sites.md for detailed guides.

Quick Decision Framework

Which Documentation Layer?

API for external consumers?
  → Layer 1: API Documentation (OpenAPI + Swagger UI/Redoc)

Code for maintainers?
  → Layer 2: Code Documentation (TypeDoc/Sphinx/godoc/rustdoc)

Comprehensive guides?
  → Layer 3: Documentation Site (Docusaurus/MkDocs)

Architectural decision?
  → Layer 4: ADR (MADR template)

Visual system design?
  → Layer 5: Diagrams (Mermaid/PlantUML/D2)

Tool Selection Matrix

NeedPrimary ToolBest For
Doc SiteDocusaurusFeature-rich React sites
Doc SiteMkDocs MaterialSimple Python docs
API Docs (Interactive)Swagger UITesting
API Docs (Read-Only)RedocProfessional design
TypeScriptTypeDocAll TS projects
PythonSphinxAll Python projects
GogodocBuilt-in
RustrustdocBuilt-in
DiagramsMermaidAll-purpose

API Documentation Quick Start

Create OpenAPI specification:

openapi: 3.1.0
info:
  title: User API
  version: 1.0.0

servers:
  - url: https://api.example.com/v1

paths:
  /users/{userId}:
    get:
      summary: Get a user
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      required: [id, email, name]
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        name:
          type: string

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

Render with Swagger UI, Redoc, or Scalar. See references/api-documentation.md for complete examples and templates/openapi-template.yaml for starter template.

Code Documentation Quick Start

TypeScript

/**
 * Calculate the sum of two numbers.
 *
 * @param a - The first number
 * @param b - The second number
 * @returns The sum of a and b
 *
 * @example
 * ```typescript
 * const result = add(2, 3);
 * console.log(result); // 5
 * ```
 */
export function add(a: number, b: number): number {
  return a + b;
}

Generate docs:

npm install -D typedoc
npx typedoc --entryPoints src/index.ts --out docs

Python

def calculate_total(items: list[dict], tax_rate: float = 0.0) -> float:
    """Calculate the total price including tax.

    Args:
        items: List of items with 'price' and 'quantity' keys.
        tax_rate: Tax rate as decimal (e.g., 0.1 for 10%).

    Returns:
        Total price including tax.

    Example:
        >>> items = [{'price': 10, 'quantity': 2}]
        >>> calculate_total(items, tax_rate=0.1)
        22.0
    """
    subtotal = sum(item['price'] * item['quantity'] for item in items)
    return subtotal * (1 + tax_rate)

Generate docs:

pip install sphinx sphinx-rtd-theme
sphinx-quickstart docs
cd docs && make html

See references/code-documentation.md for Go and Rust examples.

Documentation Site Quick Start

Docusaurus

npx create-docusaurus@latest my-website classic
cd my-website
npm start

Basic config:

// docusaurus.config.js
module.exports = {
  title: 'My Project',
  url: 'https://docs.example.com',
  themeConfig: {
    navbar: {
      items: [
        {type: 'doc', docId: 'intro', label: 'Docs'},
      ],
    },
  },
  presets: [
    ['@docusaurus/preset-classic', {
      docs: {
        sidebarPath: require.resolve('./sidebars.js'),
      },
    }],
  ],
};

MkDocs

pip install mkdocs mkdocs-material
mkdocs new my-project
mkdocs serve

Basic config:

# mkdocs.yml
site_name: My Project
theme:
  name: material
  features:
    - navigation.tabs
    - search.suggest

plugins:
  - search

nav:
  - Home: index.md
  - Getting Started: getting-started.md

See references/documentation-sites.md for versioning and deployment.

Architecture Decision Records

Use MADR template for recording decisions:

# Use PostgreSQL for Primary Database

* Status: accepted
* Deciders: Engineering Team, CTO
* Date: 2025-01-15

## Context and Problem Statement

Application requires relational database with complex queries,
ACID transactions, JSON support, and full-text search.

## Decision Drivers

* Data integrity (ACID compliance)
* Performance (10K+ queries/second)
* Cost (open-source preferred)
* Features (JSONB, full-text search)

## Considered Options

* PostgreSQL
* MySQL
* Amazon Aurora

## Decision Outcome

Chosen "PostgreSQL" for best balance of features and cost.

### Positive Consequences

* Open-source with no licensing costs
* Advanced features (JSONB, full-text search)
* Strong ACID compliance

### Negative Consequences

* Self-hosting requires DevOps investment
* Horizontal scaling requires changes

Copy full template from templates/adr-template.md. See references/adr-guide.md for workflow and examples/adr/0001-database-selection.md for complete example.

Diagrams Quick Start

Create diagrams with Mermaid:

````markdown

sequenceDiagram
    User->>Frontend: Click "Login"
    Frontend->>API: POST /auth/login
    API->>Database: Verify credentials
    Database-->>API: User found
    API-->>Frontend: JWT token
    Frontend->>User: Redirect to dashboard

````

Mermaid renders in GitHub, Docusaurus, and MkDocs. See references/diagram-generation.md for PlantUML and D2 examples.

Common Patterns

Design-First vs Code-First APIs

Design-First: 1. Write OpenAPI spec 2. Review with stakeholders 3. Generate server stubs 4. Implement handlers

Pros: Contract before implementation, parallel development Cons: Spec authoring can be verbose

Code-First: 1. Implement API with decorators 2. Generate OpenAPI from code 3. Publish documentation

Pros: Faster development, spec matches code Cons: Documentation lags behind

Recommendation: Design-first for new APIs, code-first for existing.

Embedding API Docs in Sites

Docusaurus integration:

// docusaurus.config.js
plugins: [
  ['docusaurus-plugin-openapi-docs', {
    config: {
      api: {
        specPath: 'openapi/api.yaml',
        outputDir: 'docs/api',
      },
    },
  }],
],
themes: ['docusaurus-theme-openapi-docs'],

See references/api-documentation.md for MkDocs integration.

CI/CD Automation

# .github/workflows/docs.yml
name: Documentation

on:
  push:
    branches: [main]

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4

      - name: Generate API docs
        run: npm run docs:api

      - name: Generate code docs
        run: npm run docs:code

      - name: Build site
        run: npm run docs:build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

See references/ci-cd-integration.md for validation and versioning.

When to Write an ADR

Write ADRs for:

✅ Technology selection (database, framework, cloud) ✅ Architecture patterns (microservices, event-driven) ✅ Decisions with trade-offs (pros/cons) ✅ Team alignment needed

Don't write ADRs for:

❌ Trivial decisions (naming, formatting) ❌ Easily reversible (config tweaks) ❌ Implementation details (document in code)

See references/adr-guide.md for workflow and examples.

Reference Documentation

For detailed guides:

  • `references/api-documentation.md` - OpenAPI, Swagger UI, Redoc, Scalar, design-first vs code-first
  • `references/code-documentation.md` - TypeDoc, Sphinx, godoc, rustdoc with examples
  • `references/documentation-sites.md` - Docusaurus and MkDocs setup, versioning, deployment
  • `references/adr-guide.md` - MADR template, workflow, when to write ADRs
  • `references/diagram-generation.md` - Mermaid, PlantUML, D2 syntax and integration
  • `references/ci-cd-integration.md` - Automation, validation, deployment strategies

Templates

  • `templates/adr-template.md` - MADR template for Architecture Decision Records
  • `templates/openapi-template.yaml` - OpenAPI 3.1 specification starter

Examples

  • `examples/openapi/` - Complete OpenAPI specifications
  • `examples/typescript/` - TypeDoc configuration and TSDoc examples
  • `examples/python/` - Sphinx configuration and docstring examples
  • `examples/adr/` - Real-world Architecture Decision Records
  • `examples/diagrams/` - Mermaid, PlantUML, D2 examples

Tool Recommendations

Based on research (December 2025):

Documentation Sites:

  • Docusaurus - React-based, feature-rich (versioning, i18n, search)
  • MkDocs Material - Python-based, simple, beautiful

API Documentation:

  • Swagger UI - Interactive testing
  • Redoc - Beautiful read-only
  • Scalar - Modern 2025 design

Code Documentation:

  • TypeScript: TypeDoc
  • Python: Sphinx
  • Go: godoc (built-in)
  • Rust: rustdoc (built-in)

Diagrams:

  • Mermaid - Most popular, GitHub-integrated
  • PlantUML - UML standard
  • D2 - Modern, declarative

Integration with Other Skills

  • `api-patterns` - API implementation and documentation
  • `building-ci-pipelines` - Automate documentation generation
  • `testing-strategies` - Document test patterns
  • `sdk-design` - Generate SDK documentation

Best Practices

1. Docs-as-Code - Keep docs in version control 2. Single Source of Truth - Generate from code/specs 3. Automation - Generate in CI/CD pipelines 4. Examples - Include working code examples 5. Validation - Lint Markdown, validate specs 6. Versioning - Version docs with releases 7. Consistency - Use consistent terminology 8. Maintenance - Update when code changes

Common Pitfalls

Documentation Drift - Docs become outdated → Automate generation, validate in CI/CD

Over-Documentation - Documenting obvious behavior → Focus on "why" not "what"

Fragmented Docs - Information scattered → Single site with clear navigation

No Examples - Theory without practice → Include runnable examples

Related skills

open.feishu.cnLark MarkdownInstantly turn any markdown file into clean, formatted Lark/Figma-compatible documents without manual reformatting.488klarksuiteLark DocCreate, read, update, summarize, rewrite and manage Feishu/Lark cloud documents directly from agent workflows.401k16.1klarksuiteLark WikiCreate, organize, query, and manage documents, spaces, and members inside Lark (Feishu) knowledge bases directly from AI agent workflows.397k16.1kmattpocockDomain ModelingBuild and sharpen a project's domain model: pin down domain terminology in a glossary and record architectural decisions as ADRs.318k202kxixu-meOpensource Guide CoachGet expert, attribution-safe guidance on launching and sustaining an open-source project.270k71xixu-meReadme I18nMaintain consistent, updatable language selector blocks across every README variant in a multilingual repository.270k71

FAQ

Which tool for a feature-rich docs site?

Docusaurus for feature-rich React sites, or MkDocs Material for simpler Python docs.

What are the five documentation layers?

API documentation, code documentation, documentation sites, architecture decisions (ADRs), and diagrams.

Documentationdocsbackend
Browse by category
AI & AgentsFrontend & DesignBackend & DataDev ToolsAutomationTesting & ReviewSecurityMonitoring & CloudDocs & Planning
Design & frontend
Design systemsAnimation & motionAccessibility (a11y)CSS & TailwindUI designUXDesign to codeshadcn/uiLanding pagesBest design skills
Most searched skills
find-skillscavemanfrontend-designbrainstormingsystematic-debuggingstop-slopemil-design-engui-ux-pro-maxkarpathy-guidelinesweb-design-guidelinesreact-best-practicesgrill-meimprovemicrosoft-foundryagent-browser
Browse all listings
All agent skillsAll MCP serversAll marketplacesAll plugins

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.