Progressive Disclosure: Why You Can Install 30 Skills and Pay for Almost Nothing

Claude Code Skills use progressive disclosure to load only relevant instructions per request, allowing users to install dozens of Skills without bloating context. A Skill loads in three stages: frontmatter always, body on request match, and files only when referenced. This design keeps sessions efficient and encourages modular Skill writing.

Part 5 of the "Automating Playwright with Claude Code" series. In Part 4, we built a single playwright-form-tester Skill. This post explains the mechanism that lets you install dozens more like it without bloating every session — and shows how to structure a Skill to actually take advantage of it. If you've ever wondered "wait, if I install 10 Skills, does Claude load all 10 into context on every single request?" — the answer is no, and the reason why is one of the more elegant parts of how Claude Code Skills are designed: progressive disclosure . Understanding it changes how you write Skills, not just how many you install. It's the difference between a Skill and a bloated CLAUDE.md. A CLAUDE.md file is always fully in context. A Skill isn't — and that's the entire point.Completed Part 4 https://dev.to/aswani25/what-is-skillmd-building-a-reusable-playwright-testing-skill-for-claude-code-27b1 of this series, with the playwright-form-tester Skill installed. Comfortable editing a SKILL.md file and creating subfolders alongside it. Every installed Skill loads in three stages, only as needed: | Layer | What's in it | When it loads | |---|---|---| | 1. Frontmatter | name + description ~100 tokens | Always, for every Skill, at session start | | 2. Body | The full SKILL.md instructions | Only when your request matches the description | | 3. Files | references/ , scripts/ , assets/ | Only when a step in the body actually calls for that specific file | This is why installing 30 Skills doesn't mean paying for 30 Skills' worth of context on every request — you're only ever paying for Layer 1 across the board, plus Layers 2 and 3 for the one or two Skills that actually apply to what you asked. At the start of every Claude Code session, only this much of each installed Skill gets loaded: --- name: playwright-form-tester description: Test HTML forms using Playwright CLI. Use this whenever the user asks to test, validate, or verify a form login, signup, checkout, contact, etc. on a web page, or mentions form submission, validation errors, or success messages. --- The moment you say something like "test the checkout form" , Claude matches it against the description field above, and only then pulls in the full body: Process 1. Navigate to the target page with playwright-cli navigate <url . 2. Run playwright-cli snapshot to get element references e.g. e12 . 3. Fill each field with playwright-cli fill <ref "<value " . ... This is the layer most people don't take advantage of, and it's the one that matters most once a Skill grows complex. If a step in your body references a file — a script, a longer reference doc, a template — that file is only opened if that specific step actually runs. .claude/skills/playwright-form-tester/ ├── SKILL.md ├── scripts/ │ └── check-known-selectors.sh └── references/ └── negative-test-checklist.md check-known-selectors.sh and only sees the result, not the whole script. references/negative-test-checklist.md only gets read if the workflow step says "consult the negative test checklist" — otherwise it sits on disk, costing nothing.Let's apply this to the Skill from Part 4. Right now, our negative-testing guidance is baked directly into the body: Notes - Always test one valid case and at least one invalid case per form. - If the form has a CAPTCHA or OTP step, stop and ask the user how to proceed rather than guessing. That's short enough to leave inline — but imagine it grew into a 40-line checklist covering SQL injection payloads, Unicode edge cases, and field-length boundaries. At that size, it belongs in a reference file instead: mkdir -p .claude/skills/playwright-form-tester/references references/negative-test-checklist.md . Notes - Always test one valid case and at least one invalid case per form. - For a full negative-test checklist injection payloads, boundary values, Unicode edge cases , consult references/negative-test-checklist.md . Now that checklist only enters context on the requests where Claude actually needs it — not on every single form test. If a Skill isn't firing when you expect it to, the description is almost always the reason — because it's the only thing Claude has to go on before deciding to load the rest. Too vague — likely won't fire reliably description: Helps with testing. Specific, with real trigger phrases description: Test HTML forms using Playwright CLI. Use this whenever the user asks to test, validate, or verify a form login, signup, checkout, contact, etc. on a web page, or mentions form submission, validation errors, or success messages. Progressive disclosure is why Skills scale where a giant CLAUDE.md file doesn't — you get the benefit of a large, well-organized library while only ever paying for the small slice that's relevant to what you're doing right now. In the next post, we'll use this exact structure to grow our single form-tester Skill into a small pack covering page objects, flaky-test debugging, and locator strategy — much like the framework packs the wider QA-skills ecosystem has started building. Have you restructured a Skill to use references/ or scripts/ yet? Let me know how it went in the comments