# Skill Doc Generator

> Skill Doc Generator

- Skill: `materialofair/skill-doc-generator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add materialofair/skill-doc-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/materialofair/skill-doc-generator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: materialofair (https://skillmd.com/u/materialofair)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/materialofair/skill-doc-generator

---



# Skill Documentation Generator

Automated documentation generation for Codex skills. Creates professional README.md, HOW_TO_USE.md, and example files from your SKILL.md definition.

## Capabilities

- **README Generation**: Creates installation-focused README.md with quick start
- **Usage Guide Creation**: Generates detailed HOW_TO_USE.md with examples
- **Example Extraction**: Pulls usage examples from SKILL.md into standalone files
- **Sample Data Generation**: Creates sample_input/output JSON from skill description
- **Documentation Templates**: Uses Codex best practices for structure
- **Multi-Format Support**: Markdown, JSON, YAML outputs
- **Auto-Update**: Regenerates docs when SKILL.md changes
- **Quality Validation**: Ensures generated docs meet standards

## Input Requirements

**Minimal**:
- SKILL.md file with valid YAML frontmatter
- Basic capabilities and usage sections

**Optimal**:
- Complete SKILL.md with all recommended sections
- Existing usage examples in "How to Use" section
- Python files (if applicable) for code documentation

## Output Files

### 1. README.md
**Purpose**: Quick start and installation guide

**Content**:
- Brief skill description
- Quick install command
- Usage teaser (2-3 examples)
- File listing
- Related skills links

**Length**: ~20-30 lines (scannable)

### 2. HOW_TO_USE.md
**Purpose**: Comprehensive usage guide

**Content**:
- Detailed usage examples (organized by use case)
- Input/output format explanations
- Advanced usage patterns
- Troubleshooting guide
- Integration examples
- Real-world scenarios

**Length**: ~100-200 lines (thorough)

### 3. sample_input.json
**Purpose**: Example input data

**Content**:
- Realistic input example
- All required fields
- Optional fields shown
- Comments explaining structure

### 4. expected_output.json
**Purpose**: Expected output example

**Content**:
- Corresponding output for sample input
- Complete structure shown
- Annotations for clarity

### 5. CHANGELOG.md (Optional)
**Purpose**: Version history

**Content**:
- Version numbers
- Change descriptions
- Breaking changes highlighted
- Migration guides

## How to Use

**Quick Generation**:
```
"Generate documentation for my financial-analyzer skill"
"Create README and HOW_TO_USE for code-review"
"Auto-generate docs for all my skills"
```

**Selective Generation**:
```
"Just create README.md for aws-solution-architect"
"Generate HOW_TO_USE only for prompt-factory"
"Create sample input/output files for skill-tester"
```

**Update Existing Docs**:
```
"Update documentation for financial-analyzer (SKILL.md changed)"
"Regenerate all docs for code-review"
```

**Custom Templates**:
```
"Generate README using minimal template"
"Create comprehensive HOW_TO_USE with troubleshooting"
```

## Documentation Templates

### Template 1: Minimal (Simple Skills)
**README**: 15-20 lines, quick install + 2 examples
**HOW_TO_USE**: 50-75 lines, basic usage patterns
**Use for**: Utility skills, simple tools

### Template 2: Standard (Most Skills)
**README**: 25-35 lines, install + features + 3-4 examples
**HOW_TO_USE**: 100-150 lines, organized sections, real-world examples
**Use for**: Production skills, general purpose

### Template 3: Comprehensive (Complex Skills)
**README**: 40-50 lines, detailed overview, file structure
**HOW_TO_USE**: 200+ lines, advanced patterns, integration guide, troubleshooting
**Use for**: Complex skills, API integrations, multi-feature

## Generation Process

### Step 1: Analyze SKILL.md
```
- Extract YAML frontmatter (name, description)
- Identify sections (Capabilities, Input/Output, How to Use)
- Parse usage examples
- Detect Python files (if present)
```

### Step 2: Select Template
```
- Count capabilities (< 3 = minimal, 3-6 = standard, > 6 = comprehensive)
- Check skill complexity (simple = minimal, medium = standard, complex = comprehensive)
- Consider Python files (present = more detailed docs)
```

### Step 3: Generate Content
```
- README: Skill overview + quick start
- HOW_TO_USE: Detailed guide + examples
- sample_input: Realistic example data
- expected_output: Corresponding output
```

### Step 4: Validate
```
- Check all required sections present
- Verify examples are clear
- Ensure links work
- Validate JSON/YAML syntax
```

### Step 5: Write Files
```
- Create README.md
- Create HOW_TO_USE.md
- Create sample_input.json
- Create expected_output.json
- (Optional) Create CHANGELOG.md
```

## Documentation Best Practices

### README.md Principles
1. **Scannable**: User should understand in 10 seconds
2. **Actionable**: Clear install command
3. **Enticing**: Best 2-3 examples shown
4. **Linked**: References to detailed docs

### HOW_TO_USE.md Principles
1. **Progressive**: Simple examples first, complex later
2. **Organized**: Group by use case or scenario
3. **Real-world**: Actual usage patterns, not theory
4. **Complete**: Cover all major capabilities
5. **Helpful**: Include troubleshooting and tips

### Sample Data Principles
1. **Realistic**: Use actual use case data
2. **Complete**: Show all required fields
3. **Annotated**: Comments explain structure
4. **Valid**: JSON/YAML syntax correct

## Example Generation Session

```
User: "Generate docs for financial-analyzer"

