skill-progressive-disclosure-design
Decide how to split skill content between SKILL.md and reference files for context efficiency and reliable triggering. Use this whenever creating a new Claude skill, refactoring an existing one, or when a SKILL.md is growing past 300-400 lines. Also trigger when the user mentions "progressive disclosure", "reference files", "splitting skills", "skill bundling", "context window for skills", "SKILL.md too long", "what goes in references/", "skill structure", or expresses any uncertainty about where to put content within a skill. Use this even if the user phrases the question as a triggering problem ("how do I make my skill trigger better"), because that question is often confused with the splitting question and needs to be disentangled first.
git clone --depth 1 https://github.com/samber/cc-skills /tmp/skill-progressive-disclosure-design && cp -r /tmp/skill-progressive-disclosure-design/skills/skill-progressive-disclosure-design ~/.claude/skills/skill-progressive-disclosure-designSKILL.md
# Skill Progressive Disclosure Design
Each section that recommends a direction includes explicit pros and cons. The decisions in this skill are trade-offs, not rules. The model using this skill should reason from the trade-offs to the user's specific situation rather than apply rules blindly.
## Triggering vs. disclosure: separate these first
Two problems get conflated and need separating before any splitting decision.
**Triggering** is whether Claude invokes the skill at all. Driven entirely by the YAML `description`. File splitting does not affect triggering. If the question is "my skill doesn't trigger reliably", do not split files, fix the description (use `run_loop.py` from the `skill-creator` skill).
**Progressive disclosure** is what loads after the skill activates. SKILL.md body always loads. `references/*` only loads when SKILL.md tells the model to read a specific file. `scripts/*` executes without loading into context at all. This is where context protection happens.
If the user is asking about splitting because of triggering issues, surface the confusion first and redirect.
## Default: do not split
A monolithic SKILL.md beats a split one until proven otherwise.
Split only when at least one is true:
- SKILL.md exceeds ~400 lines and content has natural branches.
- Empirical evidence (eval transcripts) shows the model wasting context on irrelevant sections.
- Specific content is large and only needed in narrow conditions.
**Pros of staying monolithic:**
- Single context load, no router prose to maintain.
- No tool-call overhead from reading references.
- No risk of the model loading the wrong reference or skipping a needed one.
- Easier to maintain: one file, one source of truth.
- Better for highly interconnected content where context is global.
- Easier for human reviewers to read end-to-end.
**Cons of staying monolithic:**
- Every invocation pays the full token cost, even when only 10% of the content is relevant.
- Does not scale past ~500 lines without degrading the model's ability to find what matters.
- No mechanism to gate rare or niche content.
- All content must justify its always-loaded status.
- Maintenance gets harder as the file grows.
## Three split axes that work
### 1. Variant branch
User intent selects exactly one path. SKILL.md holds the decision logic and shared workflow. Each `references/<variant>.md` holds path-specific detail.
```
my-skill/
├── SKILL.md # decision tree + shared steps
└── references/
├── variant-a.md
├── variant-b.md
└── variant-c.md
```
Examples of clean variants: cloud provider, database engine, framework choice, output format, language.
**Pros:**
- Each invocation loads only the matching variant; large savings when variants are big.
- Variants evolve independently, simplifying maintenance.
- Adding a new variant does not bloat existing content.
- Mental model is easy: select one path based on input.
- Maps cleanly to user intent that already mentions the variant.
**Cons:**
- Requires routing logic in SKILL.md, eating back some of the line savings.
- Cross-cutting changes touch every variant file, multiplying effort.
- Risk of treatments diverging across variants over time.
- If user intent is ambiguous, the model may load multiple variants and lose the savings.
- If variants share more than ~60% of their content, the abstraction breaks down.
### 2. Workflow vs. reference data
SKILL.md holds the procedure (verbs, sequence, decisions). `references/` holds lookup material queried by key.
Good reference content: schemas, error code tables, API surface listings, example galleries, configuration option matrices, design tokens.
**Pros:**
- Highest leverage of all splits: lookups are narrow, the model reads one entry.
- Natural conceptual boundary (procedure vs. data).
- Reference can grow large without affecting per-invocation cost.
- Adding new reference entries does not touch the workflow.
- Reference data can often be machine-generated and regenerated.
**Cons:**
- The model must know what to look up before reading. Pointer must encode lookup keys explicitly.
- Fails when the workflow needs to weave reference data inline rather than at discrete points.
- Splits content that is conceptually unified, harder for human readers.
- The model may miss broader context that lives only in the reference.
- Lookup data that is small (under ~50 lines total) is rarely worth splitting.
### 3. Depth tier (common path vs. edge cases)
SKILL.md covers the 80% case. `references/edge-cases.md` covers the rest.
The pointer must read like:
> If you see X, Y, or Z, stop and read `references/edge-cases.md` before continuing.
**Pros:**
- Common path stays minimal, fast, cheap.
- Edge cases can be exhaustive without polluting every invocation.
- Easy to extend edge-case coverage without touching the common path.
- Mirrors how experts work: defaults first, exceptions on demand.
**Cons:**
- The load condition must be sharp and observable from user input. Most edge cases do not satisfy this.
- Vague conditions cause either always-loading (waste) or never-loading (dead weight).
- Edge cases get less testing because evals naturally cluster on common queries.
- The model may follow the common path past a point where it should have escalated.
- The 80/20 estimate is often wrong; what looked like an edge case turns out to be common.
## Splits that do not work
For each anti-pattern, "why it appears attractive" shows what makes designers reach for it; "why it fails" shows what goes wrong in practice.
### Topic-based splits where invocations do not cluster by topic
A testing skill split into `unit.md`, `integration.md`, `mocks.md` is a typical example.
**Why it appears attractive:**
- Conceptually clean, mirrors how a human would organize documentation.
- Easy to navigate as a maintainer.
- Plausibly reduces context per invocation.
**Why it fails:**
- Real tasks span 2-3 topics, forcing multiple loads per inComprehensive guide for building Chrome extensions with Manifest V3. Use this skill whenever the user mentions Chrome extension, browser extension, manifest.json, content script, service worker (in extension context), popup, side panel, chrome.runtime, chrome.tabs, chrome.storage, chrome.scripting, background script, MV3, Manifest V3, or any Chrome extension API. Also trigger when the user wants to inject scripts into web pages, communicate between page and background, bypass CSP from a content script, build an RPC layer over chrome messaging, or publish to the Chrome Web Store. Covers both new extension projects and adding features to existing ones. Do NOT use for framework-specific questions.
Conventional Commits v1.0.0 branch naming, worktree naming, and commit message standards for GitHub and GitLab projects. Use when creating branches, naming worktrees, writing commits, generating commit messages, reviewing branch conventions, or setting up changelog automation. Apply when your project needs consistent git history, SemVer-driven releases, parseable changelog generation, or automatic issue closing. Trigger when the user asks how to name a worktree, create a git worktree, or organize worktrees alongside branches.
Design end-of-article CTAs (calls-to-action placed at the bottom of blog posts, newsletters, essays, articles, or any long-form content). Use this skill whenever the user asks to write, design, review, or improve a CTA at the bottom of an article, blog post, or essay; mentions "end-of-post CTA", "bottom of the article", "call-to-action", "signup box", "newsletter CTA", "subscribe block", "what should I put at the bottom", "how do I get readers to subscribe / share / book a call / buy / follow / join / download"; or asks how to convert article readers into subscribers, leads, customers, community members, or supporters. Also trigger when the user wants A/B testing guidance or accessibility review for a CTA block. Covers independent / personal writing, newsletter publications, and brand / content-marketing blogs across any topic — tech, finance, food, climate, design, lifestyle, B2B, B2C. Produces both the copy (content) and the structural / visual design (form), matched to the user's objective and audience.
>
Codifies how someone or a brand writes — prose mechanics (lexicon, syntax, rhythm, structure, signature moves) independent of emotional tone. Output: PROSE.md. Three modes: BUILD a fresh guide from SOUL.md + TONE.md + discovery interview; ADAPT an existing guide to a new channel; AUDIT a corpus for prose patterns before codification. Use when: writing rules for a content factory, codifying ghostwriting voice for multi-writer consistency, defining banned words and sentence-length targets, building a house style guide, reverse-engineering prose from a corpus, porting style across channels. Trigger on: PROSE.md, writing style guide, prose guide, house style, ghostwriter style, writing playbook, brand writing mechanics, signature moves. NOT for: writing actual content (→ linkedin-ghostwriting, technical-article-writer, press-release-writer), removing AI patterns (→ humanizer), tone decisions (→ copywriting-tone-of-voice), hooks (→ copywriting-hooks), CTAs (→ copywriting-cta).
Build a brand tone of voice guide (TONE.md) via discovery, voice definition, and channel modulation. Outputs voice attributes with do's/don'ts, NN/g positioning, tone modulation matrix, lexicon, mechanics, and channel rules — consumed by downstream content skills writing on-brand copy. Covers B2B SaaS, B2C/D2C, NGO, public sector, consulting, industrial, product-led, personal, and volunteering brands; researches uncovered contexts (politics, regulated niches, religious orgs, gaming) on demand. Also adapts an existing TONE.md to a new channel (blog → LinkedIn, web → Twitter/X, in-product UI). Optionally consumes SOUL.md to pre-fill brand identity. Apply when the user wants to create a TONE.md, define brand voice, port voice to a new channel, refresh an outdated voice, or set up a content factory writing across many supports. Not for writing individual posts, articles, emails, or UI strings (→ dedicated writing skills), nor SOUL.md, PROSE.md, DESIGN.md.
CRXJS Chrome extension development — true HMR for popup, options, content scripts, side panels, manifest-driven builds, dynamic content script imports (`?script`, `?script&module`), and `defineManifest` for type-safe manifests. Uses Vite as its build tool. Use when the user mentions CRXJS, crxjs, @crxjs/vite-plugin, 'extension with hot reload', 'HMR for chrome extension', or wants to set up a CRXJS-based Chrome extension project with any framework (React, Vue, Svelte, Solid, Vanilla). Also trigger when the user has an existing CRXJS project and wants to add features, fix HMR issues, or configure content scripts with CRXJS. For general Chrome extension architecture (messaging, CSP, storage, permissions) -> See `samber/cc-skills@chrome-extension` skill.
Deep research skill — broad parallel web searches, multi-source validation, confidence tracking, cited Markdown report. Supports 11 research types: market (TAM/SAM, segments, pricing, trends), domain (industry structure, ecosystem, regulatory landscape), technical (architecture, tools, benchmarks), competitive (competitor teardown, positioning, win/loss), product (feature analysis, reviews, roadmap signals), academic (literature survey, citation networks, key authors), person/org (due diligence on a company or public figure), financial (funding rounds, valuation multiples, revenue signals), legal (IP, patents, litigation, compliance), trend (emerging signals, foresight, scenario mapping), community (ecosystem health, key voices, governance, fragmentation). Use when asked to: 'research <topic>', 'deep dive on X', 'analyze the landscape', 'competitive analysis', 'compare these options', 'who are the players in Z', 'literature review', 'background on Y', 'what papers exist on X', 'product teardown', 'technology evaluation', 'regulatory overview', 'funding landscape', 'what trends are emerging in X', 'patent landscape', 'community health', or any request requiring scanning many sources and producing a cited written analysis. Apply whenever the deliverable is a thorough, sourced report rather than a quick answer. Trigger even when phrased casually: 'look into X', 'what's the deal with Y', 'dig into Z', 'I need to understand the space', 'catch me up on X'.