Matt Pocock Skills Explained: Engineering Best Practices for AI Programming Assistants

II. Quick Installation (30 seconds)

# Option 1: Use the official installer
npx skills@latest add mattpocock/skills

# Option 2: Manual clone
git clone https://github.com/mattpocock/skills.git ~/.claude/skills

After installation, select the desired skills. Be sure to choose /setup-matt-pocock-skills for initial configuration.

III. Core Skills Detailed Explanation

3.1 /grill-me — Requirements Clarification Interview

Purpose: Before starting to code, let the AI conduct a "stress interview" with you, clarifying requirements branch by branch.

Workflow:

User: I want to implement user login functionality.
AI: How will users log in? Email? Phone? Third-party OAuth?
User: Both email and phone should be supported.
AI: Does phone login require a verification code? Which provider?
... (Drilling deeper until all branches are resolved)

Applicable Scenarios:

• Requirements grooming before developing new features
• Technical solution design review
• Any moment when "I haven't figured it out yet"

3.2 /grill-with-docs — Requirements Clarification with Documentation

Enhanced version of /grill-me, with additional features:

1. Auto-maintenance of CONTEXT.md — project domain glossary
2. Auto-generation of ADRs — Architecture Decision Records
3. Detection of terminology conflicts — When you say "account," AI will ask: "Do you mean Customer or User?"

Document Structure:

project/
├── CONTEXT.md           # Domain vocabulary
├── docs/
│   └── adr/             # Architecture Decision Records
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

Example:

• Before: "There's an issue in the course video manager. When a chapter's video becomes 'real,' it causes an error."
• After: "The materialization cascade has a problem."

This conciseness compounds across sessions, delivering ever-increasing benefits.

3.3 /tdd — Test-Driven Development

Core Principle: Tests verify behavior, not implementation details.

Correct Approach (Vertical Slicing):

RED→GREEN: test1→impl1
RED→GREEN: test2→impl2
RED→GREEN: test3→impl3

Wrong Approach (Horizontal Slicing):

RED:   test1, test2, test3, test4, test5
GREEN: impl1, impl2, impl3, impl4, impl5

Key Rules:

• Write only one test at a time
• Write only the minimum code to pass the current test
• Do not anticipate future tests
• Focus tests on observable behavior

Good Test vs Bad Test:

3.4 /diagnose — Systematic Debugging

Six-Phase Diagnostic Loop:

Phase 1: Build a feedback loop ← Most critical!
Phase 2: Reproduce the bug
Phase 3: Generate 3–5 falsifiable hypotheses
Phase 4: Verify each hypothesis
Phase 5: Fix + regression test
Phase 6: Clean up + postmortem

10 Ways to Build a Feedback Loop (in priority order):

1. Failing tests — unit/integration/E2E tests
2. Curl/HTTP scripts — targeting APIs
3. CLI invocation + snapshot comparison
4. Headless browser scripts — Playwright/Puppeteer
5. Replay captured requests
6. One-shot test skeleton
7. Property/fuzz testing
8. Binary search skeleton
9. Diff comparison
10. Human-in-the-loop scripts — last resort

Key Insight:

Once you build the right feedback loop, the bug is 90% solved.

3.5 /to-prd — Product Requirements Document Generation

Process:

1. Explore the codebase to understand the current state
2. Outline the modules to be built/modified
3. Confirm testing strategy
4. Publish the PRD to an Issue Tracker

PRD Template:

## Problem Statement
Description of the problem from the user's perspective

## Solution
Solution from the user's perspective

## User Stories
1. As a <actor>, I want <feature>, so that <benefit>

## Implementation Decisions
- Module design decisions
- Interface changes
- Technical clarifications

## Testing Decisions
- Testing strategy
- Scope of testing

## Out of Scope
Items not included in this scope

3.6 /improve-codebase-architecture — Architecture Improvement

Goal: Discover deepening opportunities — transform shallow modules into deep modules.

Core Vocabulary:

Depth Judgment Criteria:

• Delete Test: Imagine deleting the module; does the complexity disappear or shift to N callers?
• One adapter = hypothetical seam; Two adapters = real seam

Workflow:

1. Explore the codebase to find friction points
2. Present candidate improvement areas
3. Discuss design options one by one
4. Update CONTEXT.md and ADRs

3.7 /setup-matt-pocock-skills — Initialization Configuration

Must be run first to configure three key settings:

1. Issue Tracker — GitHub / GitLab / local Markdown
2. Triage Labels — mapping of five standard labels:
   • needs-triage — needs evaluation
   • needs-info — waiting for more information
   • ready-for-agent — can be executed AFK (Away From Keyboard)
   • ready-for-human — requires human implementation
   • wontfix — will not be addressed
