mattpocock/skills is Matt Pocock's public agent skills library—workflows he uses daily for real engineering, not vibe coding. The repository has attracted 135,000+ GitHub stars and 11,700+ forks (June 2026), making it the most visible skill collection in the agent ecosystem. Matt Pocock built Total TypeScript, is a former Vercel and Stately engineer, and runs a newsletter with ~60,000 subscribers.
Version 1.0.1 shipped June 17, 2026 with progressive disclosure, shared design skills, and a formal user-invoked vs model-invoked taxonomy. See our v1.0 deep dive for token economics and spec debates.
This explainx.ai article is a map, not a replacement for upstream docs. github.com/mattpocock/skills is canonical. MIT license, no paywall.
explainx.ai also hosts a discoverable skills registry at /skills—ranked listings from many authors with copy-ready install commands. Use Matt's repo for engineering discipline; browse /skills for domain-specific skills (SEO, MCP, analytics, and more).
Quickstart (30 seconds)
From the README:
npx skills@latest add mattpocock/skills
- Pick skills and which coding agents to install on
- Always select
/setup-matt-pocock-skills— run it once per repo - It asks: issue tracker (GitHub, Linear, local files), triage labels, docs save location
- Done — skills are wired to your project
The installer uses skills.sh — the same CLI pattern the Kaggle Agent Skills whitepaper recommends for cross-platform portability.
The thesis: small, composable, not process-heavy
Skills for real engineers. Straight from my
.claudedirectory.
Pocock built these to fix failure modes in Claude Code, Codex, and Cursor—not to replace your judgment with a heavyweight process framework. He explicitly contrasts his approach with GSD, BMAD, and Spec-Kit: those tools own the process, which can hide bugs in the process itself and take control away from you.
These skills are small, easy to adapt, and composable. They work with any model. Hack around with them; make them your own.
Four failure modes (and the skill that fixes each)
The README organizes the entire library around four problems every AI-assisted team hits:
#1: The agent didn't do what I want
Problem: Misalignment—the same gap between "what I meant" and "what got built" that The Pragmatic Programmer calls the core software failure mode.
Fix: A grilling session—force the agent to ask detailed questions before work starts.
| Skill | Invocation | Role |
|---|---|---|
/grill-me | User | Relentless interview until every decision branch is resolved |
/grill-with-docs | User | Same loop + builds domain model, updates CONTEXT.md and ADRs inline |
grilling | Model | Reusable interview loop behind the two grill skills |
Use /grill-me or /grill-with-docs every time you make a change.
#2: The agent is way too verbose
Problem: Agents drop into projects cold and use 20 words where one domain term would do—Eric Evans' ubiquitous language problem applied to LLMs.
Fix: A shared language document. Example from Pocock's course-video-manager repo:
- Before: "There's a problem when a lesson inside a section of a course is made 'real' (i.e. given a spot in the file system)"
- After: "There's a problem with the materialization cascade"
/grill-with-docs and the model-invoked domain-modeling skill build and maintain this vocabulary in CONTEXT.md. Side effects: consistent naming, easier agent navigation, fewer tokens spent thinking.
#3: The code doesn't work
Problem: Alignment without feedback loops = flying blind.
Fix: Static types, browser access, automated tests. For tests, red-green-refactor is non-negotiable.
| Skill | Invocation | Role |
|---|---|---|
/tdd | Model | Red-green-refactor; one vertical slice at a time |
diagnosing-bugs | Model | reproduce → minimise → hypothesise → instrument → fix → regression-test |
/tdd now delegates interface-design guidance to codebase-design (v1.0)—no duplicated deep-module docs inline.
#4: We built a ball of mud
Problem: Agents accelerate coding and entropy. Codebases get complex faster than ever.
Fix: Care about design every day—Kent Beck and John Ousterhout's deep-module philosophy baked into skills.
| Skill | Invocation | Role |
|---|---|---|
/to-prd | User | Quizzes which modules you're touching before creating a PRD |
/improve-codebase-architecture | User | HTML report of deepening opportunities, then grill through your pick |
codebase-design | Model | Deep modules: behaviour behind small interfaces at clean seams |
Pocock recommends running /improve-codebase-architecture once every few days on active codebases.
User-invoked vs model-invoked (v1.0 taxonomy)
v1.0 renamed the old Commands / Skills split. Full definition lives in docs/invocation.md.
| Type | Who triggers | Purpose | Rule |
|---|---|---|---|
| User-invoked | You type /skill-name | Orchestrate workflows | May call model-invoked skills |
| Model-invoked | You or the agent when task fits | Hold reusable discipline | Never call another user-invoked skill |
This maps directly to Pocock's skill-invocable tier proposal—and to the Kaggle whitepaper's progressive disclosure levels.
Router: /ask-matt (user-invoked) sends you to the right flow when you are not sure which skill fits.
The skill map (June 2026)
Always verify against the upstream README—skills are versioned with changesets (currently v1.0.1).
Engineering — daily code work
User-invoked
| Skill | What it does |
|---|---|
| ask-matt | Router over user-invoked skills in this repo |
| grill-with-docs | Grilling + domain model + CONTEXT.md + ADRs |
| triage | Move issues through a state machine of triage roles (GitHub, Linear, local, PRs) |
| improve-codebase-architecture | Scan → HTML report → grill through chosen deepening |
| setup-matt-pocock-skills | One-time repo config: tracker, labels, doc layout |
| to-issues | Break plan/spec/PRD into vertical-slice issues |
| to-prd | Synthesize current conversation into PRD → issue tracker |
| prototype | Throwaway prototype: terminal app for logic, or multiple UI variations on one route |
Model-invoked
| Skill | What it does |
|---|---|
| diagnosing-bugs | Disciplined debug loop for hard bugs and perf regressions |
| tdd | Red-green-refactor; vertical slices |
| domain-modeling | Sharpen glossary; stress-test terms; update CONTEXT.md / ADRs |
| codebase-design | Deep modules: interface, depth, seam, adapter vocabulary |
Productivity — not code-specific
User-invoked
| Skill | What it does |
|---|---|
| grill-me | Interview loop for any plan or design |
| handoff | Compact conversation into handoff doc for another agent |
| teach | Multi-session teaching workspace (v1.0.1: reuse-first components in ./assets/) |
| writing-great-skills | Reference for predictable skill authoring (replaced write-a-skill) |
Model-invoked
| Skill | What it does |
|---|---|
| grilling | Shared interview loop for grill-me and grill-with-docs |
Misc — install when needed
| Skill | What it does |
|---|---|
| git-guardrails-claude-code | Hooks blocking dangerous git (push, reset --hard, clean, etc.) |
| migrate-to-shoehorn | Migrate as assertions to @total-typescript/shoehorn |
| scaffold-exercises | Exercise dirs: sections, problems, solutions, explainers |
| setup-pre-commit | Husky + lint-staged + Prettier + types + tests |
| resolving-merge-conflicts | Loop for in-progress merge/rebase conflicts (v1.0) |
Removed in v1.0 (breaking)
| Old skill | Status |
|---|---|
| caveman | Removed (duplicate test) |
| zoom-out | Removed (unused) |
| write-a-skill | → writing-great-skills |
| diagnose | → diagnosing-bugs |
| design-an-interface | → prototype |
| triage-issue | → triage |
| ubiquitous-language | → domain-modeling |
Philosophy: Real engineering, not vibe coding
The README and skill descriptions repeatedly emphasize discipline over speed:
- TDD first —
/tddenforces red-green-refactor via the model-invoked skill - Planning before coding —
/grill-meand/grill-with-docswon't let you proceed until decisions are explicit - Vertical slices —
/to-issuesbreaks work into independently shippable pieces - Git safety —
/git-guardrails-claude-codeblocks destructive commands unless confirmed - Deep modules + domain language —
/codebase-designand/domain-modelingkeep architecture and vocabulary aligned
This stands in contrast to "generate a feature and hope it works" workflows common in demo-focused agent usage.
How /tdd works (red-green-refactor)
The /tdd skill is the most referenced in Matt Pocock's public posts. The pattern:
- Red — Write a failing test that describes the desired behavior.
- Green — Write the minimum code to make the test pass.
- Refactor — Clean up the implementation while keeping tests green.
- Repeat — Build the feature one vertical slice at a time.
Per the skill description: "Builds features or fixes bugs one vertical slice at a time." This prevents over-engineering and ensures every line of code is verified.
Example workflow:
- User: "Add validation to the login form"
- Agent with
/tdd: "I'll write a test for invalid email first, then implement validation to make it pass."
Install:
npx skills@latest add mattpocock/skills/tdd
How /to-prd and /to-issues chain together
A common pattern in the repository is chaining skills:
- Conversation — Discuss a feature or problem with the agent.
/to-prd— Synthesize the conversation into a Product Requirements Document and file as a GitHub issue. No interview needed—it just summarizes what you already discussed./to-issues— Break the PRD into independently-grabbable GitHub issues using vertical slices (end-to-end functionality, not layers).
This mirrors the "skills compound if you chain them" idea in our agent skills guide and gstack's sprint process.
Install both:
npx skills@latest add mattpocock/skills/to-prd
npx skills@latest add mattpocock/skills/to-issues
Domain-driven design: CONTEXT.md + shared skills
Matt Pocock's architecture workflow in v1.0 is layered:
/grill-with-docsordomain-modeling— build ubiquitous language inCONTEXT.mdand ADRscodebase-design— deep modules, seams, adapters (Ousterhout vocabulary)/improve-codebase-architecture— scan codebase, HTML report, pick one deepening to grill through
Example: If your codebase has processOrder() but the business talks about "fulfillment workflows," domain-modeling flags the mismatch and suggests refactoring toward business language—then codebase-design guides where to put the new interface.
Install the v1.0 stack:
npx skills@latest add mattpocock/skills
# Ensure: setup-matt-pocock-skills, improve-codebase-architecture, codebase-design, domain-modeling
Git guardrails: Preventing destructive commands
The /git-guardrails-claude-code skill is a safety net for agent-assisted git workflows. It sets up Claude Code hooks to block:
git push --forcegit reset --hardgit clean -fgit branch -D- Other destructive commands
Unless you explicitly confirm the action, the hook prevents execution. This is critical when agents have terminal access.
Per the skill description: "Block dangerous git commands (push, reset --hard, clean, etc.) before they execute."
Install:
npx skills@latest add mattpocock/skills/git-guardrails-claude-code
Prototyping: /prototype
The /prototype skill (v1.0, replaces design-an-interface) builds throwaway prototypes to flesh out a design:
- Terminal app — when the question is state or business logic
- Multiple UI variations — radically different approaches toggleable from one route
Use it before committing to an implementation path—same "compare alternatives early" goal as the old design skill, with less sub-agent overhead.
npx skills@latest add mattpocock/skills/prototype
Writing skills: /writing-great-skills
Meta-skill for skill authors. Replaced write-a-skill in v1.0 with writing-great-skills plus a GLOSSARY.md—vocabulary and principles for predictable skills, hunting no-ops down to the sentence level.
Pairs with the Kaggle whitepaper's EDD guidance and Anthropic's agentskills.io spec.
npx skills@latest add mattpocock/skills/writing-great-skills
Install paths and compatibility
All skills use the npx skills@latest add pattern from the skills CLI. They follow the SKILL.md format and work with:
- Claude Code (primary target)
- Other agents that support the SKILL.md convention (see agent skills guide)
Individual skill install:
npx skills@latest add mattpocock/skills/<skill-name>
Examples:
npx skills@latest add mattpocock/skills/tdd
npx skills@latest add mattpocock/skills/grill-me
npx skills@latest add mattpocock/skills/improve-codebase-architecture
Always check the README for the current install command—syntax can change with CLI releases.
Who is Matt Pocock?
Matt Pocock is a TypeScript educator and developer with:
- Total TypeScript — A comprehensive, production-grade TypeScript course with thousands of students.
- Former Vercel engineer — Worked on developer tooling and TypeScript infrastructure.
- Former Stately engineer — Contributed to XState and state machine patterns.
- 60,000+ newsletter subscribers — Regular TypeScript tips, agent workflows, and engineering insights.
- 25,500+ → 135,000+ GitHub stars on mattpocock/skills (June 2026).
His expertise centers on TypeScript, developer education, and production engineering practices. The skills repository is a public release of the workflows he uses to ship code and teach at scale.
Primary channels:
- Newsletter: Sign up for TypeScript and agent tips
- Twitter/X: @mattpocock
- GitHub: github.com/mattpocock
- Total TypeScript: totaltypescript.com
A minimal "try it" path (June 2026)
npx skills@latest add mattpocock/skills— picksetup-matt-pocock-skills,tdd,grill-me,git-guardrails-claude-code- Run
/setup-matt-pocock-skillsonce - On your next feature:
/grill-me→ discuss →/to-prd→/to-issues→/tddon first slice - When lost:
/ask-matt
For larger codebases add /improve-codebase-architecture, /domain-modeling, and /codebase-design (model-invoked—install with the bundle).
v1.0 token tip: Progressive disclosure cuts baseline context ~63%—see v1.0 guide.
How this fits the explainx.ai view of agent skills
The mattpocock/skills repository is a monorepo of opinionated workflows from a single author. explainx.ai hosts discoverable skills at /skills—a ranked directory from many authors, tagged by domain, with install commands you can copy without hunting GitHub READMEs.
The underlying pattern is the same: structured, reusable agent instructions. Many teams use both:
- mattpocock/skills for TDD, planning, and git safety
- /skills for domain skills—marketing, security, MCP builders, analytics integrations, and more
Browse the registry: /skills
Read our agent skills guide: What are agent skills? Complete guide
Comparison: mattpocock/skills vs gstack vs explainx.ai registry
| Project | Author | Focus | Install | License |
|---|---|---|---|---|
| mattpocock/skills | Matt Pocock (Total TypeScript) | Production engineering: TDD, planning, DDD architecture | npx skills@latest add mattpocock/skills/<skill> | MIT |
| gstack | Garry Tan (Y Combinator) | Sprint process: office hours, reviews, QA in browser, shipping | ./setup (team mode) | MIT |
| explainx.ai /skills | Community (many authors) | Discoverable, ranked skills across domains | Browse at /skills | Varies per skill |
All three are complementary: use mattpocock/skills for engineering rigor, gstack for sprint cadence, and /skills to discover domain-specific skills from the broader community.
Privacy and open source
Per the repository:
- MIT license — Fully open source.
- No telemetry — Skills are local instruction files, not SaaS.
- No paywall — All skills free to use and modify.
This contrasts with some agent skill marketplaces that require accounts or usage fees.
Read next (explainx.ai)
- Matt Pocock Skills v1.0 — Progressive Disclosure
- Kaggle Agent Skills Whitepaper Guide
- What are agent skills? Complete guide
- Matt Pocock AI Coding Workshop
- gstack: Garry Tan's open-source software factory
- Browse discoverable skills at /skills
Summary
mattpocock/skills is Matt Pocock's MIT-licensed library for real engineering: four failure modes, user-invoked orchestrators and model-invoked discipline, 135K+ GitHub stars, v1.0.1 with progressive disclosure.
Start with /setup-matt-pocock-skills, then /grill-me, /tdd, and /git-guardrails-claude-code. Scale with /improve-codebase-architecture, domain-modeling, and codebase-design.
Primary repository: github.com/mattpocock/skills · @mattpocockuk · totaltypescript.com
Next: Browse discoverable skills at /skills → · v1.0 progressive disclosure → · Newsletter →
Skill descriptions follow the upstream README and CHANGELOG as of June 2026 (v1.0.1). Star counts change daily—verify at github.com/mattpocock/skills.