Skills For Real Engineers

mattpocock/skills at 4ae2317

39 skills · 118 files shown of 183 · license: MIT · imported 2026-11-10

About

Matt Pocock’s own set of agent skills for daily software engineering and for general workflow, which the README describes as made for “real engineering - not vibe coding”. The skills are small and meant to be combined, rather than a framework that owns the whole process, and they rest on established engineering ideas: interviews (“grilling”) to align with the agent before work starts, a shared domain glossary, red-green TDD, and deep modules. What sets the repo apart is a strict split between skills only the user can start and skills the agent may reach for on its own, and a main flow that runs from an idea through a spec and tickets to reviewed code.

How the repo is organized

Layout. Every skill is a folder under skills/<bucket>/<skill>/ holding a SKILL.md, its reference files, and an agents/openai.yaml. There are five buckets, each with a README.md that lists its skills:

engineering/ (20 skills) and productivity/ (7 skills) are the promoted buckets. Only these ship in the plugin, appear in the top-level README, and get a docs page under docs/.
in-progress/ (7 skills) is a public beta. These skills are left out of the plugin and are installed one at a time with npx skills@latest add mattpocock/skills --skill=<name>.
misc/ (4 skills) is kept but frozen: issues against these skills are closed.
deprecated/ is empty and holds only its README.

Who can start a skill. Each skill is either user-invoked or model-invoked. A user-invoked skill sets disable-model-invocation: true in its SKILL.md frontmatter for Claude Code and policy.allow_implicit_invocation: false in agents/openai.yaml for Codex, so only a person typing its name can start it. User-invoked skills orchestrate, and they reach model-invoked skills with an explicit instruction such as Call the Skill tool with "grilling".Some are only that line: grill-me calls grilling, and grill-with-docs calls grilling and domain-modeling. Shared material lives inside the skill that owns it (grilling, domain-modeling, codebase-design, tdd, writing-for-agents), not in a shared folder, so the repo has no shared scripts. software-factory is the one skill without an agents/openai.yaml.

How the skills fit together. ask-matt is a router over the whole set. The main flow runs grill-with-docs → to-spec → to-tickets → implement (one ticket at a time) or implement-spec (all tickets through subagents), which build with tdd and finish with code-review, and then retro. triage, diagnosing-bugs, and wayfinder are entry points that feed into that flow, and the rest are standalone.

Installing. The README offers one route per agent and says to pick only one, because two routes give every skill twice. Claude Code installs the plugin with claude plugin install mattpocock-skills@claude-plugins-official. Codex and GitHub Copilot install from the repo’s own marketplace in .claude-plugin/. Gemini CLI installs the two promoted buckets by path, and every other agent uses skills.sh (npx skills@latest add mattpocock/skills). After installing, the user runs /setup-matt-pocock-skills once per project. It writes docs/agents/issue-tracker.md, docs/agents/domain.md, and (when triage is installed) docs/agents/triage-labels.md, plus an ## Agent skills block in CLAUDE.md or AGENTS.md, and the engineering skills read those files to find the issue tracker and the label names.

What runs automatically. The plugin registers no hooks, commands, or agents, so nothing runs without the user or the agent choosing a skill. The only hook in the repo belongs to misc/git-guardrails-claude-code, which the user installs into their own Claude Code settings. The GitHub Actions workflows only maintain this repo’s issues and releases.

Skills

Engineering

