Doc To Skill

Documentation to Skill Converter

Transform documentation into structured Agent Skills using progressive disclosure and context-efficient design principles.

Quick Start

Conversion workflow:

1. Analyze source document structure and content
2. Extract core workflows (20% that solves 80%)
3. Create SKILL.md with essential content (<500 lines)
4. Move detailed content to references/ files
5. Write comprehensive description with trigger scenarios
6. Validate and package

Key principle: Progressive disclosure - metadata → SKILL.md → references/ (loaded only when needed)

Core Conversion Process

Step 1: Analyze Source Document

Identify structure:

• Document length and sections
• Information hierarchy (intro → basics → advanced)
• Most frequently used content (80/20 rule)
• Detailed reference material

Questions to answer:

• What are the core workflows? (most common tasks)
• What's reference material? (complete command lists, detailed specs)
• What triggers this skill? (when would someone need this?)

Step 2: Extract Core Content

For SKILL.md (keep essential only):

• Quick start / getting started
• Core workflows (most common tasks)
• Essential commands/operations
• Basic configuration
• Common patterns
• Troubleshooting basics
• References to detailed docs

Extraction criteria:

• Used in 80% of cases → SKILL.md
• Used in 20% of cases → references/
• Quick reference needed → SKILL.md
• Complete reference → references/

Step 3: Write Frontmatter

Description format:

description: [What it does]. Use when (1) [Scenario 1], (2) [Scenario 2], (3) [Scenario 3]...

Requirements:

• Clear "what it does" statement
• Numbered list of trigger scenarios
• Include all use cases (this is the trigger mechanism)
• No colons in description field

Example:

description: Comprehensive guide for using GitHub CLI (gh) to interact with GitHub from the command line. Use when (1) Managing GitHub repositories, issues, pull requests, or releases from terminal, (2) Automating GitHub workflows in scripts, (3) Creating or managing pull requests, (4) Working with GitHub issues, (5) Creating releases or managing repository operations, (6) Integrating GitHub operations into development workflows, (7) Using GitHub CLI commands in automation scripts

Step 4: Structure SKILL.md

Recommended structure:

# [Title]

[Brief overview - 1-2 sentences]

## Quick Start
[Most common operations - 5-10 examples]

## Core Workflows
[Organized by task category]

## Configuration
[Essential settings]

## Advanced Usage
[Optional - only if needed]

## Common Patterns
[Best practices]

## Troubleshooting
[Common issues]

## References
[Links to references/ files]

Guidelines:

• Keep under 500 lines (ideally 200-300)
• Prioritize actionable content (commands, examples)
• Use code blocks for all examples
• Reference detailed docs, don't duplicate

Step 5: Create References

When to create references/ files:

• Complete command/API reference
• Detailed workflow scenarios
• Advanced patterns and examples
• Large reference material (>100 lines)

File organization:

• references/commands.md - Complete command/API reference
• references/workflows.md - Detailed workflow scenarios
• references/advanced.md - Advanced patterns (if needed)

Reference file structure:

# [Title]

## [Category 1]
[Detailed content]

## [Category 2]
[Detailed content]

Step 6: Link References

In SKILL.md, add references section:

## References

For detailed information, see:
- [commands.md](references/commands.md) - Complete command reference
- [workflows.md](references/workflows.md) - Detailed workflow scenarios

Design Principles

1. Progressive Disclosure

Three-level loading:

1. Metadata (name + description) - Always loaded (~100 words)
2. SKILL.md body - Loaded when skill triggers (<500 lines)
3. references/ - Loaded only when needed (unlimited)

Benefit: Minimizes context window usage while maintaining completeness.

2. 80/20 Rule

• 20% of content (most common) → SKILL.md
• 80% of content (detailed) → references/

Example:

• SKILL.md: gh pr create, gh pr list, gh pr merge (most common)
• references/: All PR commands with all flags and options

3. Actionability First

Prioritize:

• ✅ Executable commands/code
• ✅ Real-world examples
• ✅ Common patterns
• ❌ Theoretical explanations
• ❌ Edge cases (move to references)

4. No Duplication

Rule: Information lives in ONE place only.

• SKILL.md = Quick reference, essential workflows
• references/ = Complete documentation, detailed specs

Avoid: Copying same content to both places.

5. Trigger Clarity

Description must include:

• What the skill does
• When to use it (numbered scenarios)
• All relevant use cases

Why: Description is the ONLY trigger mechanism - Codex uses it to decide when to load the skill.

Conversion Checklist

Pre-Conversion

• Analyzed source document structure
• Identified core workflows (80/20)
• Listed all trigger scenarios
• Planned file organization

Frontmatter

• name field (lowercase, hyphenated)
• description with "Use when" scenarios
• metadata.short-description
• No colons in description
• All use cases listed

SKILL.md

• Under 500 lines (ideally 200-300)
• Quick Start section
• Core workflows organized
• Actionable examples (code blocks)
• References section linking to references/
• No duplication with references/

References

• Created references/ directory
• Detailed content moved to references/
• Files properly named and organized
• Linked from SKILL.md

Validation

• Frontmatter format correct
• All references valid
• Code examples tested
• Skill packages successfully

Common Patterns

Pattern 1: Command-Line Tool Documentation

Source: CLI tool manual (e.g., gh, git, docker)

Structure:

• SKILL.md: Most common commands, basic workflows
• references/commands.md: Complete command reference with all flags
• references/workflows.md: Common usage patterns

Pattern 2: API Documentation

Source: API reference documentation

Structure:

• SKILL.md: Quick start, common operations, authentication
• references/api.md: Complete API reference
• references/examples.md: Code examples

Pattern 3: Framework Guide

Source: Framework documentation (e.g., React, Django)

Structure:

• SKILL.md: Core concepts, common patterns
• references/concepts.md: Detailed concepts
• references/patterns.md: Advanced patterns
• references/api.md: API reference

Pattern 4: Workflow Documentation

Source: Process/workflow documentation

Structure:

• SKILL.md: Main workflow steps, decision points
• references/workflows.md: Detailed workflow scenarios
• references/troubleshooting.md: Common issues

Examples

Before (Documentation)

# Tool Guide (500 lines)
## Introduction (50 lines)
## Installation (100 lines)
## Basic Usage (150 lines)
## Advanced Features (200 lines)

After (Skill)

SKILL.md (200 lines)
├── Quick Start
├── Core Workflows
├── Common Patterns
└── References → references/

references/
├── installation.md (100 lines)
├── advanced.md (200 lines)
└── complete-reference.md (150 lines)

Tools and Commands

Initialize skill:

python init_skill.py <skill-name> --path <path> --resources references

Package skill:

python package_skill.py <path/to/skill>

Validate frontmatter:

python quick_validate.py <path/to/SKILL.md>

References

For detailed conversion methodology and examples, see:

• methodology.md - Complete conversion methodology
• checklist.md - Detailed conversion checklist
• examples.md - Real conversion examples
• patterns.md - Common conversion patterns