Documentation Skills Roundup: Which One Fits Your Stack?

Documentation is the eternal challenge of software development. Everyone agrees it's important. Nobody has enough time to write it. And when it does exist, it's often out of date by the time anyone reads it.

Claude Code documentation skills attack this problem by automating the tedious parts of documentation while preserving human judgment for the parts that matter. In this roundup, we'll examine the major approaches to documentation skills and help you choose the right tools for your project.

The Documentation Dilemma

Documentation fails for predictable reasons:

Time Cost: Writing good documentation takes significant effort, often as much as writing the code itself.

Maintenance Burden: Code changes but documentation doesn't. Drift makes docs worse than no docs.

Format Friction: Different tools expect different formats. Converting between them wastes time.

Audience Mismatch: Developer docs, user guides, and API references need different approaches.

Effective documentation skills address one or more of these challenges, automating what can be automated while maintaining quality where it matters.

Skill Category 1: API Documentation

API docs are the most automatable documentation type because they derive from code structure.

openapi-generator

Generates OpenAPI specifications from code:

# OpenAPI Generator

Generate OpenAPI 3.0 specifications from code analysis.

## Supported Frameworks

- Express.js (Node.js)
- FastAPI (Python)
- Spring Boot (Java)
- Go Chi/Gin
- Rails (Ruby)

## Process

1. Analyze route definitions
2. Extract endpoint metadata:
   - HTTP method
   - Path and parameters
   - Request body schema
   - Response schemas
3. Infer types from code/annotations
4. Generate OpenAPI YAML/JSON

## Example Output

```yaml
openapi: 3.0.3
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserInput'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Validation error

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        createdAt:
          type: string
          format: date-time

### Strengths

- **Always accurate**: Generated from actual code
- **Comprehensive**: Captures all endpoints
- **Standard format**: OpenAPI works with many tools
- **Tooling ecosystem**: Swagger UI, Postman, client generators

### Limitations

- **Description quality**: Can't infer what endpoints DO, only what they accept
- **Example data**: Needs manual enhancement for meaningful examples
- **Error documentation**: Error cases need human description

### Best For

REST API documentation. Teams using OpenAPI tooling. Auto-generating API clients.

### graphql-documenter

Documents GraphQL schemas:

```markdown
# GraphQL Documenter

Generate documentation for GraphQL schemas.

## Analysis

From GraphQL schema:
- Types and their fields
- Queries and mutations
- Arguments and return types
- Deprecations and directives

## Output Formats

### Markdown Documentation

```markdown
# GraphQL API Reference

## Types

### User

Represents a registered user.

| Field | Type | Description |
|-------|------|-------------|
| id | ID! | Unique identifier |
| email | String! | User's email address |
| profile | Profile | User's profile information |
| createdAt | DateTime! | When the user was created |

### Profile

User profile information.

| Field | Type | Description |
|-------|------|-------------|
| name | String | Display name |
| avatar | String | Avatar URL |
| bio | String | User biography |

## Queries

### user(id: ID!): User

Fetch a single user by ID.

**Arguments:**
- `id` (ID!, required): The user's unique identifier

**Returns:** User or null if not found

**Example:**
```graphql
query {
  user(id: "123") {
    email
    profile {
      name
    }
  }
}

Mutations

createUser(input: CreateUserInput!): User!

Create a new user account.

### Interactive Documentation
Generate GraphQL Playground/GraphiQL configuration with schema.

jsdoc-generator

Generates JSDoc comments for JavaScript/TypeScript:

# JSDoc Generator

Generate JSDoc comments for code documentation.

## Process

1. Analyze function signatures
2. Infer parameter purposes from names
3. Determine return types from implementation
4. Identify thrown exceptions
5. Generate JSDoc blocks

## Example

