Building a Documentation Generator Skill

Good documentation is essential for maintainable software, yet it is often the first thing sacrificed under deadline pressure. A documentation generator skill can help by automatically creating and updating documentation from your codebase, ensuring your docs stay current with minimal effort.

In this tutorial, we will build a documentation generator that scans code, extracts meaningful information, analyzes patterns, and produces comprehensive, well-structured documentation. The skill will handle everything from API references to getting-started guides.

What We Are Building

Our documentation generator will:

1. Scan the codebase to discover documentable elements
2. Extract function signatures, types, and existing comments
3. Analyze code patterns to understand behavior
4. Generate multiple documentation formats
5. Output well-structured, readable documentation

By the end, your skill will transform code like this:

export async function createUser(
  data: CreateUserInput,
  options?: CreateOptions
): Promise<User> {
  // Validate input
  validateUserData(data);

  // Check for existing user
  const existing = await findUserByEmail(data.email);
  if (existing) {
    throw new ConflictError('User already exists');
  }

  // Create and return
  return await db.users.create(data);
}

Into documentation like this:

## createUser

Creates a new user in the system.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| data | CreateUserInput | Yes | User data including email, name, and password |
| options | CreateOptions | No | Optional creation settings |

### Returns

`Promise<User>` - The created user object

### Throws

- `ConflictError` - When a user with the same email already exists

### Example

```typescript
const user = await createUser({
  email: 'user@example.com',
  name: 'John Doe',
  password: 'securepassword'
});

## Prerequisites

Before we begin, you should have:

- Understanding of code structure and documentation patterns
- Familiarity with multiple programming languages
- Basic knowledge of markdown formatting
- Claude Code installed and configured

## Part 1: Architecture Design

Let us design the documentation generator's workflow.

### Processing Pipeline

Codebase → [Scan] → [Extract] → [Analyze] → [Generate] → Documentation

Each stage has specific responsibilities:

```markdown
## Pipeline Stages

### Stage 1: Scan
- Discover all source files
- Identify file types and languages
- Filter by documentation relevance
- Create file manifest

### Stage 2: Extract
- Parse code structure
- Extract function/class signatures
- Collect existing comments/docstrings
- Identify exports and public APIs

### Stage 3: Analyze
- Understand function purposes
- Infer parameter meanings
- Detect patterns and relationships
- Identify examples and use cases

### Stage 4: Generate
- Apply documentation templates
- Format for target output
- Add navigation and structure
- Validate completeness

Output Types

The skill will generate multiple documentation types:

## Documentation Types

### API Reference
- Complete function documentation
- Type definitions
- Parameter descriptions
- Return values and errors

### Getting Started Guide
- Installation instructions
- Basic usage examples
- Quick start code

### Module Overview
- Purpose of each module
- Key concepts
- Architecture description

### Changelog
- Version history
- Breaking changes
- Migration guides

Part 2: Building the Scanner

The scanner discovers what needs to be documented.

Step 1: Create the Scanner Module

---
name: doc-scanner
description: Scans codebase for documentable elements
version: 1.0.0
tools:
  - Glob
  - Read
---

# Documentation Scanner

Scan a codebase to identify all documentable elements.

## Scanning Process

### Step 1: Discover Files

Use Glob to find source files:

Patterns by language:

