What inputs are required?

OpenAPI/AsyncAPI specs, architecture mappings, migration notes, and any runbook templates or templates for guides.

What outputs are produced and where do they go?

API docs, architecture diagrams, runbooks, migration guides, change notes, and site-ready artifacts (HTML, PDF). Outputs can be published to MkDocs or Backstage.

Which tools are supported and how does integration work?

Swagger UI, AsyncAPI, PlantUML, Mermaid, MkDocs, and Backstage integrations via CLI or config-driven workflows.

documentation-generator

npx machina-cli add skill a5c-ai/babysitter/documentation-generator --openclaw

Files (1)

SKILL.md

2.4 KB

Documentation Generator Skill

Generates comprehensive documentation for migrated systems including API documentation, architecture diagrams, and operational runbooks.

Purpose

Enable documentation creation for:

API documentation generation
Architecture documentation
Runbook generation
Change documentation
Diagram generation

Capabilities

1. API Documentation Generation

Generate from OpenAPI specs
Create interactive docs
Include examples
Support versioning

2. Architecture Documentation

Create architecture diagrams
Document components
Map dependencies
Explain patterns

3. Runbook Generation

Create operational procedures
Document troubleshooting
Include escalation paths
Generate playbooks

4. Change Documentation

Document migration changes
Track before/after
Note breaking changes
Generate release notes

5. Migration Guide Creation

Create upgrade guides
Document migration steps
Include rollback procedures
Provide checklists

6. Diagram Generation

Generate architecture diagrams
Create sequence diagrams
Build data flow diagrams
Produce deployment diagrams

Tool Integrations

Tool	Purpose	Integration Method
Swagger UI	API docs	CLI
AsyncAPI	Event docs	CLI
PlantUML	Diagrams	CLI
Mermaid	Diagrams	Markdown
Backstage	Developer portal	Config
MkDocs	Documentation site	CLI

Output Schema

{
  "generationId": "string",
  "timestamp": "ISO8601",
  "documentation": {
    "api": {
      "path": "string",
      "format": "string"
    },
    "architecture": {
      "path": "string",
      "diagrams": []
    },
    "runbooks": [],
    "guides": []
  },
  "artifacts": {
    "site": "string",
    "pdfs": [],
    "diagrams": []
  }
}

Integration with Migration Processes

documentation-migration: Primary doc generation
All migration processes (change documentation)

Related Skills

openapi-generator: API spec generation
knowledge-extractor: Source material

Related Agents

documentation-migration-agent: Doc orchestration
operational-readiness-agent: Runbook creation

Source

git clone https://github.com/a5c-ai/babysitter/blob/main/plugins/babysitter/skills/babysit/process/specializations/code-migration-modernization/skills/documentation-generator/SKILL.md

View on GitHub

Overview

Generates comprehensive documentation for migrated systems, including API docs, architecture diagrams, and operational runbooks. It orchestrates API spec-driven docs, architecture diagrams, and migration guides to capture changes and support onboarding. Outputs structured artifacts ready for deployment to docs sites and PDFs.

How This Skill Works

Inputs like OpenAPI specs, architecture mappings, and migration notes are consumed to generate API docs, architecture diagrams, and runbooks. The process leverages Swagger UI/AsyncAPI for API docs, PlantUML/Mermaid for diagrams, and formats outputs into runbooks, migration guides, and site-ready artifacts (MkDocs/Backstage).

When to Use It

When migrating systems and you need API/docs, architecture diagrams, and runbooks generated from source specs.
When OpenAPI or AsyncAPI specs exist and you want interactive/API docs and versioned changes.
When you must document migration changes, including before/after state and release notes.
When you need upgrade guides, rollback procedures, and checklists for a safe migration.
When publishing a developer-friendly documentation site or portal (Backstage/MkDocs) with all artifacts.

Quick Start

Step 1: Provide inputs (OpenAPI/AsyncAPI specs, architecture components, and migration notes).
Step 2: Run the documentation generator to produce API docs, diagrams, runbooks, and guides.
Step 3: Export to your docs site (MkDocs/Backstage) and share via PDFs or a deployed portal.

Best Practices

Use OpenAPI/AsyncAPI as authoritative sources and generate docs incrementally from those specs.
Version API docs and tie changes to migration milestones to maintain traceability.
Leverage PlantUML and Mermaid for clear diagrams that reflect current architecture and data flows.
Provide runnable runbooks with troubleshooting steps and clearly defined escalation paths.
Organize outputs for site generators (MkDocs or Backstage) to create a discoverable docs portal.

Example Use Cases

Auto-generated API docs from an OpenAPI spec for a migrated microservice with versioned releases.
A set of architecture diagrams mapping components and dependencies after modernization.
A comprehensive runbook suite covering deployment, monitoring, and incident response post-migration.
A migration guide containing upgrade steps, rollback procedures, and checklists.
A MkDocs-based documentation site hosting API docs, diagrams, and runbooks for developer onboarding.

Frequently Asked Questions

Add this skill to your agents