3. Domain Docs — single-context or multi-context layout

IV. Architecture Diagrams

4.1 Skill System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                  Matt Pocock Skills Architecture                │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐          │
│  │  Productivity │    │ Engineering │    │    Misc     │          │
│  ├─────────────┤    ├─────────────┤    ├─────────────┤          │
│  │ grill-me     │    │ tdd         │    │ git-guardrails│         │
│  │ grill-with-docs│   │ diagnose    │    │ setup-pre-commit│       │
│  │ caveman      │    │ to-prd      │    │ migrate-to-shoehorn│    │
│  │ handoff      │    │ to-issues   │    │ scaffold-exercises│     │
│  │ write-a-skill│    │ triage      │    └─────────────┘          │
│  └─────────────┘    │ improve-*   │                              │
│                      │ zoom-out    │                              │
│                      │ prototype   │                              │
│                      │ setup-*     │                              │
│                      └─────────────┘                              │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                  Supporting Documentation System              │ │
│  ├─────────────────────────────────────────────────────────────┤ │
│  │  CONTEXT.md ─── Domain Glossary (Shared Language)            │ │
│  │  docs/adr/ ─── Architecture Decision Records                │ │
│  │  docs/agents/ ── Skill configuration files                  │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘

4.2 Workflow Diagram

User intention
    │
    ▼
┌──────────────┐
│ /grill-me    │ ←─────── Requirements clarification
│ /grill-with-docs│        Update CONTEXT.md
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ /to-prd      │ ←─────── Generate PRD
│ /to-issues   │          Break into Issues
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ /tdd         │ ←─────── Red-Green-Refactor cycle
└──────┬───────┘
       │
       ├─── Bug? ──→ /diagnose ──→ /tdd
       │
       ▼
┌──────────────┐
│ /improve-*   │ ←─────── Periodic architecture improvement
└──────────────┘

4.3 Deep Module vs Shallow Module

Deep Module (Ideal State)
┌─────────────────────────────────────┐
│           Simple Interface          │
│    ┌───────────────────────┐        │
│    │    Complex Implementation      │
│    │  ┌─────────────────┐  │        │
│    │  │   Business Logic  │        │
│    │  │   Data Processing  │        │
│    │  │   Edge Cases        │        │
│    │  └─────────────────┘  │        │
│    └───────────────────────┘        │
└─────────────────────────────────────┘
High leverage: simple for callers, concentrated for maintainers

Shallow Module (Needs Improvement)
┌─────────────────────────────────────┐
│           Complex Interface         │
│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐   │
│  │Config1│ │Config2│ │Config3│ │Config4│
│  └──┬──┘ └──┬──┘ └──┬──┘ └──┬──┘   │
│     │       │       │       │       │
│  ┌──▼──┐ ┌──▼──┐ ┌──▼──┐ ┌──▼──┐   │
│  │Impl1│ │Impl2│ │Impl3│ │Impl4│   │
│  └─────┘ └─────┘ └─────┘ └─────┘   │
└─────────────────────────────────────┘
Low leverage: complex for callers, scattered for maintainers

V. Best Practices

5.1 Pre-Development Checklist

[ ] Run /grill-with-docs to clarify requirements
[ ] Confirm term definitions in CONTEXT.md
[ ] Check relevant ADRs to avoid duplicate decisions
[ ] Use /tdd to start development
[ ] After completion, run /improve-codebase-architecture

5.2 Documentation Maintenance Principles

CONTEXT.md should contain:

• Terms understood by domain experts
• Definition of business concepts
• Boundaries between modules

CONTEXT.md should NOT contain:

• Implementation details
• Database fields
• API endpoints

Conditions for creating ADRs (all three must be met simultaneously):

1. Difficult to reverse — high cost of change
2. Confusing without context
3. Represents a real trade-off

5.3 Debugging Mindset

Don't ask: "Why doesn't the code work?"
Ask:      "Is the feedback loop fast enough? Is the signal clear enough?"

VI. Comparison with Other Tools

VII. Summary

Core Philosophy of Matt Pocock Skills:

Software engineering fundamentals matter more than ever.
These skills condense decades of engineering experience into repeatable practices.

Recommended Order of Use:

1. /setup-matt-pocock-skills — Initialization
2. /grill-with-docs — Before each new feature
3. /tdd — During development
4. /diagnose — When encountering bugs
5. /improve-codebase-architecture — Periodic execution

References

• GitHub Repository
• Author Newsletter
• skills.sh Installer
• The Pragmatic Programmer — David Thomas & Andrew Hunt
• Domain-Driven Design — Eric Evans
• A Philosophy of Software Design — John Ousterhout