Progressive Disclosure: Why Skills Stay Cheap

Load the minimum, then more as needed

Skills use progressive disclosure, in three levels. Level 1: the skill's name and description are always available to Claude (a small cost per skill), so it knows what exists. Level 2: when a task matches a description, Claude reads the full SKILL.md body. Level 3: the body can point to additional files (reference documents, templates, scripts) that Claude opens or runs only if the task needs them. Scripts are especially efficient: Claude can run a script and read only its output, without the script's source code consuming context. The consequence is that you can install many skills and keep each one rich, because only the descriptions are paid for up front. It also tells you how to design: keep the description sharp, keep the body focused, and move bulky material into separate files.

The cost of always-on descriptions, run

I ran this with plain Python 3 (standard library only). With illustrative sizes (80 tokens per description, 1,200 per body, 4,000 per reference), 40 skills cost about 3,200 tokens when only descriptions are loaded, versus 51,200 if every body were always loaded and 211,200 if references were too. A task that uses one skill loads about 8,400 tokens in total. The real sizes depend on your skills.

# Progressive disclosure: only name+description are always in context; the body loads when the skill is used.
n_skills = 40
desc_tokens, body_tokens, ref_tokens = 80, 1200, 4000     # illustrative sizes per skill

always_on = n_skills * desc_tokens
print("40 skills, descriptions only (always loaded):", always_on, "tokens")
print("if every body were always loaded instead    :", n_skills * (desc_tokens + body_tokens), "tokens")
print("if bodies AND references were always loaded :", n_skills * (desc_tokens + body_tokens + ref_tokens), "tokens")

used = 1
print("a task that uses one skill (desc + body + one reference):", always_on + body_tokens + ref_tokens, "tokens")

Output:

40 skills, descriptions only (always loaded): 3200 tokens
if every body were always loaded instead    : 51200 tokens
if bodies AND references were always loaded : 211200 tokens
a task that uses one skill (desc + body + one reference): 8400 tokens

Scripts save context

Claude can run a script and read only its output, so long logic costs no context.

Quick check: What is always available to Claude about every installed skill?

• Only its scripts' source code
• Its entire body and all reference files
• Nothing
• Its name and description