Generate Agent Documentation

Creates user-friendly documentation for AI coding assistant customization files.

Host-specific packaging

This is a repository maintenance skill, excluded from the WoW plugin. Maintain canonical WoW skills under skills and generate the package with npm run build. Agent metadata, rules, commands, and discovery paths differ by host; do not copy Copilot conventions into Codex or Claude mechanically. See file locations. Examples using <provider>/ below describe Copilot-style source files and must be adapted using host specifications.

When to Use

• Onboarding new team members to your agent ecosystem
• Creating a catalog of available agents and skills
• Generating usage examples for specific agents
• Documenting your customization setup for reference

Documentation Types

Individual Item Documentation

Generate detailed docs for a single agent, skill, prompt, or instruction.

Catalog Documentation

Generate a comprehensive overview of all customization files.

Output Templates

Agent Documentation

# Agent: [Agent Name]

## Overview
[What this agent does and why it exists]

## When to Use This Agent

Use `@[agent-name]` when:
- [Scenario 1]
- [Scenario 2]
- [Scenario 3]

**Don't use** when:
- [Anti-pattern 1]
- [Anti-pattern 2]

## How It Behaves

This agent will:
- [Behavior 1]
- [Behavior 2]
- [Behavior 3]

## Example Conversations

### Example 1: [Scenario Title]

**You:** [Example user message]

**Agent:** [How agent responds - summarized]

### Example 2: [Scenario Title]

**You:** [Example user message]

**Agent:** [How agent responds - summarized]

## Tips for Best Results

- [Tip 1 for effective usage]
- [Tip 2 for effective usage]
- [Common mistake to avoid]

## Related

- **[Related Agent]**: Use for [distinction]
- **[Related Skill]**: This agent uses this for [purpose]

Skill Documentation

# Skill: [Skill Name]

## Purpose
[What this skill accomplishes]

## Triggers
This skill activates when:
- [Trigger keyword/scenario 1]
- [Trigger keyword/scenario 2]

## What It Does
[Step-by-step of what the skill does]

## Used By
- [Agent 1] - for [purpose]
- [Agent 2] - for [purpose]

## Example

**Scenario:** [Description]

**Input:** [What's provided]

**Output:** [What's produced]

Prompt Documentation

# Prompt: [Prompt Name]

## Purpose
[What task this prompt accomplishes]

## Mode
`[mode]` - [explanation of what this mode does]

## Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `{{var1}}` | [what it's for] | [example value] |

## How to Use

1. [Step 1]
2. [Step 2]

## Example

**With these values:**
- `{{var1}}` = [value]

**Produces:**
[Example output]

Instruction Documentation

# Instructions: [Name]

## Applies To
Files matching: `[glob pattern]`

## Purpose
[What guidance these instructions provide]

## Key Rules

1. [Rule 1]
2. [Rule 2]
3. [Rule 3]

## When Active
These instructions automatically apply when you're working with files that match the pattern above.

## Examples of Affected Files
- `[example path 1]`
- `[example path 2]`

Catalog Documentation

# AI Coding Assistant Customizations

This document catalogs all custom agents, skills, prompts, and instructions configured for this project.

## Provider
[Specify which provider folder is used: `.github/`, `.claude/`, `.codex/`, `.config/opencode/`]

## Quick Reference

### Agents (User-Invokable)

| Agent | Purpose | Invoke With |
|-------|---------|-------------|
| [name] | [brief purpose] | `@[name]` |

### Sub-Agents (Workflow Components)

| Sub-Agent | Purpose | Used By |
|-----------|---------|---------|
| [name] | [brief purpose] | [parent workflow agent] |

### Skills

| Skill | Purpose | Triggers |
|-------|---------|----------|
| [name] | [brief purpose] | [keywords] |

### Prompts

| Prompt | Mode | Purpose |
|--------|------|---------|
| [name] | [mode] | [brief purpose] |

### Instructions

| Instructions | Applies To | Purpose |
|--------------|------------|---------|
| [name] | [pattern] | [brief purpose] |

## Detailed Documentation

[Full documentation for each item]

## Usage Guidelines

[General guidance on how to use these customizations effectively]

Generation Process

Step 1: Read Source File

Load the agent/skill/prompt/instruction file.

Step 2: Extract Key Information

• Name and description from frontmatter
• Behaviors and rules from body
• Examples if present
• Related items (skills, handoffs)

Step 3: Enhance with Context

• Generate additional examples based on purpose
• Identify related items from the ecosystem
• Add tips based on common patterns

Step 4: Format Output

Apply appropriate template based on item type.

Quality Guidelines

Generated documentation should be:

1. Clear - No jargon without explanation
2. Practical - Real, actionable examples
3. Complete - Covers all key aspects
4. Concise - No unnecessary padding
5. Current - Reflects actual file contents

Additional Examples

When generating examples beyond those in the source:

• Cover different use case variations
• Show edge cases and how they're handled
• Demonstrate integration with other items
• Illustrate common mistakes to avoid