PurposeAn Agent Skills collection for "real engineers" that tackles four common AI coding agent failure modes: the agent didn't do what you wanted (alignment via grilling), the agent is too verbose (shared language), the code doesn't work (test-driven development), and the codebase becomes a ball of mud (continuous architecture improvement). Split into engineering (daily code work) and productivity (general workflow) categories. Small, composable, model-agnostic — not an all-in-one framework but independent LEGO-like skills you pick.

Skill Count

Required CLI

ghgit

Domains

CodingOthers

Forms

Style GuideWorkflow

Installation

One command to install the entire Skillset.

Copy and run in your terminal to add mattpocock/skills to your Agent environment.

$npx skills add mattpocock/skills

SkillsWay.ai

View Repo ↗

mattpocock/skills

Skill Count

Required CLI

ghgit

Domains

CodingOthers

Forms

Style GuideWorkflow

Core Idea

Principles & Methodology

The author's design philosophy, what sets this apart from peer projects, and quick notes on the key workflows. Skill names mentioned in the text auto-link to their detail pages.

Core Philosophy

Unlike all-in-one frameworks like GSD, BMAD, and Spec-Kit, this skillset follows three principles:

Small and focused: each skill does one thing (/grilling is just the interview loop, /domain-modeling is just domain modeling, /codebase-design is just design vocabulary). Easy to understand and modify.
Composable: through /ask-matt's router and flow definitions (idea → ship main flow, on-ramps, vocabulary layers), skills assemble like LEGO. E.g., /grill-with-docs composes /grilling + /domain-modeling; /implement composes /tdd + /code-review.
Model-agnostic: works with Claude Code, Codex, or any agent — not tied to any specific model.

Workflow

When you present a development requirement, the skillset orchestrates behind the scenes:

Requirements alignment (Grilling): /grill-with-docs (with a codebase) or /grill-me (without) interviews you one question at a time until every decision tree branch is resolved. With a codebase, /domain-modeling builds the domain model concurrently.
Prototype validation: For questions needing a "let me try it" answer, /handoff forks into a /prototype session, then brings back conclusions.
Spec & Tickets: /to-spec synthesises discussion into a spec; /to-tickets breaks it into vertical-slice tickets with declared blocking edges.
Implement: Each ticket is executed via /implement, which drives /tdd loops (red→green→refactor), then finishes with a two-axis /code-review.
Architecture Health: Periodic /improve-codebase-architecture scans find "deepening opportunities" and drive refactoring.

On-ramps

/triage for external bugs/requests
/diagnosing-bugs for hard bugs
/wayfinder for huge foggy efforts

Vocabulary Layers

/domain-modeling: domain modeling, inline term refinement, ADR creation
/codebase-design: deep-module design vocabulary

Standalone Skills

/handoff, /research, /prototype, /teach, /writing-great-skills

Skill Relationships

Usage Relationships Between Skills

Skill → Skill usage relationships, with cross-layer references. Same color blocks indicate the same skill form.

Relationship Count

Standalone Skills

Most Referencing

ask-matt19 downstream skills
improve-codebase-architecture3 downstream skills

Most Referenced

grilling6 upstream skills
domain-modeling5 upstream skills

Note: Each dependency line reads as "the current Skill depends on" the Skill it points to.

Skill Composition

How skills in this set are triggered

Each skill is designed for a specific kind of caller — some only fire when you name them, others load automatically when the model judges them relevant. The split below summarises both modes at a glance.

User-Invoked13

These skills only fire when you call them by name. The agent will not load them on its own — they stay inert until invoked.

ask-matt grill-with-docs grill-me triage improve-codebase-architecture to-spec to-tickets implement wayfinder handoff teach writing-great-skills setup-matt-pocock-skills

Model-Invoked9

These skills are loaded automatically by the agent when it judges the context relevant. You usually don't need to call them yourself.

code-review codebase-design diagnosing-bugs domain-modeling grilling prototype research resolving-merge-conflicts tdd

Skill List

22 Skills · Filter by name or domain

ask-matt

A router skill for the entire skillset: when the user can't remember which skill to use or which flow fits their situation, they invoke this to get a recommendation. It describes the main "idea → ship" flow (grill-with-docs → to-spec/to-tickets → implement), plus on-ramps (triage, diagnosing-bugs, wayfinder), codebase health (improve-codebase-architecture), vocabulary layers (domain-modeling, codebase-design), and standalone skills (grill-me, prototype, research, teach). Following its map leads users to the correct workflow entry point.

Domain: Coding
Form: Workflow
Location: skills/engineering/ask-matt/SKILL.md

code-review

A two-axis code review skill: reviews a diff (from a fixed point to HEAD) along both Standards (coding standards + Fowler smell baseline) and Spec (faithful implementation of the originating issue/PRD). Both axes run as parallel sub-agents to avoid context pollution. The report aggregates findings without merging conclusions, ensuring "passes standards but implements the wrong thing" and "implements the right thing but breaks conventions" are both surfaced independently.