Input:
```typescript
function createOrder(userId, items, options) {
  if (!userId) throw new Error('User ID required')
  if (!items.length) throw new Error('Cart is empty')

  const order = {
    id: generateId(),
    userId,
    items: items.map(validateItem),
    total: calculateTotal(items, options?.discount),
    status: 'pending',
    createdAt: new Date()
  }

  return saveOrder(order)
}

Output:

/**
 * Creates a new order for a user with the specified items.
 *
 * @param {string} userId - The unique identifier of the user placing the order
 * @param {Array<OrderItem>} items - Array of items to include in the order
 * @param {Object} [options] - Optional order configuration
 * @param {number} [options.discount] - Discount percentage to apply
 * @returns {Promise<Order>} The created order object
 * @throws {Error} If userId is not provided
 * @throws {Error} If items array is empty
 *
 * @example
 * const order = await createOrder('user-123', [
 *   { productId: 'prod-1', quantity: 2 },
 *   { productId: 'prod-2', quantity: 1 }
 * ], { discount: 10 })
 */
function createOrder(userId, items, options) {
  // ...
}

Bulk Generation

Run across codebase:

• Analyze all exportable functions
• Generate JSDoc for undocumented ones
• Update outdated documentation
• Report coverage metrics

## Skill Category 2: Code Documentation

Documentation that explains how code works, not just what it does.

### readme-generator

Creates and maintains README files:

```markdown
# README Generator

Generate README files from project analysis.

## Analysis

Examines:
- package.json/pyproject.toml for metadata
- Project structure for organization
- Existing documentation for context
- CI configuration for build/test commands
- License file for licensing info

## Generated Sections

### Title and Description
From package metadata or analysis.

### Installation
From package manager and dependencies.

### Usage
From examples in code or tests.

### Development
From scripts in package.json, Makefile, etc.

### Contributing
From CONTRIBUTING.md or generated standard.

### License
From LICENSE file.

## Example Output

```markdown
# User Authentication Service

JWT-based authentication service for microservices architecture.

## Features

- JWT token generation and validation
- Refresh token rotation
- OAuth2 provider integration (Google, GitHub)
- Rate limiting and brute force protection

## Installation

```bash
npm install @company/auth-service

Quick Start

import { AuthService } from '@company/auth-service'

const auth = new AuthService({
  jwtSecret: process.env.JWT_SECRET,
  tokenExpiry: '15m',
})

// Authenticate user
const tokens = await auth.login(email, password)

// Verify token
const user = await auth.verify(tokens.accessToken)

Configuration

Development

# Install dependencies
npm install

# Run tests
npm test

# Run locally
npm run dev

License

MIT

architecture-documenter

Documents system architecture:

# Architecture Documenter

Generate architecture documentation from code structure.

## Analysis

### Dependency Graph
Map dependencies between modules:
- Which modules import which
- External dependencies
- Circular dependencies

### Layer Analysis
Identify architectural layers:
- Controllers/handlers
- Services/use cases
- Repositories/data access
- Utilities/shared

### Component Boundaries
Detect bounded contexts and modules.

## Output

### Architecture Overview

```markdown
# System Architecture

## High-Level Structure

┌─────────────────────────────────────────────────────────┐ │ API Gateway │ │ (src/api/) │ ├─────────────────────────────────────────────────────────┤ │ Application Layer │ │ (src/services/) │ ├───────────────────────┬─────────────────────────────────┤ │ Domain Layer │ Infrastructure │ │ (src/domain/) │ (src/infra/) │ ├───────────────────────┴─────────────────────────────────┤ │ Data Access Layer │ │ (src/repositories/*) │ └─────────────────────────────────────────────────────────┘

## Module Dependencies

### User Module

The user module handles all user-related operations.

Dependencies:
- auth (for authentication)
- email (for notifications)
- storage (for avatars)

Dependents:
- order (user reference)
- review (user reference)

### Order Module

[Similar analysis for each module]

Mermaid Diagrams

Generate visual diagrams:

graph TD
    A[API Gateway] --> B[Auth Service]
    A --> C[User Service]
    A --> D[Order Service]
    B --> E[(Auth DB)]
    C --> F[(User DB)]
    D --> G[(Order DB)]
    D --> C

### adr-generator

Creates Architectural Decision Records:

```markdown
# ADR Generator

