Matt Pocock Skills

What It Does

mattpocock/skills is a single-author framework of 22 promoted agent skills (41 SKILL.md files total across all buckets) written by Matt Pocock, the TypeScript educator behind Total TypeScript. The skills target developers doing real software engineering with Claude Code or Codex, and they are organized around a deliberate workflow: grill the idea into a spec, break the spec into tracer-bullet tickets, implement each ticket test-first, then code-review the diff. A router skill (ask-matt) maps the full flow, and two vocabulary skills (domain-modeling, codebase-design) supply shared terminology that the other skills invoke by name. The repo ships as both an editable install via npx skills add mattpocock/skills (which copies files into your project) and a managed Claude Code plugin that updates on release. At review time it carried 178,283 stars and 15,257 forks, making it the highest-starred single-author agent-skill repo GearScope has reviewed.

The Good

The skills form a coherent, routed workflow rather than a bag of prompts. Most skill packs GearScope reviews are independent files that do not reference each other. This repo is the opposite. ask-matt (engineering/ask-matt/SKILL.md, 78 lines) is an explicit router that maps the main flow (grill-with-docs to to-spec to to-tickets to implement to code-review), two on-ramps (triage for incoming bugs, wayfinder for multi-session builds), and standalone skills, and it spells out context-hygiene rules like keeping steps 1 through 3 in one context window. The CLAUDE.md file enforces a maintenance rule: any add, rename, or flow change must trigger an ask-matt re-check so the router never lies. This is the most self-aware routing discipline GearScope has seen in a skill framework.

The writing-great-skills skill is the best meta-skill on skill authoring GearScope has reviewed. At 83 lines plus a 60-line glossary, it defines a precise vocabulary (leading words, information hierarchy, progressive disclosure, branches, context pointers, granularity, no-ops, sediment, sprawl, premature completion, negation, negative space) and uses each term consistently across the other skills. The failure-mode catalog is concrete and diagnostic rather than abstract. For anyone writing their own skills, this single file is worth the install.

Both install paths work and are documented. npx skills@latest add mattpocock/skills cloned the repo, found all 41 skills, ran three security scanners (Gen, Socket, Snyk), and installed ask-matt into .claude/skills/ask-matt/ with a correct SKILL.md and agents/openai.yaml. claude plugin validate . --strict against the cloned repo passed cleanly. bash scripts/link-skills.sh symlinked every non-deprecated skill into both ~/.claude/skills and ~/.agents/skills with a guard against accidentally writing back into the repo. The ADR at .agents/adr/0002-ship-as-a-claude-code-plugin.md documents exactly why the repo ships a Claude Code plugin but defers a native Codex plugin (Codex plugin manifests accept only a single skills path string, so the bucketed layout cannot express a curated subset without restructuring). That level of documented reasoning about distribution is rare.

The structural validation is clean. A custom 22-check validation script confirmed that every promoted skill has a SKILL.md with valid name and description frontmatter, an agents/openai.yaml, a docs page under docs/, a README link, and an entry in the plugin.json skills array. No non-promoted skill leaked into the plugin manifest. The docs tree mirrors the promoted buckets exactly. The marketplace.json lists exactly one plugin. 20 of 22 checks passed. The two failures are documented below in The Bad.

The CHANGELOG is unusually detailed. At 116 lines for a v1.1.0 release, it cites 11 pull requests by number and explains not just what changed but why, including the reasoning behind renaming decision-mapping to wayfinder, splitting to-issues into to-tickets, and the facts-vs-decisions refinement to the grilling skill. This is the kind of release documentation most projects skip.

The Bad

The version numbers across the three sources of truth are out of sync. package.json declares version 1.1.0. .claude-plugin/plugin.json declares version 1.2.0. The CHANGELOG head is 1.1.0. The CLAUDE.md file explicitly states that the plugin.json version must track the package.json version because Claude uses the plugin version to decide when installed users see an update, and the ADR repeats this as an invariant. So the repo violates its own documented invariant. This means a user who installed the Claude Code plugin at v1.1.0 may or may not see the v1.2.0 plugin.json bump as an update, depending on whether Claude keys off the plugin manifest or the package release. This is the kind of self-consistency gap the writing-great-skills meta-skill warns about.