Skill	Summary	Files
ask-matt	A router over the repo’s skills: the agent places the user’s situation on the main flow from idea to shipped code, on an entry point such as triage or wayfinder, or on a standalone skill, reading a skill’s SKILL.md before it recommends that skill. User-invoked, for when you do not know which skill fits.	3
code-review	Reviews the diff since a fixed point on two separate axes, Standards (the repo’s documented standards plus a baseline of Fowler code smells) and Spec (the originating issue or spec), using two parallel subagents whose reports it shows side by side without reranking. Model-invoked for reviewing a branch, a PR, or work in progress, and called at the end of implement and implement-spec.	2
codebase-design	A reference vocabulary for designing deep modules (module, interface, depth, seam, adapter, leverage, locality) with principles such as the deletion test, which the agent uses whenever code is designed or restructured. Model-invoked; tdd, improve-codebase-architecture, and setup-ts-deep-modules call it for the vocabulary.	4
diagnosing-bugs	A phased method for hard bugs and performance regressions: the agent must first build a fast, deterministic command that fails on this exact bug, then shrink the repro, rank testable hypotheses, instrument, fix with a regression test, and clean up. Model-invoked when the user reports something broken, failing, or slow.	3
domain-modeling	Makes the agent actively build the project’s domain language: it challenges terms against GLOSSARY.md, sharpens vague words, tests relationships with edge-case scenarios, updates the glossary as terms are settled, and offers an ADR only for decisions that are hard to reverse, surprising, and a real trade-off. Model-invoked; grill-with-docs, triage, wayfinder, and improve-codebase-architecture call it.	4
grill-with-docs	A one-line skill that calls grilling and domain-modeling, so the interview also writes GLOSSARY.md entries and ADRs as decisions are made. User-invoked; ask-matt makes it the first step of the main flow whenever there is a working directory.	2
implement	Builds the work described in a spec or ticket on the current branch, using tdd at agreed seams, running typechecks and tests, then calling code-review and committing. User-invoked, usually once per ticket with a fresh context each time.	2
implement-spec	Implements a whole spec on one integration branch by treating its tickets as a task graph: fresh implementer subagents take each ready ticket in their own worktrees, merger subagents merge the results, and one code-review runs at the end. User-invoked, when you want one run to build every ticket of a spec.	2
improve-codebase-architecture	Surveys a codebase for deepening opportunities, looking first at recently changed areas, writes them to a visual HTML report with before and after diagrams in the OS temp folder, then grills the user through the candidate they pick. User-invoked, as maintenance the README suggests running every few days.	3
pr	Gives the agent a template for pull request bodies: a Summary that uses the smallest visual that shows the change, before and after Evidence, and a Merge Danger section that says whether the change is a one-way or two-way door and how wide its effects could reach. Model-invoked whenever the agent writes a PR body.	3
prototype	Has the agent build throwaway code that answers one design question: a single HTML file that pushes a state model through hard cases (LOGIC.md), or several switchable UI variants on one route (UI.md). The prototype is then kept on a throwaway branch and only the decision goes into the real code. Model-invoked when a state model or a UI is hard to settle on paper.	4
research	Starts a background agent with a fresh context that investigates a question against primary sources and writes a cited Markdown file where the repo keeps such notes. Model-invoked when the user wants a topic researched or reading delegated; wayfinder uses it for research tickets.	2
retro	Reviews a coding session and suggests changes to the agent’s environment rather than the code (navigation pointers, automated checks, coding standards, AGENTS.md, tool costs, access to information), most severe first. User-invoked after a session; it loads writing-for-agents first.	2
setup-matt-pocock-skills	Configures a project for the engineering skills: the agent explores the repo, asks about the issue tracker, triage labels, and domain doc layout, then writes `docs/agents/*.md` from its seed templates and an `## Agent skills` block in CLAUDE.md or AGENTS.md. User-invoked, once per project before the other engineering skills.	7
tdd	A reference for test-driven development in vertical red-green slices: tests go only at seams agreed with the user and check behaviour through public interfaces, avoiding tests tied to the implementation, tautological tests, and writing all tests before any code. Model-invoked when building or fixing test-first, and called by implement and implement-spec.	4
to-spec	Turns the current conversation into a spec without interviewing the user again: it confirms the test seams, fills a template (problem, solution, user stories, implementation and testing decisions, out of scope), and publishes it to the issue tracker with the ready-for-agent label. User-invoked after a grilling session or a wayfinder map.	2
to-tickets	Breaks a plan, spec, or conversation into tracer-bullet tickets, each a thin vertical slice with its blocking tickets named, and uses expand-contract batches for wide refactors. After the user approves, it publishes them as numbered files under `.scratch/` or as issues with native blocking links. User-invoked, usually right after to-spec.	2
triage	Moves incoming issues (and external PRs, if the tracker config allows them) through category and state labels: the agent checks for an existing implementation and past rejections, verifies the claim, grills if needed, and posts an agent brief or needs-info notes. User-invoked by a maintainer working through requests they did not write.	4
wayfinder	Plans an effort too large for one session as a map issue on the tracker with child decision tickets (research, prototype, grilling, or task). It resolves one ticket per session and turns the vague areas into new tickets as they become clear. User-invoked for large, unclear efforts; when the map is done it hands off to to-spec instead of building.	2
wizard	Has the agent write an interactive Bash wizard, built on template.sh, that walks a person through steps only they can do, such as copying keys from a third-party dashboard into `.env` and GitHub secrets. Model-invoked when the agent reaches a step that needs a human.	3

In progress

