jmagly/skill-builder

Skill Builder Skill

Purpose

Single responsibility: Transform extracted documentation into properly structured Claude skill packages ready for upload. (BP-4)

Grounding Checkpoint (Archetype 1 Mitigation)

Before executing, VERIFY:

• [ ] Input data directory exists and contains extracted content
• [ ] Content format is recognized (JSON pages, markdown, etc.)
• [ ] Output directory is writable
• [ ] Skill name follows Claude conventions (lowercase, alphanumeric, hyphens)

DO NOT build without verifying input data quality.

Uncertainty Escalation (Archetype 2 Mitigation)

ASK USER instead of guessing when:

• Multiple input formats detected - which to prioritize?
• Category structure unclear from content
• Skill description ambiguous
• Target audience undefined

NEVER generate placeholder content without user guidance.

Context Scope (Archetype 3 Mitigation)

| Context Type | Included | Excluded | |--------------|----------|----------| | RELEVANT | Input data, skill config, output path | Other skills | | PERIPHERAL | Similar skill examples | Unrelated documentation | | DISTRACTOR | Previous build attempts | Source scraping details |

Workflow Steps

Step 1: Validate Input (Grounding)

# Check input data exists
ls -la output/<skill-name>_data/

# Verify page count
find output/<skill-name>_data/pages -name "*.json" | wc -l

# Check summary
cat output/<skill-name>_data/summary.json

Step 2: Generate Skill Structure

Standard Claude skill structure:

output/<skill-name>/
├── SKILL.md              # Main skill file (required)
├── references/           # Reference documentation
│   ├── index.md          # Category index
│   ├── getting_started.md
│   ├── api_reference.md
│   └── guides.md
├── scripts/              # Optional automation scripts
└── assets/               # Optional images, diagrams

Step 3: Create SKILL.md

Template for SKILL.md:

# <Skill Name>

## Description
<When to use this skill - clear, specific>

## Key Features
- Feature 1
- Feature 2
- Feature 3

## Quick Reference

### Common Patterns
<Most frequently used patterns with code examples>

### API Overview
<Key API methods/functions>

## Navigation

| Topic | File | Description |
|-------|------|-------------|
| Getting Started | references/getting_started.md | Installation and setup |
| API Reference | references/api_reference.md | Complete API documentation |
| Guides | references/guides.md | How-to guides and tutorials |

## Code Examples

<3-5 practical code examples from documentation>

## Common Questions

<FAQ section based on documentation>

## Version Information

- Documentation version: <version>
- Last updated: <date>
- Source: <url>

Step 4: Generate Reference Files

Categorize extracted content:

# Categories and their keywords
categories = {
    "getting_started": ["intro", "install", "setup", "quickstart"],
    "api_reference": ["api", "reference", "method", "function", "class"],
    "guides": ["guide", "tutorial", "how-to", "example"],
    "concepts": ["concept", "overview", "architecture"],
    "advanced": ["advanced", "internals", "extend", "customize"]
}

Step 5: Validate Output

# Check required files exist
test -f output/<skill-name>/SKILL.md || echo "Missing SKILL.md"
test -d output/<skill-name>/references || echo "Missing references/"

# Verify SKILL.md structure
grep "^# " output/<skill-name>/SKILL.md
grep "^## " output/<skill-name>/SKILL.md

# Check reference files
ls -la output/<skill-name>/references/

Recovery Protocol (Archetype 4 Mitigation)

On error:

1. PAUSE - Preserve partial build
2. DIAGNOSE - Check error type:
   • Missing input data → Re-run extraction
   • Invalid content format → Check parser compatibility
   • Categorization failed → Manual category mapping
   • Template error → Check SKILL.md syntax
3. ADAPT - Adjust build configuration
4. RETRY - Rebuild affected sections (max 3 attempts)
5. ESCALATE - Present partial build, ask for guidance

Checkpoint Support

State saved to: .aiwg/working/checkpoints/skill-builder/

checkpoints/skill-builder/
├── build_config.json       # Build configuration
├── categorization.json     # Category assignments
├── skill_md_draft.md       # SKILL.md draft
└── progress.json           # Build progress

Quality Criteria

| Criterion | Requirement | Validation | |-----------|-------------|------------| | SKILL.md present | Required | File exists check | | Description clear | Required | Non-empty, specific | | References organized | Required | At least 2 categories | | Code examples | Recommended | 3+ examples in SKILL.md | | Navigation table | Recommended | Links to all references |

Output Validation

Run quality check after build:

# Use quality-checker skill
# Or manual validation:

# 1. SKILL.md structure
grep -E "^#{1,2} " output/<skill-name>/SKILL.md

# 2. Code examples present
grep -c '```' output/<skill-name>/SKILL.md

# 3. References populated
for f in output/<skill-name>/references/*.md; do
  echo "$f: $(wc -l < $f) lines"
done

# 4. No broken links
grep -oE '\[.*\]\(.*\)' output/<skill-name>/SKILL.md | head -10

Configuration Options

{
  "name": "myskill",
  "description": "When to use this skill",
  "input_dir": "output/myskill_data/",
  "output_dir": "output/myskill/",
  "template": "standard",
  "options": {
    "extract_examples": true,
    "max_examples": 10,
    "generate_faq": true,
    "include_navigation": true,
    "min_category_pages": 5
  }
}

Templates

Standard Template

Full-featured skill with all sections.

Minimal Template

Just SKILL.md and one reference file.

API Reference Template

Optimized for API documentation.

Tutorial Template

Optimized for learning content.

Troubleshooting

| Issue | Diagnosis | Solution | |-------|-----------|----------| | Missing input data | Data directory not found | Run doc-scraper or pdf-extractor first | | Empty SKILL.md | Template failed | Check input format, verify JSON structure | | No categories | Keywords not matched | Provide custom category mapping | | Build hangs | Large dataset | Use doc-splitter first for 10K+ pages | | Invalid structure | Wrong template | Verify template compatibility with content |

References

• Claude Skills Format: https://docs.anthropic.com/skills
• Skill Seekers Builder: https://github.com/jmagly/Skill_Seekers
• REF-001: Production-Grade Agentic Workflows (BP-4, BP-5)
• REF-002: LLM Failure Modes (Archetype 1-4 mitigations)