# Load all YAML frontmatter from SKILL.md files
metadata = {}
for skill_path in list_skills(skills_dir):
    with open(f"{skill_path}/SKILL.md") as f:
        frontmatter = parse_frontmatter(f)
        metadata[skill_path] = {
            'name': frontmatter['name'],
            'description': frontmatter['description'],
            'allowed_tools': frontmatter.get('allowed_tools')
        }
# Cost: ~25 tokens per skill × N skills
# Total: ~200 tokens for 8 skills

# Parse user request for keywords
task_terms = extract_terms(task_description)

# Extract:
# - File extensions (.xlsx, .pdf, .ts)
# - Action verbs (extract, validate, test, refactor)
# - Domain terms (API, database, authentication)
# - Tool names (jest, pytest, docker)

# Compare task triggers against skill descriptions
matched_skills = []
for skill_path, meta in metadata.items():
    relevance_score = calculate_relevance(task_description, meta['description'])
    if relevance_score > threshold:
        matched_skills.append((skill_path, relevance_score))

# Sort by relevance
matched_skills.sort(key=lambda x: x[1], reverse=True)

# Load full SKILL.md only for top matched skills (typically 1-3)
loaded_skills = []
for skill_path, score in matched_skills[:3]:
    with open(f"{skill_path}/SKILL.md") as f:
        full_content = f.read()
        loaded_skills.append({
            'path': skill_path,
            'content': full_content,
            'relevance': score
        })
# Cost: ~200-400 tokens per loaded skill

# Supporting files are NOT loaded initially

## Examples
See [examples/advanced-usage.md](examples/advanced-usage.md) for more.

# When Claude follows the link, THEN load the file

8 skills × 200 tokens avg = 1,600 tokens
+ All skills loaded regardless of relevance
= Total: 1,600 tokens

8 metadata files × 25 tokens = 200 tokens      (Phase 1)
1-2 matched skills × 200 tokens = 200-400 tokens  (Phase 4)
Supporting files loaded on-demand
= Total: 400-600 tokens
= Savings: 1,000-1,400 tokens (62-87% reduction)

def calculate_relevance(task, description):
    task_lower = task.lower()
    desc_lower = description.lower()
    
    # Extract key terms
    task_terms = extract_terms(task_lower)
    desc_terms = extract_terms(desc_lower)
    
    # Calculate overlap with weights
    common_terms = task_terms & desc_terms
    score = 0
    
    for term in common_terms:
        if is_file_extension(term):      # .xlsx, .pdf, .ts
            score += 10
        elif is_action_verb(term):       # extract, validate, test
            score += 5
        elif is_domain_term(term):       # API, database, auth
            score += 3
        else:                            # general match
            score += 1
    
    return score

User: "Extract fields from invoice.pdf"

Task terms: [extract, fields, invoice, .pdf]

Skill matches:
- pdf-extractor (mentions "PDF extraction") → score: 15
- api-integrator (no PDF mentions) → score: 0
- data-validator (no PDF mentions) → score: 0

Loaded: pdf-extractor only
Tokens: 200 (metadata) + 350 (skill) = 550 tokens
Saved: 1,050 tokens

User: "Test the REST API endpoints for authentication"

Task terms: [test, REST, API, endpoints, authentication]

Skill matches:
- api-testing (mentions "REST API") → score: 20
- code-testing (mentions "testing") → score: 10
- auth-handler (mentions "authentication") → score: 8

Loaded: api-testing, code-testing, auth-handler
Tokens: 200 + 300 + 250 + 200 = 950 tokens
Saved: 650 tokens

User: "Refactor auth module to use JWT, plan carefully"

Task terms: [refactor, auth, JWT, plan, carefully]

Skill matches:
- plan-execute (mentions "refactor", "plan") → score: 25
- api-integrator (mentions "authentication", "JWT") → score: 15
- code-testing (mentions "test") → score: 5

Loaded: plan-execute, api-integrator
Tokens: 200 + 400 + 300 = 900 tokens
Saved: 700 tokens

# Good - Specific triggers
description: Analyze Excel spreadsheets (.xlsx), create pivot tables, generate charts. Use when working with Excel, spreadsheets, data analysis, tabular data.

# Bad - Too vague
description: Helps with files

# Good - Domain specific
description: REST API testing with Bearer auth, OAuth, rate limiting. Validates JSON responses against schemas.

# Bad - Generic
description: Test things

# Good - File extensions
description: Extract data from PDF forms (.pdf), handle OCR, validate field types.

# Bad - Generic
description: Extract data from documents

# Good - Action oriented
description: Extract, transform, validate, parse, generate, analyze JSON data.

# Bad - Passive
description: Work with JSON

# SKILL.md loaded (300 tokens)

## Examples
See [examples/advanced-usage.md](examples/advanced-usage.md)

## Templates
Use [templates/config.yaml](templates/config.yaml)

"Load examples/advanced-usage.md"
→ File loaded (200 tokens)
→ Total: 300 + 200 = 500 tokens (only when needed)

SKILL.md with all examples inline: 800 tokens (always loaded)

Issue: Task not matching any skill
Solution:
1. Check skill descriptions include relevant keywords
2. Verify YAML frontmatter is valid
3. Add more specific triggers to skill descriptions

Issue: 5+ skills loaded for simple task
Solution:
1. Make skill descriptions more specific
2. Add negative triggers ("NOT for...")
3. Use allowed-tools to narrow scope

Issue: Irrelevant skill matched
Solution:
1. Review skill description keywords
2. Add domain-specific terms
3. Remove generic terms that match everything