• TypeScript: **/.ts, **/.tsx
• JavaScript: **/.js, **/.jsx
• Python: **/*.py
• Go: **/*.go
• Rust: **/*.rs

Exclude patterns:
- node_modules/**
- dist/**
- build/**
- **/*.test.*, **/*.spec.*
- **/__mocks__/**

### Step 2: Categorize Files

Group discovered files:

```yaml
categories:
  entryPoints:
    patterns: [index.*, main.*, app.*]
    priority: high

  publicAPI:
    patterns: [src/api/**, lib/**]
    priority: high

  utilities:
    patterns: [src/utils/**, src/helpers/**]
    priority: medium

  types:
    patterns: [src/types/**, **/*.d.ts]
    priority: high

  internal:
    patterns: [src/internal/**]
    priority: low

Step 3: Create Manifest

Output file manifest:

{
  "summary": {
    "totalFiles": 45,
    "byLanguage": {
      "typescript": 40,
      "json": 5
    },
    "byCategory": {
      "publicAPI": 15,
      "utilities": 10,
      "types": 8,
      "internal": 12
    }
  },
  "files": [
    {
      "path": "src/api/users.ts",
      "language": "typescript",
      "category": "publicAPI",
      "priority": "high",
      "size": 2500,
      "exports": ["createUser", "updateUser", "deleteUser"]
    }
  ]
}

Output

File manifest with categorized, prioritized list of files to document.

## Part 3: Building the Extractor

The extractor pulls structured information from code.

### Step 2: Create the Extractor Module

```markdown
---
name: doc-extractor
description: Extracts documentation elements from code
version: 1.0.0
tools:
  - Read
---

# Documentation Extractor

Extract documentable elements from source code files.

## Extraction Targets

### Functions and Methods

Extract:
- Name
- Parameters (name, type, default value)
- Return type
- Async status
- Visibility (public/private)
- Existing JSDoc/docstring

### Classes and Interfaces

Extract:
- Name
- Properties with types
- Methods
- Inheritance
- Generic parameters

### Type Definitions

Extract:
- Type name
- Structure
- Documentation comments
- Related types

### Exports

Extract:
- Exported names
- Export type (named, default, re-export)
- Original location

## Language-Specific Patterns

### TypeScript/JavaScript

```typescript
// Function pattern
export async function name(
  param: Type = default
): ReturnType {

// Class pattern
export class Name extends Base implements Interface {
  property: Type;
  method(): ReturnType {}
}

// Type pattern
export interface Name {
  property: Type;
}

export type Name = Definition;

Python

# Function pattern
def name(param: Type = default) -> ReturnType:
    """Docstring"""

# Class pattern
class Name(Base):
    """Docstring"""

    def method(self) -> ReturnType:
        """Method docstring"""

Extraction Output

For each file, produce:

{
  "file": "src/api/users.ts",
  "elements": [
    {
      "type": "function",
      "name": "createUser",
      "signature": "createUser(data: CreateUserInput, options?: CreateOptions): Promise<User>",
      "async": true,
      "visibility": "public",
      "parameters": [
        {
          "name": "data",
          "type": "CreateUserInput",
          "required": true,
          "description": null
        },
        {
          "name": "options",
          "type": "CreateOptions",
          "required": false,
          "default": null,
          "description": null
        }
      ],
      "returns": {
        "type": "Promise<User>",
        "description": null
      },
      "throws": ["ConflictError"],
      "existingDoc": null,
      "location": {
        "start": 10,
        "end": 25
      }
    }
  ],
  "imports": ["db", "validateUserData", "findUserByEmail", "ConflictError"],
  "exports": ["createUser"]
}

Handling Edge Cases

Missing Types

If types are not explicit, note as "inferred" or "any"

Complex Types

For complex generics, preserve full type string

Overloaded Functions

Extract all overload signatures

Dynamic Exports

Note dynamic patterns, may require manual documentation

## Part 4: Building the Analyzer

The analyzer understands what the code does.

### Step 3: Create the Analyzer Module

```markdown
---
name: doc-analyzer
description: Analyzes code to understand behavior and purpose
version: 1.0.0
---

# Documentation Analyzer

Analyze extracted code elements to understand their purpose and behavior.

## Analysis Tasks

### 1. Purpose Inference

Determine what each element does:

```markdown
Analyze the function/class to understand:
- Primary purpose (what it accomplishes)
- Use cases (when to use it)
- Side effects (what it changes)
- Dependencies (what it relies on)

2. Parameter Analysis

For each parameter:

Determine:
- Purpose: What this parameter controls
- Valid values: What inputs are acceptable
- Effects: How it affects behavior
- Examples: Typical values

3. Return Value Analysis

For return values:

Determine:
- What the return value represents
- Structure of complex returns
- Possible states (success, error, null)
- How to use the return value

4. Error Analysis

For thrown errors:

Identify:
- What conditions trigger errors
- Error types and meanings
- How to handle or prevent

5. Relationship Analysis

Understand connections:

Map:
- Dependencies between functions
- Class hierarchies
- Module relationships
- Common usage patterns

Analysis Output

Enrich extracted data with analysis:

{
  "element": "createUser",
  "analysis": {
    "purpose": "Creates a new user account in the system",
    "useCases": [
      "User registration flow",
      "Admin creating accounts",
      "Bulk user import"
    ],
    "parameters": {
      "data": {
        "purpose": "Contains the user's information for account creation",
        "includes": ["email", "name", "password"],
        "validation": "Email must be unique, password must meet requirements"
      },
      "options": {
        "purpose": "Optional settings for the creation process",
        "includes": ["sendWelcomeEmail", "assignDefaultRole"],
        "default": "Uses system defaults if not provided"
      }
    },
    "returns": {
      "description": "The newly created user object with generated ID and timestamps",
      "structure": {
        "id": "Unique identifier",
        "email": "User's email address",
        "name": "User's display name",
        "createdAt": "Creation timestamp"
      }
    },
    "errors": {
      "ConflictError": "Thrown when email is already registered"
    },
    "sideEffects": [
      "Creates database record",
      "May send welcome email"
    ],
    "relatedFunctions": ["updateUser", "deleteUser", "findUserByEmail"]
  }
}

Analysis Guidelines

Naming Conventions

Use function/variable names as hints:

• "create", "add", "new" → creation operations
• "get", "find", "fetch" → retrieval operations
• "update", "modify", "set" → modification operations
• "delete", "remove" → deletion operations
• "validate", "check", "is" → validation operations

Code Patterns

Recognize common patterns:

• CRUD operations
• Factory patterns
• Builder patterns
• Event handlers
• Middleware

Context Clues

Use context for understanding:

• File/folder location
• Import statements
• Surrounding code
• Test files (if available)

## Part 5: Building the Generator

The generator produces the final documentation.

### Step 4: Create the Generator Module

```markdown
---
name: doc-generator
description: Generates formatted documentation from analyzed code
version: 1.0.0
tools:
  - Write
---

# Documentation Generator

Generate well-formatted documentation from analyzed code elements.

## Output Formats

### Markdown (Default)

```markdown
# API Reference

## Functions

### createUser

Creates a new user account in the system.

**Signature:**
```typescript
createUser(data: CreateUserInput, options?: CreateOptions): Promise<User>

Parameters:

Returns:

Promise<User> - The newly created user object

Throws:

• ConflictError - When email is already registered

Example:

const user = await createUser({
  email: 'user@example.com',
  name: 'John Doe',
  password: 'securepassword'
});
console.log(user.id);

### JSDoc Format

For inline documentation:

```typescript
/**
 * Creates a new user account in the system.
 *
 * @param data - User information for account creation
 * @param options - Optional creation settings
 * @returns The newly created user object
 * @throws ConflictError When email is already registered
 *
 * @example
 * const user = await createUser({
 *   email: 'user@example.com',
 *   name: 'John Doe',
 *   password: 'securepassword'
 * });
 */

Document Structure

API Reference Structure

# API Reference

## Table of Contents
- [Module: users](#module-users)
- [Module: auth](#module-auth)

---

## Module: users

User management functions.

### Functions

#### createUser
[Full documentation]

#### updateUser
[Full documentation]

---

## Types

### User
[Type documentation]

### CreateUserInput
[Type documentation]

Getting Started Structure

# Getting Started

## Installation

```bash
npm install package-name

Quick Start

import { createUser } from 'package-name';

const user = await createUser({
  email: 'user@example.com',
  name: 'John Doe'
});

Basic Concepts

Users

[Concept explanation]

Authentication

[Concept explanation]

Next Steps

• API Reference
• Advanced Usage

## Generation Rules

### Formatting
- Use consistent heading levels
- Include code syntax highlighting
- Add navigation links
- Use tables for parameters

### Content Quality
- Write in active voice
- Be concise but complete
- Include practical examples
- Explain the "why" not just "what"

### Organization
- Group related items
- Order by importance/usage
- Maintain consistent structure
- Add cross-references

## Output

Write generated documentation to specified files:
- docs/api-reference.md
- docs/getting-started.md
- docs/modules/*.md

Part 6: Complete Skill Integration

Now let us combine everything into the main skill.

Step 5: Create the Main Skill

---
name: documentation-generator
description: Automatically generates comprehensive documentation from code
version: 1.0.0
tools:
  - Glob
  - Read
  - Write
  - Grep
arguments:
  - name: path
    type: string
    default: "."
    description: Root path to document
  - name: output
    type: string
    default: "docs"
    description: Output directory for documentation
  - name: format
    type: string
    default: "markdown"
    options: [markdown, jsdoc, both]
    description: Output format
  - name: include
    type: string
    description: Glob pattern for files to include
  - name: exclude
    type: string
    description: Glob pattern for files to exclude
---

# Documentation Generator

Automatically generate comprehensive documentation from your codebase.

## Workflow

### Phase 1: Discovery

Scan the codebase:
1. Find all source files matching patterns
2. Categorize by type and priority
3. Create documentation manifest

### Phase 2: Extraction

For each relevant file:
1. Read file contents
2. Parse code structure
3. Extract functions, classes, types
4. Collect existing documentation

### Phase 3: Analysis

For each extracted element:
1. Infer purpose from name and code
2. Analyze parameters and returns
3. Identify errors and side effects
4. Map relationships

### Phase 4: Generation

Create documentation:
1. Apply templates to analyzed data
2. Generate API reference
3. Generate getting started guide
4. Generate module documentation

### Phase 5: Output

Write documentation:
1. Create output directory structure
2. Write markdown files
3. Generate table of contents
4. Validate links

## Configuration

### Default Include Patterns

src//*.ts src//.tsx lib/**/.ts

### Default Exclude Patterns

/.test.ts **/.spec.ts /tests/ /mocks/ node_modules/ dist/**

## Output Structure

docs/ ├── README.md # Overview and navigation ├── getting-started.md # Quick start guide ├── api-reference.md # Complete API documentation ├── modules/ │ ├── users.md # User module documentation │ ├── auth.md # Auth module documentation │ └── ... └── types.md # Type definitions

## Error Handling

### Parse Errors
- Log problematic files
- Continue with other files
- Note incomplete documentation

### Missing Types
- Use "unknown" or inferred types
- Flag for manual review

### Complex Patterns
- Document what can be analyzed
- Note areas needing manual documentation

## Quality Checks

Before output:
- [ ] All public exports documented
- [ ] No broken internal links
- [ ] Examples are syntactically valid
- [ ] Consistent formatting throughout
- [ ] Table of contents accurate

## Example Usage

```bash
# Generate docs for current project
/documentation-generator

# Generate docs for specific path
/documentation-generator --path src/api

# Generate with JSDoc format
/documentation-generator --format jsdoc

# Custom output location
/documentation-generator --output ./documentation

Output

Comprehensive documentation in the specified format, ready for use.

## Part 7: Testing and Refinement

### Step 6: Test the Complete Skill

```markdown
## Test Cases

### Test 1: Simple Module
Input: Single file with 3 functions
Expected: Complete API documentation with examples

### Test 2: Complex Project
Input: Multi-module project
Expected: Organized documentation with cross-references

### Test 3: TypeScript Project
Input: Typed TypeScript codebase
Expected: Type information preserved in docs

### Test 4: Existing Documentation
Input: Files with existing JSDoc
Expected: Merge and enhance existing docs

### Test 5: Edge Cases
Input: Complex generics, overloads, dynamic exports
Expected: Graceful handling, notes for manual review

Step 7: Quality Improvements

Add quality enhancements:

## Quality Enhancements

### Example Generation
Generate realistic examples:
- Use meaningful variable names
- Show common use cases
- Include error handling

### Cross-Referencing
Link related items:
- Types used in function signatures
- Related functions in same module
- Implementation details

### Consistency Checking
Verify documentation quality:
- All parameters documented
- Return types explained
- Errors listed
- Examples provided

### Freshness Tracking
Track documentation currency:
- Add generation timestamp
- Note source file hashes
- Flag potentially outdated docs

Conclusion

You have built a comprehensive documentation generator that:

1. Scans codebases to discover documentable elements
2. Extracts structured information from code
3. Analyzes code to understand purpose and behavior
4. Generates well-formatted, comprehensive documentation
5. Outputs multiple documentation formats

This skill demonstrates the Chain pattern, where each stage builds on the previous to produce a sophisticated final result.

Key takeaways:

• Break complex tasks into focused stages
• Extract structure before adding intelligence
• Generate multiple output formats from same analysis
• Handle edge cases gracefully
• Validate output quality

Your documentation generator is ready to keep your docs current with minimal effort!