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 <path/to/skill-directory>

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 <path/to/skill-directory> [--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:

# 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:

```markdown
## 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:

```markdown
## 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