skill-builder
Build Claude skills from extracted documentation. Use after doc-scraper/pdf-extractor to generate uploadable skill packages. Use when relevant to the task.
When & Why to Use This Skill
The Skill Builder is a specialized developer utility designed to automate the transformation of raw documentation into structured, production-ready Claude skill packages. By processing data from scrapers and PDF extractors, it generates standardized SKILL.md files, reference directories, and validation scripts. This tool ensures that AI agents are grounded in high-quality data while maintaining consistent architectural patterns and error-handling protocols, significantly reducing the manual effort required to deploy specialized agentic capabilities.
Use Cases
- Documentation-to-Skill Pipeline: Automatically convert technical manuals, API documentations, or internal wikis into uploadable Claude skill packages after initial data extraction.
- Standardizing Agent Knowledge: Enforce consistent organizational standards for AI skills by using predefined templates that include grounding checks, uncertainty escalation, and recovery protocols.
- Rapid Agent Prototyping: Quickly iterate on new agent capabilities by bypassing manual formatting and structural setup, allowing developers to focus on the core logic and data quality.
- Knowledge Base Maintenance: Systematically update and re-validate existing Claude skills when source documentation changes, ensuring the agent's references remain accurate and well-structured.
| name | skill-builder |
|---|---|
| description | Build Claude skills from extracted documentation. Use after doc-scraper/pdf-extractor to generate uploadable skill packages. Use when relevant to the task. |
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:
- PAUSE - Preserve partial build
- DIAGNOSE - Check error type:
Missing input data→ Re-run extractionInvalid content format→ Check parser compatibilityCategorization failed→ Manual category mappingTemplate error→ Check SKILL.md syntax
- ADAPT - Adjust build configuration
- RETRY - Rebuild affected sections (max 3 attempts)
- 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)