materialofair 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
- Scannable: User should understand in 10 seconds
- Actionable: Clear install command
- Enticing: Best 2-3 examples shown
- Linked: References to detailed docs
HOW_TO_USE.md Principles
- Progressive: Simple examples first, complex later
- Organized: Group by use case or scenario
- Real-world: Actual usage patterns, not theory
- Complete: Cover all major capabilities
- Helpful: Include troubleshooting and tips
Sample Data Principles
- Realistic: Use actual use case data
- Complete: Show all required fields
- Annotated: Comments explain structure
- 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