Skill Builder

Do NOT use for: editing existing skills (use editor), searching skills (use lev get), or installing skills (use clawdhub).

Quick Decision Tree

What does the user want?
│
├─→ Convert existing docs to skill?
│   ├─→ Website only? → Website Scraping
│   ├─→ GitHub repo only? → GitHub Analysis
│   ├─→ PDF only? → PDF Extraction
│   └─→ Multiple sources? → Unified Multi-Source
│
├─→ Create NEW skill from scratch?
│   └─→ Route to skill-creator
│       - SKILL.md format: YAML frontmatter + markdown body
│       - Progressive disclosure: metadata → body → references
│       - Body <500 lines, description is PRIMARY trigger
│       - See skill-creator skill for full standards
│
├─→ Combine/merge existing skills?
│   └─→ Route to BOTH:
│       1. Analyze existing skills (codifier patterns)
│       2. Author merged skill (skill-creator standards)
│       3. Ensure router pattern if subsumes others
│
├─→ Export for non-Claude platform?
│   └─→ Package with --target (gemini|openai|markdown)
│
└─→ First time? → references/setup.md

Skill Installation from External Sources

When intake routes a skills.sh URL or skill:// to skill-builder:

Step 1: Acquire → skills-db staging

# Extract GitHub repo URL from skills.sh page (WebFetch for the link ONLY)
git clone --depth 1 {repo} /tmp/skill-intake-{ts}/
# Find the skill: find /tmp/skill-intake-{ts}/ -name "SKILL.md" -path "*{name}*"
# Stage to skills-db (NOT directly to active):
cp -r /tmp/skill-intake-{ts}/skills/{name}/ ~/.agents/skills-db/_workshop/{source}/{name}/
rm -rf /tmp/skill-intake-{ts}/

Step 2: Validate (HARD GATES — run on staged copy)

file=~/.agents/skills-db/_workshop/{source}/{name}/SKILL.md
head -1 "$file" | grep -q "^---$"           # Has YAML frontmatter
grep -q "^name:" "$file"                     # Has name field
grep -q "^description:" "$file"              # Has description field
awk '/^---$/{c++} c==2{exit}' "$file"        # Has closing ---

If any hard gate fails → REJECT. Move to .archive/ or delete. Do NOT promote.

Step 3: Prior Art Check

• Search ~/.agents/skills/ for name/trigger overlap
• Exact match → compare quality (line count, scoring), keep better version
• Partial overlap (>30% triggers) → recommend merge
• No overlap → proceed to scoring

Step 4: Quality Score (run on staged copy, BEFORE promotion)

Score 1-10 on 5 dimensions (read the SKILL.md content):

Grades: A (8+) promote, B (7-7.9) promote with note, C (5-6.9) hold in _todo, D (<5) reject

Step 5: Catalog (move from staging to skills-db home)

# A/B grade → catalog in skills-db (DEFAULT destination):
mv ~/.agents/skills-db/_workshop/{source}/{name}/ ~/.agents/skills-db/{domain}/{name}/
# C grade → move to _todo for enhancement:
mv ~/.agents/skills-db/_workshop/{source}/{name}/ ~/.agents/skills-db/_todo/{name}/
# D grade → reject:
mv ~/.agents/skills-db/_workshop/{source}/{name}/ ~/.agents/skills-db/.archive/{name}/

Step 5b: Activate (ONLY if user requests)

# Only when user explicitly wants the skill loaded into Claude Code:
cp -r ~/.agents/skills-db/{domain}/{name}/ ~/.agents/skills/{name}/
# Or symlink:
ln -s ~/.agents/skills-db/{domain}/{name}/ ~/.agents/skills/{name}

NOTE: Most skills stay in skills-db. Only day-to-day/global operational skills get activated. The user decides when to activate — skill-builder should PROPOSE activation, not assume it.

Step 6: Lifecycle Check

• Is this skill a candidate for merging into an existing hub/router?
• Does it overlap with 2+ existing skills in the same domain?
• If yes → recommend leaf→hub→router graduation

Skill Lifecycle: Leaf → Hub → Router

Skills grow organically through 3 stages:

Growth triggers

• Merge: 2+ skills share >30% intent overlap → merge into hub
• Router: Merged hub exceeds ~400L → graduate to router (move content to sub-skills)
• Split: Single skill >500L without references/ → split into skill + references/