Domain: Coding
Form: Workflow
Location: skills/engineering/code-review/SKILL.md

codebase-design

A shared vocabulary skill for deep module design: provides a precise set of design terms (Module, Interface, Depth, Seam, Adapter, Leverage, Locality) guiding agents and developers to design "deep modules" — a lot of behaviour behind a small interface. Includes design principles (the deletion test, the interface is the test surface) and testability guidelines. A reference skill consumed by other skills (e.g., improve-codebase-architecture, tdd) and invoked directly by engineers.

Domain: Coding
Form: Style Guide
Location: skills/engineering/codebase-design/SKILL.md

diagnosing-bugs

A disciplined diagnosis loop for hard bugs and performance regressions. The core idea is to first build a tight feedback loop — no hypothesis phase without one. Six phases: build feedback loop → reproduce + minimise → generate 3-5 falsifiable hypotheses → instrument by prediction → fix + regression test → cleanup + post-mortem. If the codebase architecture can't lock down the bug, it recommends handing off to the improve-codebase-architecture skill.

Domain: Coding
Form: Workflow
Location: skills/engineering/diagnosing-bugs/SKILL.md

domain-modeling

An active discipline for building and sharpening a project's domain model: challenges terms in real time during conversation, clarifies fuzzy language, stress-tests scenarios, cross-validates code against the model, updates CONTEXT.md inline, and sparingly creates ADRs (only when the decision is hard to reverse, surprising without context, and the result of a real trade-off). Not a static glossary — a living process that continuously polishes the domain model.

Domain: Coding
Form: Workflow
Location: skills/engineering/domain-modeling/SKILL.md

grill-me

A "grilling" skill without documentation output: directly delegates to a `/grilling` session, relentlessly interviewing the user about a plan or design one question at a time until every decision tree branch is resolved. Unlike `/grill-with-docs`, it produces no persistent documentation — no CONTEXT.md updates, no ADR creation. Suitable for codebase-less or discussion-only scenarios (brainstorming, personal plan validation). User-invoked.

Domain: Others
Form: Workflow
Location: skills/productivity/grill-me/SKILL.md

grill-with-docs

A "grilling" skill with documentation output: relentlessly interviews the user about a plan or design (via the /grilling skill) while using /domain-modeling to continuously build the project's domain model — updating CONTEXT.md and creating ADRs inline. The key difference from /grill-me is that it produces persistent documentation artefacts. User-invoked, suitable for codebase-based projects.

Domain: Coding
Form: Workflow
Location: skills/engineering/grill-with-docs/SKILL.md

grilling

The universal "grilling" loop — the lowest-level reusable interview primitive in the skillset: questions the user one at a time about a plan, decision, or idea, walking each branch of the decision tree. Verifiable facts are looked up independently. Decisions belong to the user — wait for each answer before proceeding. No action is taken until the user confirms shared understanding. Used by `/grill-me` and `/grill-with-docs`, and automatically loaded by `/improve-codebase-architecture`, `/triage`, `/wayfinder`, and other skills needing structured discussion.

Domain: Others
Form: Workflow
Location: skills/productivity/grilling/SKILL.md

handoff

A cross-session handoff skill: compacts the current conversation's key context into a Markdown handoff document saved to the OS temp directory, for another agent to continue work in a new session. Includes a "suggested skills" section recommending which skills the next agent should load. Avoids duplicating content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs) — references them by path or URL instead. Redacts sensitive information like API keys, passwords, and PII.

Domain: Others
Form: Workflow
Location: skills/productivity/handoff/SKILL.md

implement

Executes development work based on a spec or set of tickets: reads the provided spec/tickets, uses /tdd at pre-agreed seams where possible, runs typechecking and single test files regularly, and finishes with a /code-review of the diff before committing to the current branch. This is the actual "write code" stage in the "idea → ship" flow, downstream of /to-spec and /to-tickets.

Domain: Coding
Form: Workflow
Location: skills/engineering/implement/SKILL.md

improve-codebase-architecture

Codebase architecture improvement skill: scans the codebase for "deepening opportunities" (turning shallow modules into deep ones), generates a visual HTML report (with Tailwind styling and Mermaid diagrams), then enters a /grilling loop once the user picks a candidate. Uses /codebase-design vocabulary for analysis, /domain-modeling to maintain the domain model, and /grilling to walk the decision tree. Running periodically prevents the codebase from becoming a "ball of mud."

Domain: Coding
Form: Workflow
Location: skills/engineering/improve-codebase-architecture/SKILL.md

prototype

A skill for building throwaway prototypes to answer design questions: identifies two branches — "does this logic/state model feel right?" answered via an interactive terminal app, and "what should this UI look like?" answered via a multi-variant UI switcher. Prototype code is marked throwaway from day one — no tests, no error handling, no persistence. Validated decisions flow into real code; the prototype itself is committed to a throwaway branch as a primary source.

Domain: Coding
Form: Workflow
Location: skills/engineering/prototype/SKILL.md

research