The marquee skills are very thin, which is a mixed signal. The three skills the README promotes as the most popular are grill-me (7 lines), grill-with-docs (7 lines), and grilling (12 lines). The README calls grilling "the single coolest technique in this repo" and spends 200 lines explaining the philosophy, but the actual grill-me SKILL.md is one sentence: "Run a /grilling session." This is deliberate (the README argues small skills compose better than large ones, and the shared grilling skill carries the actual loop), and it works because grilling does carry a real 12-line interview contract. But a developer who installs grill-me expecting the relentless interview the README describes will find a redirect, and whether the underlying model produces the documented behavior depends entirely on the model's priors about the word "grill." There is no runnable check that the grilling loop actually fires. Contrast this with code-review (89 lines) or wayfinder (128 lines), which carry enough procedural detail to constrain the agent regardless of model. The variance is large.

The skills assume a specific workflow and a configured issue tracker. Several engineering skills (triage, to-tickets, code-review, wayfinder) require a configured issue tracker, which setup-matt-pocock-skills provisions. The setup skill itself supports GitHub, GitLab, and local markdown files. But if you do not run setup first, the other skills fail with "run /setup-matt-pocock-skills" messages. The skills are also opinionated about process in a way that may not match every team: implement always drives tdd, code-review always runs two parallel sub-agents, wayfinder always produces decisions rather than deliverables. Developers who do not share these opinions will fight the skills.

Telemetry and update behavior of the managed plugin path is undocumented in the repo. The skills.sh installer surfaces three security scanners per skill, but the Claude Code plugin install path is a subscribe-and-update model where the plugin updates when the author ships a new version. The repo does not document whether the plugin path inherits the skills.sh security scanning, how update notifications surface, or what happens to local edits when the plugin updates. The ADR notes the plugin is read-only by design, which is clear, but the operational details for a subscriber are thin.

Smoke Test Results

Tested on macOS (host) with Node v24.13.1, Claude Code CLI available on PATH. The repo was shallow-cloned to /tmp/mattpocock-skills. No sandbox (sbx) was used because the skills are prompt contracts with no executable component to isolate. All commands below were run verbatim.

Structural validation

$ python3 /tmp/mp_validate.py
=== Structural validation: 20 PASS / 2 FAIL of 22 ===

PASS top-level README.md exists
PASS top-level LICENSE exists
PASS top-level CHANGELOG.md exists
PASS top-level package.json exists
PASS top-level CLAUDE.md exists
PASS marketplace.json exists
PASS plugin.json exists
PASS found >=20 SKILL.md files (count=41)
PASS plugin.json skills array matches promoted buckets
PASS non-promoted skills absent from plugin.json
PASS promoted SKILL.md have name+description frontmatter
PASS promoted skills have agents/openai.yaml
PASS docs/ tree mirrors promoted buckets
PASS README references each promoted skill
FAIL package.json version == plugin.json version (CLAUDE.md rule)
 (package.json=1.1.0 plugin.json=1.2.0)
PASS CHANGELOG has at least one version
PASS CHANGELOG head matches package.json version
PASS LICENSE is MIT
FAIL invoked /skill references resolve within repo (excluding built-ins)
 (broken=[('improve-codebase-architecture', 'tmp')])
PASS setup-matt-pocock-skills entrypoint exists
PASS ask-matt router skill exists
PASS marketplace.json lists exactly one plugin

Pass rate: 20 of 22. The version-drift failure is a real self-consistency violation documented above. The cross-reference failure is a false positive: the regex matched ` /tmp ` in a sentence about writing HTML reports to the OS temp directory, not a broken skill invocation.

Full structural log ->

Install via skills.sh (canonical badge run)