Codex: "Analyzing financial-analyzer skill...

Found:
- 5 capabilities
- 3 input types
- 4 output formats
- 6 usage examples
- 2 Python files

Selecting: Standard template (good fit for medium complexity)

Generating:
✅ README.md (28 lines) - Quick start guide
✅ HOW_TO_USE.md (145 lines) - Comprehensive usage guide
   - 6 usage examples organized by scenario
   - Input/output format details
   - Integration with other skills
   - Troubleshooting section
✅ sample_input.json - P/E ratio calculation example
✅ expected_output.json - Corresponding output with metrics

All files created in ~/.codex/skills/financial-analyzer/

Would you like me to review the generated docs?"
```

## Customization Options

### Content Options
- **Include examples**: true/false (extract from SKILL.md)
- **Include sample data**: true/false (generate JSON examples)
- **Include changelog**: true/false (version history)
- **Include troubleshooting**: true/false (common issues section)

### Style Options
- **Template**: minimal/standard/comprehensive
- **Tone**: technical/friendly/professional
- **Length**: concise/detailed/exhaustive
- **Format**: markdown/text/html

### Advanced Options
- **Extract from code**: Parse Python docstrings for additional content
- **Generate diagrams**: Create workflow/architecture diagrams (ASCII art)
- **API docs**: Generate API reference from code
- **Multilingual**: Create docs in multiple languages

## Integration with Development Workflow

### Initial Skill Creation
```
1. Write SKILL.md with capabilities
2. Run skill-doc-generator
3. Review generated docs
4. Adjust SKILL.md if needed
5. Regenerate docs
```

### Ongoing Maintenance
```
1. Update SKILL.md with new features
2. Run skill-doc-generator (auto-update)
3. Generated docs stay in sync
```

### Pre-Distribution
```
1. Complete SKILL.md
2. Generate all docs
3. Review for quality (use skill-quality-analyzer)
4. Package skill with full documentation
```

## Quality Checks

Generated docs are validated for:
- [ ] README exists and is scannable (< 50 lines)
- [ ] HOW_TO_USE exists and is comprehensive
- [ ] All code blocks have proper syntax
- [ ] Examples are clear and realistic
- [ ] Links are valid (no broken references)
- [ ] JSON/YAML files are valid
- [ ] File structure matches Codex guidelines
- [ ] No spelling/grammar errors

## Common Documentation Issues (Auto-Fixed)

### Issue 1: Vague Examples
**Before**: "Use this skill to analyze data"
**After**: "Calculate P/E ratio: 'Analyze stock with price $100 and EPS $6.45'"

### Issue 2: Missing Installation
**Before**: No install instructions
**After**: "cp -r financial-analyzer ~/.codex/skills/"

### Issue 3: No Input/Output Clarification
**Before**: "Takes data and returns results"
**After**: Shows JSON structure with field explanations

### Issue 4: No Troubleshooting
**Before**: Examples only
**After**: "If skill doesn't trigger, check description keywords"

## Limitations

- **Quality Depends on SKILL.md**: Generated docs only as good as source
- **No Code Analysis**: Doesn't parse complex Python logic (basic docstrings only)
- **Template-Based**: Uses predefined structures (not fully custom)
- **English-Only**: Currently supports English documentation only
- **No Diagrams**: Can't generate complex visual diagrams (ASCII only)

## When NOT to Use This Skill

- **Custom Documentation Needed**: Highly specialized format
- **Code Documentation**: Use language-specific tools (Sphinx, JSDoc)
- **API References**: Use dedicated API doc generators
- **Quick Notes**: Manual README is faster for simple skills

## Success Criteria

Well-generated documentation should:
- ✅ README scannable in < 10 seconds
- ✅ HOW_TO_USE answers "how do I use this?" completely
- ✅ Examples are copy-paste ready
- ✅ Sample data is realistic
- ✅ No user questions left unanswered
- ✅ Passes quality validation
- ✅ Follows Codex best practices

## Related Skills

- Use **skill-quality-analyzer** after generation to validate docs
- Use **skill-debugger** if generated examples don't trigger correctly
- Use **skill-tester** to verify examples work as documented
- Complements **Skill Factory** for initial skill creation