Matt Pocock Skills v1.0: 63% Fewer Tokens With Progressive Disclosure
Matt Pocock shipped mattpocock/skills v1.0 with progressive disclosure—63% token savings, /codebase-design, /domain-modeling, /grilling, /ask-matt, and a spec debate on skill-invocable tiers for Anthropic Agent Skills.
Matt PocockAgent SkillsTypeScriptClaude CodeToken Optimization
Matt Pocock shipped mattpocock/skills v1.0 in June 2026—the first semver major since his repo became the most-starred Agent Skills collection on GitHub (135,000+ stars, 11,700+ forks).
The headline number: 63% lower token costs via progressive disclosure—load short summaries first, pull full skill bodies only when needed.
For teams burning context on bloated SKILL.md files in every Claude Code session, v1.0 is a pattern worth copying even if you never install a single slash command. Full skill inventory and four failure modes: Matt Pocock agent skills deep dive.
Early agent skills dumped entire workflows into context at session start—planning guides, TDD checklists, architecture essays—whether or not the task needed them.
Pocock's v1.0 pattern:
snippet
Session start → compact skill index (names + one-line triggers)
│
User or model invokes /tdd (or matched intent)
│
▼
Full TDD skill body loads → agent executes with complete rules
Result: Baseline context stays lean; depth arrives on demand. Pocock reports 63% token reduction across typical sessions—meaning cheaper runs, longer conversations, and less Headroom-style compression pressure.
This mirrors web performance (lazy loading) and Karpathy's LLM Wiki index-first navigation—don't load what you have not asked for yet. The Kaggle Agent Skills whitepaper formalizes the same three-level model: metadata → body → bundled resources.
v1.0 Architecture: Shared Design Skills
The 1.0.0 changelog is the real story—not just token savings, but composition:
Change
Impact
codebase-design (new)
Deep-module vocabulary (interface, depth, seam, adapter)—generalized from improve-codebase-architecture/LANGUAGE.md
User-invoked skills orchestrate; model-invoked skills hold reusable discipline
A user-invoked skill may call model-invoked skills
A user-invoked skill must never call another user-invoked skill
Model-invoked skills can also fire automatically when the task fits
This is the production implementation of the three-tier debate below—today, "skill-invocable" is approximated by making helper skills model-invoked and accepting the token cost.
Four Failure Modes → Skill Mapping
The README frames the entire library around four problems:
Pocock positions these against GSD, BMAD, and Spec-Kit—frameworks that own the whole process. His skills stay small and composable so you keep control when the process breaks.
Ubiquitous language example (from README):
Before: "when a lesson inside a section of a course is made 'real'..."
After: "problem with the materialization cascade"
That one term replaces a paragraph in every future session.
New Skills in v1.0
Skill
Purpose
/codebase-design
Deep modules, boundaries, dependency direction—architecture you can maintain
Adversarial questioning loops—stress-test plans before code
/ask-matt
Meta-router: sends you to the right skill for your question
These extend the production set we covered in Matt Pocock's agent skills for real engineers—/tdd, /to-prd, /improve-codebase-architecture, /git-guardrails-claude-code—with more systematic design tooling.
v1.0.1 patch (June 17)
teach is now reuse-first: lessons build from components in ./assets/ (stylesheets, quiz widgets, simulators). The agent reads ./assets/ before authoring and extracts new reusable pieces instead of inlining one-offs.
@geren8te asked how "writing great skills" was authored—preferences vs research-backed
@johnlindquist noted /review behaves like a script or subagent, not a lightweight skill
@iocapon praised /ask-matt as a neat routing pattern
@ShivamS1123 and educators use /teach for instruction workflows
Video walkthrough: Pocock pointed to aihero.dev for the v1.0 changes first.
The Spec Gap: Three Tiers of Invocable
Pocock's most technical v1.0 thread is not a skill—it is a spec proposal for Anthropic's Agent Skills format.
Today (simplified):
Tier
Behavior
User-invocable
Slash command; description hidden from model (saves tokens)
Model-invocable
Description always in context; model can auto-trigger
Problem: Composite workflows. Example /review:
Run automated checks
Check against spec
Check coding standards
Step 1 wants to be /run-automated-checks—reused by /review and callable alone. But extracting it forces model-invocable status → its description burns tokens forever, even when you only want it inside /review.
Pocock's ask: Add skill-invocable — invokable by users or parent skills only, never auto-suggested to the model, no standing description in context.
Workaround today: write descriptions like "never invoke except from other skills"—spec-legal, wasteful, honest about the hack.
@dexhorthy (HumanLayer) connected this to post-IDE tooling—skills architecture is load-bearing for the next generation of dev environments.
Install and Use
bash
npx skills@latest add mattpocock/skills
Works across agents implementing the Agent Skills spec—Claude Code, Cursor with skills support, Codex, and compatible harnesses via skills.sh.
Required first run:
snippet
/setup-matt-pocock-skills
Configures issue tracker (GitHub / Linear / local), triage labels, and docs directory.
Suggested starter path:
/setup-matt-pocock-skills — once per repo
/tdd + codebase-design — red-green-refactor with interface discipline
/grill-me or /grill-with-docs — alignment before code
Token efficiency (63%) makes discipline affordable at scale
Progressive disclosure is the missing economic layer—without it, rigorous skills price themselves out of long sessions.
Summary
Matt Pocock Skills v1.0.1 is three releases in one:
Shared design skills — codebase-design + domain-modeling as composable primitives
Progressive disclosure — ~63% token reduction
Formal taxonomy — user-invoked orchestrators vs model-invoked discipline
The skill-invocable tier debate matters for composite skills—/review calling /run-automated-checks should not tax every session. If Anthropic adopts Pocock's three-tier model, the whole ecosystem gets cheaper overnight.