Skill	Summary	Files
chief-of-staff	Makes the session a long-running coordinator for one goal: all work goes to background subagents, memory is kept in a wiki of dated Markdown pages, and it runs retro and the spec-to-implementation procedures by reading those skills’ SKILL.md files. User-invoked; beta.	2
claude-handoff	Writes a handoff summary of the conversation to the OS temp folder and starts a Claude Code background agent with it through `claude --bg --name`. User-invoked; beta and specific to Claude Code.	2
loop-me	Runs a grilling session whose only output is specs for workflows the user wants to automate, kept in `workflows/*.md`, using a small vocabulary (loop, trigger, checkpoint, brief) and notes on the user’s tools in NOTES.md. User-invoked; beta.	2
setup-ts-deep-modules	Installs dependency-cruiser in a TypeScript repo with rules that let outside code reach a package only through its root entry-point files. It then scaffolds an example package, proves that a deep import fails the check, and documents the convention. User-invoked; beta.	3
software-factory	A glossary for designing a software factory, meaning a system of agents that turns tickets, PRs, and schedules into merged code: tasks, triggers, runs, runners, and the service slots (ticket tracker, git host, orchestrator, observability platform), with surveys of products for each slot. User-invoked alongside a grilling session; beta.	6
writing-beats	Turns a file of raw material into an article one beat at a time, offering two or three candidate beats at each step and tracking which concepts the reader already has before a beat may use them. User-invoked; beta.	2
writing-fragments	Runs a grilling session about something the user wants to write and appends every usable fragment to one Markdown file, separated by horizontal rules, with no structure imposed. User-invoked; beta, the exploring stage before writing-beats or writing-shape.	2
writing-shape	Shapes a file of raw material into a separate article paragraph by paragraph, starting from two or three candidate openings and arguing with the user about the format of each block. User-invoked; beta.	2

Misc

Skill	Summary	Files
git-guardrails-claude-code	Installs a Claude Code PreToolUse hook that blocks dangerous git commands such as push, `reset --hard`, and `clean -f`, for one project or for all projects. Model-invoked; in the frozen misc bucket.	3
migrate-to-shoehorn	Migrates TypeScript test files from `as` type assertions to `fromPartial`, `fromAny`, and `fromExact` from @total-typescript/shoehorn. Model-invoked; in the frozen misc bucket.	2
scaffold-exercises	Creates course exercise folders (sections, then exercises with problem, solution, or explainer subfolders and stub readmes) that pass `pnpm ai-hero-cli internal lint`, then commits them. Model-invoked; it depends on the ai-hero-cli linter and sits in the frozen misc bucket.	2
setup-pre-commit	Sets up a Husky pre-commit hook that runs lint-staged with Prettier, then the typecheck and test scripts, and commits the result as a test of the hook. Model-invoked; in the frozen misc bucket.	2

Productivity

Skill	Summary	Files
grill-me	A one-line skill that calls grilling, for an interview that saves nothing, such as sharpening a plan or a piece of writing with no repo under it. User-invoked.	2
grilling	Interviews the user about a plan in rounds: each round asks every question whose prerequisites are settled, numbered and with a recommended answer, while the agent looks up facts itself through subagents and leaves the decisions to the user. Model-invoked; it is the shared interview behind grill-me, grill-with-docs, triage, wayfinder, and improve-codebase-architecture.	2
handoff	Writes a handoff document of the current conversation to the OS temp folder so that a fresh agent can continue, listing suggested skills and pointing to existing artifacts instead of copying them. User-invoked, mainly when work moves to another harness, folder, or person.	2
teach	Teaches the user a topic over many sessions, using the current folder as a workspace that holds a mission, resources, learning records, short HTML lessons, reference sheets, and shared lesson components. User-invoked.	6
to-questionnaire	Asks the user only who a questionnaire is for and what they need back, then writes a Markdown questionnaire aimed at the gap in their knowledge for that person to fill in. User-invoked when a decision depends on someone else’s knowledge.	2
wait-what	A one-paragraph prompt that makes the agent explain its last message again with more context, in ASD-STE100 Simplified Technical English and the project’s GLOSSARY.md terms. User-invoked whenever a message is hard to follow.	2
writing-for-agents	A reference for writing documents that agents read (skills, AGENTS.md, CLAUDE.md, and docs reached by a pointer): context pointers, the information hierarchy, completion criteria, leading words, and pruning, with SKILL-MECHANICS.md for details that apply only to skills. Model-invoked when creating or editing skills or agent instruction files; retro loads it.	3