A background research skill: delegates investigation to a background agent so the main agent can continue working. The background agent queries only high-trust primary sources (official docs, source code, specs, first-party APIs), never secondary write-ups. Findings are saved as a Markdown file in the repo with each claim citing its source.

Domain: Coding
Form: Workflow
Location: skills/engineering/research/SKILL.md

resolving-merge-conflicts

A systematic git merge/rebase conflict resolution skill: follows a defined process — check current conflict state → find primary sources for each conflict (commit messages, PRs, issues) to understand original intent → resolve each hunk preserving both intents where possible, choosing by merge goal only when incompatible → run the project's automated checks → finish the merge/rebase. Core principles: never `--abort`, never invent new behaviour.

Domain: Coding
Form: Workflow
Location: skills/engineering/resolving-merge-conflicts/SKILL.md

setup-matt-pocock-skills

A one-time project setup skill: configures the Issue Tracker (GitHub/GitLab/Local Markdown/Other), Triage labels (5 canonical role label strings), and domain docs layout (single-context or multi-context). Prompt-driven, with recommended defaults at each step for one-click confirmation. After setup, other engineering skills (triage, to-spec, to-tickets, implement, etc.) can function correctly.

Domain: Coding
Form: Workflow
Location: skills/engineering/setup-matt-pocock-skills/SKILL.md

tdd

Test-Driven Development skill: defines the discipline and boundaries of the red-green-refactor loop. Specifies what a good test is (verifies behaviour through public interfaces, not implementation details), where tests go (at pre-agreed seams, confirmed each cycle), three anti-patterns (implementation-coupled, tautological, horizontal slicing), and loop rules (red before green, one vertical slice at a time, refactoring is not part of the loop). Not just a "write tests first" reminder — a comprehensive TDD quality reference.

Domain: Coding
Form: Style Guide
Location: skills/engineering/tdd/SKILL.md

teach

A multi-session teaching skill: uses the current directory as a teaching workspace with persistent, structured instruction based on the user's learning mission (MISSION.md). Produces MISSION (learning motivation), reference docs, lessons (self-contained HTML files), learning records (ADR-like knowledge captures), and RESOURCES (learning materials). Teaching philosophy emphasises "desirable difficulty" — retrieval practice, spaced learning, and interleaving to build storage strength (long-term retention) over fluency strength (in-the-moment recall).

Domain: Others
Form: Workflow
Location: skills/productivity/teach/SKILL.md

to-spec

Synthesises the current conversation into a spec (PRD) and publishes it to the Issue Tracker. No new interview — just distills what's already been discussed. Output includes Problem Statement, User Stories (extensive numbered list), Implementation Decisions, Testing Decisions, Out of Scope, and other standard sections. It identifies testing seams and gets user confirmation, then generates the spec using a template and applies the ready-for-agent label.

Domain: Coding
Form: Workflow
Location: skills/engineering/to-spec/SKILL.md

to-tickets

Breaks down a plan/spec/conversation into "tracer bullet" vertical-slice tickets: each ticket cuts a complete path through schema → API → UI → tests, is independently demoable/verifiable, fits a single agent context window, and declares its blocking edges. Supports publishing to either local files or a real issue tracker. Wide refactors use the "expand → migrate → contract" pattern instead of forcing vertical slicing. Shows the proposed breakdown to the user for confirmation before publishing.

Domain: Coding
Form: Workflow
Location: skills/engineering/to-tickets/SKILL.md

triage

An issue triage and processing skill: moves issues and external PRs through a state machine (needs-triage → needs-info → ready-for-agent/ready-for-human/wontfix) with classification, verification, optional grilling, and agent-ready brief writing. Follows a strict role system (2 category roles + 5 state roles), performing redundancy checks, priority recommendations, claim verification, grilling refinement, and ultimately producing agent-ready briefs or clear explanations for human-handoff.

Domain: Coding
Form: Workflow
Location: skills/engineering/triage/SKILL.md

wayfinder

A navigation skill for huge efforts: when the path from the current state to the destination is obscured by "fog" and cannot be seen in one session, it charts a "shared map" on the Issue Tracker — a set of decision tickets, resolved one at a time until the way is clear. Each ticket resolves a question (prototype, research, grilling, or task) and produces a decision, not a deliverable. The map is an index, not a store; decisions live in their own tickets. The "fog of war" records questions that can't yet be precisely stated.

Domain: Coding
Form: Workflow
Location: skills/engineering/wayfinder/SKILL.md

writing-great-skills

A writing reference skill — the methodology and principles for writing and editing Agent Skills. Defines predictability as the root virtue, detailing invocation type selection (user-invoked vs model-invoked), description writing, information hierarchy (in-skill step / in-skill reference / external reference), split strategies, pruning methods, leading words usage, and failure modes (premature completion, duplication, sediment, sprawl, no-op, negation). The skill itself extensively applies the principles it describes.

Domain: Coding
Form: Style Guide
Location: skills/productivity/writing-great-skills/SKILL.md

Showing 22 / 22