Generate Architectural Decision Records.

## ADR Format (MADR)

```markdown
# ADR-{number}: {title}

## Status

{Proposed | Accepted | Deprecated | Superseded}

## Context

{Describe the situation and forces at play}

## Decision

{Describe the decision made}

## Consequences

### Positive
- {Benefit 1}
- {Benefit 2}

### Negative
- {Tradeoff 1}
- {Tradeoff 2}

### Neutral
- {Implication 1}

## Related

- Supersedes: {ADR-X}
- Related: {ADR-Y, ADR-Z}

Process

1. User describes decision context
2. Skill structures into ADR format
3. Suggests consequences based on decision type
4. Numbers and files appropriately

Example

User input: "We decided to use PostgreSQL instead of MongoDB because we need strong consistency for financial transactions and our team is more familiar with SQL."

Generated ADR:

ADR-0005: Use PostgreSQL for Primary Database

Status

Accepted

Context

We need to choose a primary database for the payment processing system. The system handles financial transactions requiring ACID compliance. Our team has extensive experience with relational databases. We considered both PostgreSQL and MongoDB.

Decision

We will use PostgreSQL as our primary database.

Key factors:

• ACID transactions for financial data integrity
• Team familiarity reduces onboarding time
• Mature tooling for operations and monitoring
• Strong support for complex queries needed in reporting

Consequences

Positive

• Full ACID compliance ensures transaction integrity
• Rich query capabilities for business intelligence
• Team can be productive immediately
• Well-understood scaling patterns (read replicas, partitioning)

Negative

• Less flexible schema evolution than document databases
• Horizontal scaling requires careful planning
• Need to manage schema migrations

Neutral

• Will use an ORM (Prisma) for application access
• Backup and recovery processes need to be established

## Skill Category 3: User Documentation

Documentation for end users, not developers.

### user-guide-generator

Creates user-facing documentation:

```markdown
# User Guide Generator

Generate end-user documentation from application analysis.

## Sources

- UI component analysis
- API endpoint analysis
- Feature flags and configuration
- Existing help text
- User journey analysis

## Output Structure

### Getting Started
- Account creation
- First-time setup
- Core concepts

### Feature Guides
For each major feature:
- What it does
- How to use it
- Tips and best practices
- Common issues

### Reference
- Settings explained
- Keyboard shortcuts
- Glossary of terms

## Example

### Creating Your First Project

1. Click **New Project** in the dashboard
2. Enter a project name and optional description
3. Choose a template or start blank
4. Click **Create**

Your project is now ready. You'll see the project editor with:
- **Canvas**: The main work area
- **Toolbar**: Tools for creating content
- **Sidebar**: Navigation and settings

#### Next Steps

