Skill Doc Enhancer

---

name: skill-doc-enhancer description: Automatically analyze and enhance content-short SKILL.md files by analyzing skill directory structure, adding usage examples, script documentation, common use cases, and best practices. Use when a skill's SKILL.md is too short (less than 3000 characters), lacks sufficient examples, missing script documentation, or needs content enrichment while preserving existing structure.

---

Skill Doc Enhancer

Automatically analyze and enhance SKILL.md files that are too short or lack sufficient documentation.

When to Use

Use this skill when:

A skill's SKILL.md has less than 3000 characters

The documentation lacks usage examples

Scripts exist but aren't documented in SKILL.md

Common use cases and best practices are missing

The skill needs content enrichment while preserving structure

Enhancement Process

Step 1: Analyze Current State

Run the analysis script to understand what needs enhancement:

python3 scripts/analyze_skill.py 

This will output:

Current character count

Missing sections (examples, scripts, best practices)

Directory structure analysis

Enhancement recommendations

Step 2: Generate Enhancement Content

Based on the analysis, the script will suggest:

1. Directory Structure Analysis - List all files in scripts/, references/, assets/ - Identify undocumented resources

2. Script Documentation - For each script in scripts/, extract: - Purpose and functionality - Usage syntax - Example commands - Expected outputs

3. Usage Examples - Common task patterns - Input/output examples - Error handling examples

4. Best Practices - Recommended workflows - Common pitfalls to avoid - Tips for effective usage

Step 3: Apply Enhancements

The enhancement script can automatically append content:

python3 scripts/enhance_skill.py  [--dry-run]

Options:

--dry-run: Preview changes without modifying files

--sections examples,scripts,best-practices: Choose which sections to enhance

Enhancement Categories

1. Script Documentation

For skills with a scripts/ directory, add:

## Scripts Reference
script-name.py
Purpose: Brief description of what the script does
Usage:

bash python3 scripts/script-name.py [arguments]

Examples:

bash

Example 1: Basic usage

python3 scripts/script-name.py input.txt

Example 2: With options

python3 scripts/script-name.py input.txt --output result.txt

2. Usage Examples

Add concrete examples showing real-world usage:

## Usage Examples
Example 1: [Task Name]
Scenario: Describe when this example applies
Input: 
File: example.txt
Content: ...
Command:

bash

Command to execute

Output:

Expected output

Example 2: [Another Task]
...

3. Best Practices

Document recommendations and pitfalls:

## Best Practices
Do's
Recommendation 1
Recommendation 2
Don'ts
Pitfall 1 and why to avoid it
Pitfall 2 and why to avoid it
Tips
Pro tip for advanced usage
Performance optimization suggestion

4. Common Use Cases

List typical scenarios where the skill applies:

## Common Use Cases
1. [Use Case 1]: Brief description
   - When to use: Context
   - Expected outcome: Result
2. [Use Case 2]: Brief description
   - When to use: Context
   - Expected outcome: Result

Manual Enhancement Guidelines

When automatic enhancement isn't sufficient:

1. Preserve Existing Structure: Don't reorganize unless necessary 2. Append, Don't Replace: Add new content after existing sections 3. Match Style: Follow the existing tone and formatting 4. Be Specific: Include concrete file names, paths, and commands 5. Test Examples: Ensure all code examples work as documented

Quality Checklist

After enhancement, verify:

[ ] Character count > 3000 (unless skill is intentionally minimal)

[ ] All scripts in scripts/ are documented

[ ] At least 2-3 usage examples provided

[ ] Best practices section exists

[ ] Common use cases listed

[ ] Examples are tested and accurate

[ ] No TODO or XXX placeholders remain

Scripts

analyze_skill.py

Analyzes a skill directory and reports enhancement opportunities.

Usage:

python3 scripts/analyze_skill.py /path/to/skill-directory

Output: JSON report with:

char_count: Current SKILL.md character count

has_examples: Whether usage examples exist

scripts_documented: Whether scripts are documented

has_best_practices: Whether best practices section exists

recommendations: List of suggested enhancements

enhance_skill.py

Automatically enhances SKILL.md with missing content.

Usage:

python3 scripts/enhance_skill.py /path/to/skill-directory [options]

Options:

--dry-run: Preview changes without writing

--sections SECTIONS: Comma-separated list of sections to enhance

- Available: examples, scripts, best-practices, use-cases - Default: all sections

Example:

# Preview enhancements
python3 scripts/enhance_skill.py /path/to/skill --dry-run
Enhance only examples and scripts
python3 scripts/enhance_skill.py /path/to/skill --sections examples,scripts

Example Enhancement Workflow

# 1. Analyze the skill
python3 scripts/analyze_skill.py skills/nano-pdf
Output:
{
  "skill_name": "nano-pdf",
  "char_count": 1850,
  "has_examples": false,
  "scripts_documented": false,
  "has_best_practices": false,
  "recommendations": [
    "Add usage examples section",
    "Document scripts/pdf_utils.py",
    "Add best practices section"
  ]
}
2. Preview enhancements
python3 scripts/enhance_skill.py skills/nano-pdf --dry-run
3. Apply enhancements
python3 scripts/enhance_skill.py skills/nano-pdf
4. Review and edit manually if needed
Edit skills/nano-pdf/SKILL.md

Notes

This skill focuses on content enhancement, not restructuring

Always review automatic enhancements before committing

Some skills may be intentionally minimal - use judgment

When in doubt, prefer adding examples over explanations

Pro tip for advanced usage

Performance optimization suggestion

4. Common Use Cases
List typical scenarios where the skill applies:

markdown