mattpocock/skills Guide: 27 AI Skills for Real Vibe Coding
Master Matt Pocock's 27 open-source AI agent skills for Claude Code, Codex, and Cursor. Covers 30s setup, /grill-with-docs workflow, TDD, and Caveman combo.
Table of Contents
- 1. Creator & Core Philosophy
- 2. Why You Need It: 4 Agent Failure Modes
- 3. 30-Second Setup
- 4. Two Core Concepts
- 5. The 7-Step Vibe Coding Recipe
- 6. Three Everyday Workflows
- 7. All 27 Skills at a Glance
- 8. Eight Practical Field Tips
- 9. Stacking with Caveman & Ponytail
- 10. Frequently Asked Questions
1. Creator & Core Philosophy
Matt Pocock, known across the TypeScript ecosystem as the creator of Total TypeScript, describes mattpocock/skills as "the skills I use every day to do real engineering with AI agents."
Heavyweight frameworks like GSD, BMAD, or Spec-Kit take over your entire pipeline—which means when a step goes sideways, fixing the process itself becomes a project. Matt's skills follow four opposite principles:
- Small — each skill is a focused bundle of rules.
- Composable — pick only the pieces your current task needs.
- Easy to hack — plain Markdown text files you can edit directly.
- Model-agnostic — designed to work across Claude, Codex, Gemini, and other coding agents.
2. Why You Need It: 4 Agent Failure Modes
Each skill targets one of the four classic ways AI coding agents break down in real repositories:
| Failure Mode | Symptom | Solution Skill |
|---|---|---|
| 1. Builds the wrong thing | You thought your prompt was clear, yet the result misses the mark due to hidden assumptions. | /grill-me · /grill-with-docs — Grilling sessions: the agent interviews you on every design fork before writing code. |
| 2. Too verbose & inconsistent | Takes 20 sentences to explain one concept and re-invents project terms every session. | Ubiquitous language — /grill-with-docs builds a shared GLOSSARY.md and ADRs, shrinking future prompts and saving tokens. |
| 3. Code doesn't actually work | Right direction, broken output. The agent is flying blind without feedback. | Tight feedback loops — tdd (red → green → refactor) and diagnosing-bugs (disciplined debugging loop). |
| 4. Big ball of mud | Fast code generation breeds tangled complexity and architectural decay. | Daily design investment — /to-spec (architecture checks before coding) and /improve-codebase-architecture (periodic structural scans). |
3. 30-Second Setup
3.1 Install Skills for Your Agent
claude plugin install mattpocock-skills@claude-plugins-official3.2 Run Once Per Repository: /setup-matt-pocock-skills
Run /setup-matt-pocock-skills inside your agent and answer three quick questions:
- Which issue tracker you use (GitHub, GitLab, local files, or your own custom flow)
- Triage labels (used when
/triagecategorizes issues) - Where generated docs live (specs,
GLOSSARY.md, and ADRs)
Once configured per repo, all engineering skills know where to read and write.
4. Two Core Concepts
4.1 Who Calls Whom? (user-invoked vs model-invoked)
- User-invoked skills (16): Conductors triggered only when you type
/command(e.g.,/grill-with-docs,/implement,/retro). - Model-invoked skills (11): Reusable disciplines the agent pulls in automatically when relevant—or when called by a conductor (e.g.,
tdd,code-review,grilling). - Golden rule: User-invoked skills can call model-invoked skills, but never another user-invoked skill.
4.2 Ubiquitous Language (GLOSSARY.md)
Defining domain terms in one shared glossary keeps variable, function, and file names consistent while cutting reasoning tokens.
Real example: Instead of repeating "when a lesson inside a section inside a course gets placed on the filesystem, it breaks" every session, naming it "materialization cascade" turns an entire sentence into a single precise token-saving term.
5. The 7-Step Vibe Coding Recipe
Whenever you have a new feature idea, follow this exact seven-step sequence:
- 1Align Direction — Structured Grilling Interview
/grill-with-docsThe agent interrogates every design fork while automatically building GLOSSARY.md and Architecture Decision Records (ADRs).
- 2Consolidate Spec — Capture Decisions Without Extra Questions
/to-specDistills your grilling conversation into a clean specification document and publishes it to your configured tracker.
- 3Slice Into Tickets — Tracer-Bullet Plan With Dependencies
/to-ticketsBreaks the spec into vertical tracer-bullet tickets (data model → today view → completion/snooze) with explicit blocker links.
- 4Implement — Tests First, Auto-Review Before Commit
/implementBuilds ticket by ticket, running tdd (red → green → refactor) at planned checkpoints and triggering code-review before commits.
- 5Dual-Axis Parallel Review — Standards + Spec Fidelity
/code-reviewSpawns two independent subagents—one checks coding standards and Fowler code smells, the other verifies every spec requirement.
- 6Draft PR — Minimal Visuals, Proof & Blast Radius
/prGenerates a crisp PR description with before/after evidence, minimal visual summaries, and merge-risk/reversibility notes.
- 7Session Retrospective — Upgrade Your Agent Harness
/retroReviews the session and ranks concrete improvements to your automated checks, coding rules, and tooling by severity.
Step 1 Starter Prompt
/grill-with-docs I want to build an app for daily recurring todos where I only see today's tasks each morning.- Sample Agent Question: "Does 'done' just check it off? What happens to overdue tasks the next day? Should recurring tasks skip holidays?"
- Sample Answer: "Done just checks it off. Overdue tasks get a 'move to tomorrow' button. Skip recurring tasks on holidays."
If you remember only one habit from this entire guide: always start with /grill-with-docs, and ask /ask-matt whenever you aren't sure which skill fits next.
6. Three Everyday Workflows
Scenario A: New Feature"Build me a clean daily todo app"
“/setup-matt-pocock-skills → /grill-with-docs”
- Step 1 (Setup)
- /setup-matt-pocock-skills (local file tracker works great)
- Step 2 (Design)
- /grill-with-docs settles edge cases and builds GLOSSARY.md
- Step 3 (Build)
- /to-spec → /to-tickets → /implement (TDD per ticket)
- Step 4 (Ship)
- Wrap up with /code-review + /pr
Scenario B: Stubborn Bug"I fixed it twice and it's still broken"
“diagnosing-bugs → tdd”
- Activation
- Automatically invoked by the agent when debugging tough issues
- Loop
- Repro feedback loop → minimize → hypothesize → instrument → fix → regression test
- Benefit
- Stops random 'let me try changing this' thrashing
- Follow-up
- Lock in the root-cause fix with a failing tdd test first
Scenario C: Large Initiative"Too big for one session—keep architecture intact"
“/wayfinder · /implement-spec · /improve-codebase-architecture”
- Map Out
- /wayfinder turns multi-session work into a decision-ticket map
- Parallel Build
- /implement-spec executes ticket dependency graphs via parallel subagents
- Structural Audit
- Run /improve-codebase-architecture every few days for an HTML report
- Caveat
- The HTML report only spots mud—pick a candidate and grill it to fix
7. All 27 Skills at a Glance
The repository contains 16 user-invoked skills (11 engineering + 5 productivity) and 11 model-invoked skills (9 engineering + 2 productivity). Filter by category or search below.
- Start every feature: design interview + GLOSSARY & ADRsUser· User-Invoked · Engineering
Walks you through every architectural branch while writing GLOSSARY.md and decision records.
Skill:/grill-with-docsDomain:Engineering - Turn the conversation into a clean spec on your trackerUser· User-Invoked · Engineering
Synthesizes your grilling answers into a structured spec without redundant questions.
Skill:/to-specDomain:Engineering - Break a spec into tracer-bullet tickets with dependenciesUser· User-Invoked · Engineering
Slices specs into small vertical tickets and maps which ticket blocks which.
Skill:/to-ticketsDomain:Engineering - Implement tickets with TDD checkpoints and pre-commit reviewUser· User-Invoked · Engineering
Executes ticket plans using tdd cycles and invokes code-review automatically before committing.
Skill:/implementDomain:Engineering - Implement a full spec on an integration branch in parallelUser· User-Invoked · Engineering
Treats tickets as a dependency graph and runs parallel implementation subagents where safe.
Skill:/implement-specDomain:Engineering - Navigate multi-session initiatives via decision ticketsUser· User-Invoked · Engineering
Creates a map of decision tickets for work that exceeds a single context window.
Skill:/wayfinderDomain:Engineering - Scan repo for deep-module refactoring candidates (HTML report)User· User-Invoked · Engineering
Identifies shallow modules to deepen (small interface, rich behavior) in a visual HTML report.
Skill:/improve-codebase-architectureDomain:Engineering - Classify issues via state machine using your setup labelsUser· User-Invoked · Engineering
Applies structured issue categorization and labeling rules configured during setup.
Skill:/triageDomain:Engineering - Unsure which skill to run nextUser· User-Invoked · Engineering
Recommends the best skill and sequence based on your current task.
Skill:/ask-mattDomain:Engineering - One-time per-repo setup for tracker, labels, and doc pathsUser· User-Invoked · Engineering
Configures shared context required by the rest of the engineering suite.
Skill:/setup-matt-pocock-skillsDomain:Engineering - End-of-session harness retrospective ranked by severityUser· User-Invoked · Engineering
Suggests concrete upgrades to test scripts, coding rules, and tools after each session.
Skill:/retroDomain:Engineering - Relentless interview for non-code plans or designsUser· User-Invoked · Productivity
Stress-tests product plans, architecture ideas, or decisions before execution.
Skill:/grill-meDomain:Productivity - Compress a long thread into a handoff brief for a fresh sessionUser· User-Invoked · Productivity
Distills conversation state so another agent or new session can pick up seamlessly.
Skill:/handoffDomain:Productivity - Learn a new concept across multiple guided sessionsUser· User-Invoked · Productivity
Turns a directory into a structured multi-session learning workspace.
Skill:/teachDomain:Productivity - Convert open decisions into a human-friendly questionnaireUser· User-Invoked · Productivity
Packages unresolved choices into clear questions teammates can answer quickly.
Skill:/to-questionnaireDomain:Productivity - Re-explain confusing agent output using GLOSSARY termsUser· User-Invoked · Productivity
Fills in missing context immediately whenever an explanation stops making sense.
Skill:/wait-whatDomain:Productivity - Vertical-slice Red → Green → Refactor test disciplineAuto· Auto · Engineering
Enforces writing a failing test first, minimal passing code, and cleanup.
Skill:tddDomain:Engineering - Two-axis parallel review (standards + spec adherence)Auto· Auto · Engineering
Runs two isolated subagents to inspect Fowler smells/standards and spec completeness.
Skill:code-reviewDomain:Engineering - PR body with minimal visuals, proof & merge riskAuto· Auto · Engineering
Formats pull requests with before/after verification and reversibility assessment.
Skill:prDomain:Engineering - Disciplined debugging loop for hard bugs & regressionsAuto· Auto · Engineering
Guides reproduction, minimization, instrumentation, fix, and regression verification.
Skill:diagnosing-bugsDomain:Engineering - Refine domain models against GLOSSARY & edge casesAuto· Auto · Engineering
Stress-tests types and boundaries against your shared ubiquitous language.
Skill:domain-modelingDomain:Engineering - Shared vocabulary for deep-module architectureAuto· Auto · Engineering
Applies deep-module design seams for testability and AI navigability.
Skill:codebase-designDomain:Engineering - Throwaway HTML or UI prototype to answer design questionsAuto· Auto · Engineering
Lets you sanity-check state models or layouts before committing to production code.
Skill:prototypeDomain:Engineering - Primary-source investigation saved as cited MarkdownAuto· Auto · Engineering
Delegates API/doc research to background workflows with verified source citations.
Skill:researchDomain:Engineering - Interactive bash wizard for human-only infra/secret stepsAuto· Auto · Engineering
Walks humans through credentials, dashboards, or migrations agents cannot run.
Skill:wizardDomain:Engineering - Shared interviewing engine behind 5 grill/triage skillsAuto· Auto · Productivity
Core questioning discipline reused by grill-me, grill-with-docs, triage, and wayfinder.
Skill:grillingDomain:Productivity - Author concise CLAUDE.md, AGENTS.md, and SKILL.md filesAuto· Auto · Productivity
Keeps agent instructions crisp, imperative, and low-token instead of prose-heavy.
Skill:writing-for-agentsDomain:Productivity
8. Eight Practical Field Tips
1. Skipping Grilling Is the #1 MistakeGrilling · Glossary"Nobody knows what they actually want" (The Pragmatic Programmer). Even for a simple image resize feature, run /grill-with-docs first to lock max size, aspect ratio, and batch limits upfront.
2. Invest in GLOSSARY.mdGrilling · GlossaryRecording ADRs and domain terms keeps long sessions concise and forces consistent function and file naming across your codebase.
3. Feedback Loops Are Your Speed LimitFeedback · StructureStatic types, browser access, and automated tests form the three safety nets—tdd enforces the red-green-refactor cadence automatically.
4. Run /improve-codebase-architecture WeeklyFeedback · StructureAI writes technical debt as fast as it writes features. Generate the HTML scan report regularly, pick one hotspot, and tackle it via a grilling session.
5. Close Sessions With /retroDocs · CustomizingMissing test commands or clunky rules get surfaced and fixed immediately, creating compounding harness improvements every day.
6. Use /handoff and /wait-what LiberallyDocs · CustomizingCompress bloated sessions with /handoff before starting fresh, and trigger /wait-what whenever an agent explanation loses you.
7. Write Agent Docs With writing-for-agentsDocs · CustomizingReplace prose like 'Our project values testing...' in CLAUDE.md with crisp directives like 'Test: npx vitest run. Run before commit.' One sharp line beats a whole extra skill.
8. Hack Around—The Skills Are YoursDocs · CustomizingEvery skill is plain text. Ask your agent to open any SKILL.md and trim questions or rules that don't fit your team.
9. Stacking with Caveman & Ponytail
As covered in our Caveman & Ponytail Token Saver Guide, mattpocock/skills pairs cleanly with both tools as a 3-layer engineering stack:
| Layer | Tool | What It Controls |
|---|---|---|
| Process (what & when) | mattpocock/skills | Enforces grilling → spec → tickets → TDD → review order |
| Conversation (tokens per turn) | Caveman | Shortens replies + compresses logs/test output (npx @caveman-ai/cli@latest) |
| Code (output size) | Ponytail | Enforces the 7-step reuse ladder (AGENTS.md copy recommended) |
4-Step Integration Order
- Always-on base: Caveman CLI — compresses grilling Q&A and
/implementtest/log reads (up to 33% measured input reduction). - Implementation guard: Ponytail via
AGENTS.md— sits cleanly alongsidewriting-for-agentsrules without conflicting withtddorcode-review. - Split review timing — run
/code-reviewduring implementation (standards + spec adherence) and/ponytail-reviewonce right before opening a PR (bugs, security, dead-code cuts) to avoid double token spend. - Track results visually — compare
/ponytail bandinside Claude Code withcaveman statsin your terminal to separate process wins from token compression wins.
Quick-Copy Command Sheet
Core mattpocock/skills Workflow
Helpers & 3-Layer Combo Commands
10. Frequently Asked Questions
Q1. How is this different from GSD, BMAD, or Spec-Kit?
Q2. Isn't this too structured for vibe coding?
Q3. Which coding agent works best?
Q4. How do updates work?
Q5. Exactly how many skills are included?
Q6. I accidentally installed both the plugin and skills.sh—every skill appears twice!
Q7. Can I customize the skills for my team?
Validate Agent & Copilot JSON Settings Locally with Hafuture
Format and verify ~/.copilot/settings.json (extraKnownMarketplaces) or MCP configurations 100% locally in your browser with zero uploads.