- [Add team members](#adding-team-members)
- [Import existing content](#importing-content)
- [Configure integrations](#integrations)

### Tips

- Use descriptive project names; you can't rename later
- Templates include sample content you can modify or delete
- Projects are private by default

changelog-writer

Generates changelogs for users:

# Changelog Writer

Generate user-facing changelogs from commit history.

## Process

1. Analyze commits since last release
2. Group by type (feat, fix, etc.)
3. Translate technical changes to user benefits
4. Highlight breaking changes
5. Format for user consumption

## Translation Examples

Technical: "feat(api): add batch endpoint for orders"
User-facing: "You can now submit multiple orders at once, saving time for bulk operations."

Technical: "fix(parser): handle UTF-8 in filenames"
User-facing: "Fixed an issue where files with special characters in names couldn't be uploaded."

Technical: "perf(db): add index to user_id column"
User-facing: "Dashboard loading is now up to 3x faster."

## Output

```markdown
# Release Notes - v2.5.0

Released January 19, 2025

## What's New

### Bulk Order Processing
You can now submit multiple orders in a single operation. Select multiple
items and click "Process All" to save time on large orders.

### Improved Dashboard Performance
We've optimized database queries to make your dashboard load up to 3x faster,
especially for accounts with many projects.

## Fixes

- Files with special characters (like emojis or accented letters) now upload correctly
- Fixed an issue where session timeout didn't redirect to login
- Resolved duplicate notification emails for some users

## Breaking Changes

### API Version Requirement
API clients must now include a version header. Requests without version
headers will default to v1 behavior through March 2025.

**Action Required:** Update your API client to include `X-API-Version: 2`.

### faq-generator

Generates FAQs from support patterns:

```markdown
# FAQ Generator

Generate FAQ documentation from various sources.

## Sources

- Support ticket analysis
- Error message mapping
- Common user journeys
- Feature complexity areas

## Process

1. Identify common questions/issues
2. Generate clear answers
3. Include examples and visuals
4. Link to detailed documentation

## Example Output

```markdown
# Frequently Asked Questions

## Getting Started

### How do I create an account?

Click "Sign Up" on the homepage and enter your email address. We'll send
a verification link. Click the link to complete signup.

### Can I use my Google account?

Yes! Click "Continue with Google" on the signup page. We'll create an
account linked to your Google login.

## Billing

### How do I upgrade my plan?

Go to Settings > Billing > Change Plan. Select your new plan and enter
payment information. Changes take effect immediately.

### Can I get a refund?

We offer a 14-day money-back guarantee. Contact support@example.com
within 14 days of purchase for a full refund.

## Features

### Why can't I see the export button?

The export feature is available on Pro plans and above. Upgrade your
plan to access exports.

### How do I share a project?

Click the Share button in the project header. Enter email addresses
of people you want to share with. They'll receive an invitation link.

## Skill Category 4: Code Comments

In-code documentation that explains why, not what.

### comment-generator

Adds explanatory comments to code:

```markdown
# Comment Generator

Generate meaningful code comments.

## Philosophy

Comments should explain:
- WHY code exists (not what it does)
- Context that isn't obvious
- Gotchas and edge cases
- Links to relevant resources

Comments should NOT:
- Repeat what code clearly shows
- Become outdated
- State the obvious

## Example

Before:
```typescript
function calculatePrice(items, user) {
  let total = items.reduce((sum, item) => sum + item.price, 0)

  if (user.memberSince < new Date('2020-01-01')) {
    total = total * 0.9
  }

  if (total > 1000) {
    total = total * 0.95
  }

  return total
}

After:

function calculatePrice(items, user) {
  let total = items.reduce((sum, item) => sum + item.price, 0)

  // Legacy loyalty discount: Users who joined before our pricing restructure
  // keep their 10% discount. This was promised during the 2019 migration.
  // See: https://internal.docs/pricing-migration-2019
  if (user.memberSince < new Date('2020-01-01')) {
    total = total * 0.9
  }

  // Bulk discount kicks in at $1000. This threshold was determined by
  // analyzing order patterns - 95% of orders are under this amount.
  if (total > 1000) {
    total = total * 0.95
  }

  return total
}

Anti-Patterns Avoided

// Bad: States the obvious
let total = 0 // Initialize total to zero

// Bad: Outdated (code changed, comment didn't)
// Returns user's first name
function getFullName() { ... }

// Bad: Commented-out code
// function oldImplementation() { ... }

### todo-documenter

Manages TODO comments:

```markdown
# TODO Documenter

Manage and track TODO comments in code.

## Features

### Discovery
Find all TODOs in codebase:

TODO: Implement caching (src/api/users.ts:45) FIXME: Race condition in concurrent access (src/db/pool.ts:112) HACK: Temporary workaround for upstream bug (src/parser/index.ts:78)

### Standardization
Enforce TODO format:
```typescript
// TODO(username): Brief description
//   Context: Why this needs to be done
//   Tracking: #123 or link to issue

Reporting

Generate TODO report:

# Technical Debt Report

## Critical (FIXME)
- [ ] Race condition in connection pool (src/db/pool.ts:112)
  Added: 2024-11-15, Assignee: @bob

## Important (TODO)
- [ ] Add caching layer for user queries (src/api/users.ts:45)
  Added: 2024-12-01, No assignee

## Low Priority (HACK)
- [ ] Workaround for upstream date parsing (src/parser/index.ts:78)
  Added: 2024-10-20, Depends on: upstream fix

Integration

Create issues from TODOs:

• Parse TODO with context
• Generate issue with details
• Update TODO with issue reference

## Choosing the Right Skills

### By Documentation Type

| Need | Recommended Skill |
|------|------------------|
| API reference | openapi-generator |
| GraphQL docs | graphql-documenter |
| Code docs | jsdoc-generator |
| Project README | readme-generator |
| Architecture docs | architecture-documenter |
| Decision tracking | adr-generator |
| User guides | user-guide-generator |
| Release notes | changelog-writer |
| FAQ | faq-generator |
| Code comments | comment-generator |

### By Audience

**Developers integrating your API:**
- openapi-generator
- graphql-documenter
- readme-generator

**Developers maintaining the code:**
- jsdoc-generator
- architecture-documenter
- adr-generator
- comment-generator

**End users:**
- user-guide-generator
- changelog-writer
- faq-generator

### By Effort vs. Value

**High automation, high value (start here):**
- openapi-generator (generates from code)
- readme-generator (80% automated)
- changelog-writer (from commits)

**Medium automation, high value:**
- architecture-documenter (structure from code, prose needs human)
- adr-generator (structure automated, decisions need human)

**Human-intensive but critical:**
- user-guide-generator (needs human review)
- faq-generator (needs human knowledge)

## Integration Strategies

### Documentation as Code

Store docs alongside code:

project/ ├── src/ ├── docs/ │ ├── api/ # Generated API docs │ ├── architecture/ # ADRs and diagrams │ └── guides/ # User guides ├── CHANGELOG.md # Generated └── README.md # Generated + maintained

### CI/CD Integration

Generate docs on build:
```yaml
documentation:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Generate API docs
      run: claude /generate-openapi
    - name: Generate README
      run: claude /update-readme
    - name: Deploy docs
      run: npm run docs:deploy

Keeping Docs Fresh

Schedule regular updates:

scheduled-docs:
  schedule:
    - cron: '0 0 * * 1'  # Weekly
  steps:
    - name: Regenerate all docs
      run: claude /docs-refresh
    - name: Create PR if changes
      uses: peter-evans/create-pull-request@v5

Conclusion

Documentation skills address the fundamental tension between the importance of documentation and the time cost of creating it. By automating generation of structural documentation (API specs, READMEs, architecture diagrams) and providing templates for human-written documentation (ADRs, user guides), these skills make comprehensive documentation achievable.

The key is matching skills to needs:

• API docs: Full automation is possible and valuable
• Architecture docs: Structure automated, insights need human
• User docs: Templates help, but human review essential
• Decision records: Format automated, decisions need human

Start with the documentation your users complain about most:

• Developers can't integrate? Prioritize API docs.
• Team can't onboard? Prioritize architecture docs.
• Users confused? Prioritize guides and FAQs.

Generated documentation is better than no documentation, and well-maintained generated documentation is better than outdated handwritten documentation. Use these skills to make comprehensive documentation the default, not the exception.

---

Want to improve other aspects of your development workflow? Check out Code Review Skills Roundup for PR documentation automation, or explore Git Workflow Skills for commit message documentation.