Router graduation checklist

1. Create {domain}-hub/ directory
2. Write SKILL.md routing header (<100L): decision tree + sub-skill table
3. Add skill_type: router and subsumes: [list] to frontmatter
4. Keep sub-skills as independent SKILL.md files
5. Router description MUST include ALL sub-skill triggers (union of tags)

Full Pipeline (The Correct Order)

Every codification job follows this pipeline. Do NOT skip steps.

1. PRIOR ART CHECK → Does this skill already exist?
   ├─ lev get "{name}" --scope=knowledge --pattern="SKILL.md"
   ├─ grep -rl "{name}" ~/.claude/skills/
   └─ If found:
      • Exact match → use as-is or enhance existing, skip to step 4
      • Partial overlap → recommend merge/consolidation with existing
      • Related but different → proceed, note in description for routing

2. ESTIMATE (websites only) → How big is this job?
   └─ skill-seekers estimate configs/{name}.json
      • < 5K pages: single skill, proceed normally
      • 5K-10K: consider category split
      • 10K+: must split with router strategy

3. EXTRACT → Get the raw content
   ├─ Website:  skill-seekers scrape --name {name} --url {url}
   ├─ GitHub:   skill-seekers github --repo {owner/repo}
   ├─ PDF:      skill-seekers pdf --pdf {file} --name {name}
   └─ Unified:  skill-seekers unified --config {config.json}

4. ENHANCE → Transform raw extraction into a real skill
   └─ skill-seekers enhance output/{name}/

   ⚠️ KNOWN BUG (skill-seekers ≤2.7.4): enhance passes file path
   as positional arg to claude CLI. SKILL.md never gets updated.
   USE WORKAROUND: scripts/enhance-workaround.sh output/{name}

5. REVIEW → Check the enhanced output
   • Compare frontmatter against standards (what/how/when/why + triggers)
   • Verify description is the PRIMARY trigger mechanism
   • Check progressive disclosure (SKILL.md <500 lines, rest in references/)
   • Validate: no stats-only wrappers, real actionable content

6. PACKAGE → Bundle for distribution
   └─ echo "y" | skill-seekers package output/{name}/ [--target claude|gemini|openai|markdown]

7. INSTALL → Put it where it belongs
   ├─ Global:  cp -r output/{name} ~/.claude/skills/{name}/
   ├─ Project: cp -r output/{name} .claude/skills/{name}/
   └─ Upload:  output/{name}.zip → https://claude.ai/skills

Quick Reference: Essential Commands

1. Installation Check

command -v skill-seekers || python3 -m skill_seekers --version

If not installed, see references/setup.md for uv/venv/pip auto-detection.

2. Website Scraping (Preset)

skill-seekers scrape --config configs/react.json --enhance-local
skill-seekers package output/react/

3. Website Scraping (Custom)

skill-seekers scrape --name myframework --url https://docs.example.com/
skill-seekers package output/myframework/

4. GitHub Repository Analysis

skill-seekers github --repo facebook/react
skill-seekers package output/react/

Supports deep AST parsing for Python, JavaScript, TypeScript, Java, C++, Go. Extracts APIs, issues, PRs, changelogs, and detects doc-vs-code conflicts.

5. PDF Extraction

skill-seekers pdf --pdf docs/manual.pdf --name myskill
skill-seekers package output/myskill/

Supports OCR for scanned PDFs, table extraction, password-protected files, and parallel processing.

6. Unified Multi-Source (Docs + GitHub + PDF)

skill-seekers unified --config configs/react_unified.json
skill-seekers package output/react/

Combines all sources with automatic conflict detection and intelligent merging.

7. Multi-Platform Export

# Claude (default)
skill-seekers package output/react/

# Google Gemini
skill-seekers package output/react/ --target gemini

# OpenAI ChatGPT
skill-seekers package output/react/ --target openai

# Generic Markdown (any LLM)
skill-seekers package output/react/ --target markdown

For large docs (10K+ pages), async mode, three-stream GitHub analysis, splitting strategies, and troubleshooting, see references/advanced-commands.md.

Frontmatter Design Philosophy

The Description is Everything

The description field is the PRIMARY trigger mechanism. Agents read descriptions to route. Body loads AFTER triggering.

Every description needs What/How/When/Why + tag soup: