hafuture

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.

AIVibe CodingClaude CodeCodexCursorMatt PocockDeveloper ToolsTDD

Table of Contents


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 ModeSymptomSolution Skill
1. Builds the wrong thingYou 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 & inconsistentTakes 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 workRight 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 mudFast 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

bash
claude plugin install mattpocock-skills@claude-plugins-official
Auto-updates by default with zero manual maintenance.

3.2 Run Once Per Repository: /setup-matt-pocock-skills

Run /setup-matt-pocock-skills inside your agent and answer three quick questions:

  1. Which issue tracker you use (GitHub, GitLab, local files, or your own custom flow)
  2. Triage labels (used when /triage categorizes issues)
  3. 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:

  1. 1
    Align Direction — Structured Grilling Interview/grill-with-docs

    The agent interrogates every design fork while automatically building GLOSSARY.md and Architecture Decision Records (ADRs).

  2. 2
    Consolidate Spec — Capture Decisions Without Extra Questions/to-spec

    Distills your grilling conversation into a clean specification document and publishes it to your configured tracker.

  3. 3
    Slice Into Tickets — Tracer-Bullet Plan With Dependencies/to-tickets

    Breaks the spec into vertical tracer-bullet tickets (data model → today view → completion/snooze) with explicit blocker links.

  4. 4
    Implement — Tests First, Auto-Review Before Commit/implement

    Builds ticket by ticket, running tdd (red → green → refactor) at planned checkpoints and triggering code-review before commits.

  5. 5
    Dual-Axis Parallel Review — Standards + Spec Fidelity/code-review

    Spawns two independent subagents—one checks coding standards and Fowler code smells, the other verifies every spec requirement.

  6. 6
    Draft PR — Minimal Visuals, Proof & Blast Radius/pr

    Generates a crisp PR description with before/after evidence, minimal visual summaries, and merge-risk/reversibility notes.

  7. 7
    Session Retrospective — Upgrade Your Agent Harness/retro

    Reviews the session and ranks concrete improvements to your automated checks, coding rules, and tooling by severity.

Step 1 Starter Prompt

Step 1 Example (/grill-with-docs)
/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

Pick the Workflow That Fits Your Situation
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.

Complete 27-Skill Explorer27 skills
  • 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 · Glossary

Recording 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 · Structure

Static 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 · Structure

AI 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 · Customizing

Missing test commands or clunky rules get surfaced and fixed immediately, creating compounding harness improvements every day.

6. Use /handoff and /wait-what LiberallyDocs · Customizing

Compress 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 · Customizing

Replace 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 · Customizing

Every 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:

LayerToolWhat It Controls
Process (what & when)mattpocock/skillsEnforces grilling → spec → tickets → TDD → review order
Conversation (tokens per turn)CavemanShortens replies + compresses logs/test output (npx @caveman-ai/cli@latest)
Code (output size)PonytailEnforces the 7-step reuse ladder (AGENTS.md copy recommended)

4-Step Integration Order

  1. Always-on base: Caveman CLI — compresses grilling Q&A and /implement test/log reads (up to 33% measured input reduction).
  2. Implementation guard: Ponytail via AGENTS.md — sits cleanly alongside writing-for-agents rules without conflicting with tdd or code-review.
  3. Split review timing — run /code-review during implementation (standards + spec adherence) and /ponytail-review once right before opening a PR (bugs, security, dead-code cuts) to avoid double token spend.
  4. Track results visually — compare /ponytail band inside Claude Code with caveman stats in your terminal to separate process wins from token compression wins.

Quick-Copy Command Sheet

Click any command to copy to clipboard

Core mattpocock/skills Workflow

Helpers & 3-Layer Combo Commands


10. Frequently Asked Questions

Q1. How is this different from GSD, BMAD, or Spec-Kit?
All-in-one frameworks own the entire workflow, making it hard to debug or customize when one step misbehaves. mattpocock/skills consists of 27 small, composable Markdown skills—if grilling feels too long, you just edit the grilling skill file directly.
Q2. Isn't this too structured for vibe coding?
Not at all. The goal isn't slowing you down—it's catching agent mistakes immediately via static types, browser checks, and TDD while keeping architecture clean with /grill-with-docs and /improve-codebase-architecture.
Q3. Which coding agent works best?
It's model-agnostic. Plugin-based agents (Claude Code, Codex, Copilot) are easiest because updates happen automatically. Cursor, OpenCode, Windsurf, and others install cleanly via npx skills@latest add mattpocock/skills -a <agent>.
Q4. How do updates work?
Claude Code updates automatically, Codex updates on launch, Copilot CLI updates when autoUpdate: true is enabled, and VS Code refreshes daily. Gemini CLI updates by re-running the install command, and npx skills updates via npx skills@latest update (re-run add for brand-new skills).
Q5. Exactly how many skills are included?
27 total: 16 user-invoked skills (11 engineering + 5 productivity) and 11 model-invoked skills (9 engineering + 2 productivity), all published as readable SKILL.md files under skills/engineering/ and skills/productivity/.
Q6. I accidentally installed both the plugin and skills.sh—every skill appears twice!
Remove one per agent. To keep the auto-updating plugin, run npx skills remove mattpocock/skills. To keep editable local copies, remove mattpocock-skills from /plugin (or your agent's plugin menu), then verify /ask-matt appears only once in a fresh session.
Q7. Can I customize the skills for my team?
Yes—'Hack around with them. Make them your own.' Ask your agent to show any skill file and edit freely. Just make sure to include setup-matt-pocock-skills if installing manually, since the engineering skills depend on its saved tracker and doc paths.

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.

Open JSON Formatter