Generate Agent Documentation

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

Provider Folder Reference

This skill works across multiple AI coding assistant providers:

Provider Base Folder

GitHub Copilot .github/

Claude Code .claude/

Codex .codex/

OpenCode .config/opencode/

Throughout this document, <provider>/ represents your chosen provider's base folder.

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

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)

Sub-Agents (Workflow Components)

Skills

Prompts

Instructions

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:

• Clear - No jargon without explanation

• Practical - Real, actionable examples

• Complete - Covers all key aspects

• Concise - No unnecessary padding

• 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