Layer 2: Skill Metadata — The Cheap, Always-Scanned Descriptor

Layer 1 (previous subtopic) is always loaded and universal. Layer 2 is the first CONDITIONAL layer, but with an important twist: it's conditional in what it triggers, not in whether it gets scanned. Per this course: Layer 2: Skill Metadata — Comprises only the YAML frontmatter, about 2-3 lines (< 200 tokens).

The key design insight is the tiny size. A skill might contain a large, detailed body of instructions, examples, and edge-case handling (that's Layer 3, next subtopic) — but Claude doesn't need to read all of that just to decide WHETHER a given skill is relevant to the current request. It only needs a short descriptor: what is this skill called, and roughly when should it be used? That's exactly what the YAML frontmatter provides — a tiny, structured summary sitting at the top of the skill.md file, deliberately kept under 200 tokens.

This size constraint is what makes the whole system scale to hundreds of skills. If Claude has, say, 200 skills available, scanning 200 full skill bodies (each potentially thousands of tokens) to figure out which ONE is relevant would itself blow the context budget before any actual task work happened. But scanning 200 metadata descriptors at under 200 tokens each is a completely different, much cheaper proposition — this is precisely the mechanism this course credits with letting the system 'use 100s of skills without hitting context limits.'

So Layer 2's role is specifically triage: it's the layer Claude scans across ALL available skills to decide which ONE (or few) are actually relevant to the current request — only THOSE selected skills then trigger Layer 3 (loading their full body). Layer 2 metadata being small and cheap is what makes it feasible to check EVERY skill's relevance on every turn, rather than needing some separate, heavier pre-filtering step — the triage decision itself stays lightweight, no matter how large the total skill library grows.

# Modeling Layer 2 (Skill Metadata) as the cheap, ALWAYS-SCANNED
# triage layer -- small enough to check every skill's relevance
# every turn, even across hundreds of skills.

SKILL_LIBRARY_METADATA = [
    {"name": "refund-processing",
     "description": "Use when a customer requests a refund or asks about refund status."},
    {"name": "password-reset",
     "description": "Use when a user is locked out or needs to reset credentials."},
    {"name": "shipping-tracking",
     "description": "Use when a customer asks where their order is."},
    # ... imagine 200 more entries, each still under ~200 tokens
]

def metadata_size_tokens(entry: dict) -> int:
    """Toy token estimate (chars/4) -- illustrating why this stays cheap
    even scanned across the WHOLE library every turn."""
    return len(entry["name"] + entry["description"]) // 4

def scan_for_relevant_skills(user_message: str, library: list[dict]) -> list[str]:
    """Layer 2's job: cheap triage across ALL skills' metadata,
    deciding which (if any) are relevant -- WITHOUT loading full bodies."""
    relevant = []
    for entry in library:
        keywords = entry["description"].lower().split()
        if any(kw.strip(".,") in user_message.lower() for kw in keywords):
            relevant.append(entry["name"])
    return relevant

total_metadata_cost = sum(metadata_size_tokens(e) for e in SKILL_LIBRARY_METADATA)
print(f"Total Layer 2 scan cost across {len(SKILL_LIBRARY_METADATA)} skills: "
      f"~{total_metadata_cost} tokens (cheap, even at hundreds of skills)")

relevant = scan_for_relevant_skills("Where is my order? It's been a week.", SKILL_LIBRARY_METADATA)
print(f"Relevant skill(s) found via metadata scan: {relevant}")
# Only THESE selected skill(s) trigger Layer 3 -- loading their full body