Repository files

File	What it does
README.md
LICENSE
.claude-plugin/plugin.json	The plugin manifest for “mattpocock-skills”, version 1.3.2, with author, homepage, repository, MIT license, and keywords.
.claude-plugin/marketplace.json	A plugin marketplace named “mattpocock”, owned by Matt Pocock, that lists one plugin, “mattpocock-skills”, with `source` “./” (the repo root), a description, the category “engineering”, and keywords.
skills/engineering/README.md
skills/productivity/README.md
skills/in-progress/README.md
skills/misc/README.md
skills/deprecated/README.md

Automated checks

The import scripts ran these checks on every shown file. They look for patterns that deserve a close read, such as hidden characters, wording that tries to override an agent, or commands that download and run code. A flag does not mean a file is malicious, and no flag does not mean it is safe.

Check	What it looks for	Flagged files
Touches credentials	Mentions SSH keys, cloud credentials, keychains, or token variables.	skills/in-progress/software-factory/TICKET-TRACKERS.md, skills/in-progress/software-factory/GIT-HOSTS.md (2)
Prompt-injection wording	Wording often used to override an agent’s instructions or keep the user uninformed.	skills/productivity/grilling/SKILL.md
Changes agent or shell settings	Mentions files that change how an agent or shell behaves, such as agent settings, CLAUDE.md, AGENTS.md, shell profiles, or scheduled jobs.	skills/engineering/ask-matt/SKILL.md, skills/engineering/retro/SKILL.md (2), skills/engineering/setup-matt-pocock-skills/SKILL.md (5), skills/in-progress/setup-ts-deep-modules/SKILL.md (2), skills/misc/git-guardrails-claude-code/SKILL.md (7), skills/productivity/writing-for-agents/SKILL.md (4), README.md, skills/productivity/README.md
Hidden HTML comment	A comment that rendered Markdown hides. The page shows it as text.	skills/engineering/wayfinder/SKILL.md (3)
Destructive command	Deletes broadly, force-pushes, or loosens permissions.	skills/misc/git-guardrails-claude-code/SKILL.md

These files were skipped and never read, because they are symlinks, submodules, or have unsafe names:

AGENTS.md: symlink

Other files in the repo

These files are listed but not shown. Each name links to the file on GitHub.

Guidance for agents that maintain the repo

Rules for agents editing this repo, not for people using the skills. CLAUDE.md holds them and AGENTS.md is a symlink to it: the bucket layout, what must be listed in the README and plugin.json, and no em-dashes in prose. The .agents/ folder holds the canonical install wording, the user-invoked versus model-invoked convention, the template for docs pages, and two ADRs on setup pointers and on shipping as a Claude Code plugin.

6 files

Documentation pages

One human-facing page per promoted skill, published at aihero.dev/skills-<name>, following the template in .agents/writing-docs.md (What it does, When to reach for it, Common questions, It’s working if, Where it fits). docs/engineering/resolving-merge-conflicts.md is an archived page for a skill removed in v1.3.0.

28 files

The repo’s own configuration for its skills

Files the repo’s skills read when they run on this repo itself. GLOSSARY.md is its domain glossary (issue tracker, issue, decision ticket, triage role), and docs/agents/triage-labels.md maps the five triage roles to its GitHub labels in the shape setup-matt-pocock-skills writes.

2 files

Contribution policy and rejected requests

The rules for filing issues. CONTRIBUTING.md says where each kind of request goes, SCOPE.md sets the bar an idea must clear, and each file in .out-of-scope/ records one rejected request and the reason, in the format the triage skill’s OUT-OF-SCOPE.md describes.

11 files

GitHub issue forms and workflows

Issue forms for bugs and ideas, and three GitHub Actions workflows. One adds needs-triage to every new issue, one closes needs-info issues after 14 days without a reply, and one runs Changesets on each push to main to open the “chore: version skills” release PR.

6 files

Versioning and release

The npm package exists only to run Changesets. Each change adds a file to .changeset/, npm run version turns those files into CHANGELOG.md entries and a new version number, and scripts/sync-plugin-version.mjs copies that number into plugin.json so that plugin users receive the release.

9 files

Local development scripts and settings

Tools for the maintainer. scripts/link-skills.sh symlinks every skill outside misc/ and deprecated/ into ~/.claude/skills and ~/.agents/skills, and its header says it is not a supported installer. scripts/list-skills.sh prints every SKILL.md path, and .gitignore ignores node_modules and .claude.

3 files