$ mkdir /tmp/mp-install-test && cd /tmp/mp-install-test
$ npx -y skills@latest add mattpocock/skills --skill ask-matt --agent claude-code -y
Source: https://github.com/mattpocock/skills.git
Found 41 skills
Selected 1 skill: ask-matt

Security Risk Assessments:
 Gen Socket Snyk
ask-matt Safe 0 alerts Low Risk

Installation Summary:
./.agents/skills/ask-matt
 copy -> Claude Code

Installation complete
Installed 1 skill:
 ask-matt (copied)
 -> ./.claude/skills/ask-matt

EXIT=0

Pass rate: 1 of 1. The skills.sh installer resolves the repo, runs three security scanners, and installs the selected skill to the correct Claude Code path. The --list variant enumerated all 41 skills with descriptions.

Full install log ->

Claude Code plugin validation

$ cd /tmp/mattpocock-skills && claude plugin validate . --strict
Validating marketplace manifest: .claude-plugin/marketplace.json
Validation passed

Pass rate: 1 of 1. The plugin manifest is valid against Claude Code's strict validator.

Dev-mode symlink linker

$ bash scripts/link-skills.sh
linked ask-matt -> /tmp/mattpocock-skills/skills/engineering/ask-matt
linked code-review -> /tmp/mattpocock-skills/skills/engineering/code-review
... (37 more)

Pass rate: 1 of 1. The linker symlinks every non-deprecated skill into ~/.claude/skills and ~/.agents/skills, with a guard against the destination being a symlink into the repo.

What the runs tell you

The distribution surface is solid. Both install paths (skills.sh editable copy, Claude Code managed plugin) work, the manifests validate, the security scanners fire, and the local dev linker is safe. The structural validation is clean except for the version-drift self-consistency violation. The functional behavior of the skills themselves (the grilling loop, the TDD red-green cycle, the parallel code-review sub-agents) could not be exercised because they are prompt contracts executed inside a coding agent against the user's own codebase. Functional verification is partial for this reason, which is expected for a framework-class skill pack.

Setup Walkthrough

1. Universal install (recommended for most users): npx skills@latest add mattpocock/skills. The CLI prompts you to pick skills and target agents. The README stresses selecting setup-matt-pocock-skills as part of the install.

1. Run /setup-matt-pocock-skills once inside your agent. It asks which issue tracker you use (GitHub, Linear, or local files), which triage labels you apply, and where to save docs. This provisions the configuration the other engineering skills assume.

1. Managed plugin install (for Claude Code users who want auto-updates): inside Claude Code, run /plugin marketplace add mattpocock/skills then /plugin install mattpocock-skills@mattpocock. The plugin ships exactly the 22 promoted skills as a read-only bundle.

1. Dev mode (for contributors or anyone who wants to edit the skills in place): clone the repo and run bash scripts/link-skills.sh. This symlinks every non-deprecated skill into ~/.claude/skills and ~/.agents/skills. A git pull keeps installed skills current.

1. To find the right skill, invoke /ask-matt and describe your situation. The router maps you onto the main flow or an on-ramp.

Post-install gotcha: if you install via the managed plugin path, your skills update when the author ships a new version. If you install via skills.sh, you own the copies and must run npx skills update manually. The two paths reflect different philosophies (subscribe vs. fork) and the README is explicit about the tradeoff.

Alternatives

1. obra/superpowers - A larger agentic framework (257K stars) that includes subagent-driven development, writing-plans, and other engineering skills. Broader scope, less single-author coherence. Prefer superpowers for a full development methodology; prefer mattpocock/skills for a tighter, more opinionated workflow you can adopt incrementally.

1. anthropics/skills - The official Anthropic skill pack. Vendor-authored, covers document tools, code tools, and art tools. Prefer anthropics/skills for vendor-aligned tooling; prefer mattpocock/skills for engineering process discipline that works with any model.

1. writing-great-skills (this repo, standalone) - For skill authors who only want the meta-skill on skill craft, installing just writing-great-skills via npx skills add mattpocock/skills --skill writing-great-skills gives you the vocabulary reference without the workflow commitment.