Skills For Real Engineers

A collection of AI agent skills for real engineering, used daily by Matt Pocock. These skills are small, easy to adapt, composable, work with any model, and are based on decades of engineering experience.

Use Cases

• Developers using Claude Code, Codex, or other coding AI agents
• Those who want to solve common failure modes: agents not following intentions, being too verbose, producing broken code, or creating tangled codebases quickly
• Anyone needing repeatable, composable engineering practices to improve AI-assisted development

Core Capabilities

Engineering Skills (User-invoked)

• /ask-matt — Ask which skill or flow fits your situation.
• /grill-with-docs — Grilling session that also builds your project's domain model, sharpening terminology and updating CONTEXT.md and ADRs inline.
• /triage — Move issues through a state machine of triage roles.
• /improve-codebase-architecture — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
• /setup-matt-pocock-skills — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo.
• /to-spec — Turn the current conversation into a spec and publish it to the issue tracker.
• /to-tickets — Break any plan, spec, or conversation into a set of tracer-bullet tickets.
• /implement — Build the work described by a spec or set of tickets, driving /tdd at pre-agreed seams and closing out with /code-review before committing.
• /wayfinder — Plan a huge chunk of work, more than one agent session can hold, as a shared map of investigation tickets on the issue tracker.

Engineering Skills (Model-invoked)

• /prototype — Build a throwaway prototype to answer a design question.
• /diagnosing-bugs — Disciplined diagnosis loop: reproduce → minimise → hypothesise → instrument → fix → regression-test.
• /research — Investigate a question against high-trust primary sources and capture the findings as a cited Markdown file.
• /tdd — Test-driven development with a red-green-refactor loop.
• /domain-modeling — Actively build and sharpen a project's domain model.
• /codebase-design — Shared discipline for designing deep modules.
• /code-review — Two-axis review: standards and spec conformance.
• /resolving-merge-conflicts — Work through merge conflicts hunk by hunk.

Productivity Skills (User-invoked)

• /grill-me — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved.
• /handoff — Compact the current conversation into a handoff document for another agent.
• /teach — Teach the user a new skill or concept over multiple sessions.
• /writing-great-skills — Reference for writing and editing skills well.

Productivity Skills (Model-invoked)

• /grilling — The reusable loop behind grill-me and grill-with-docs.

How It Works

1. You invoke a skill (e.g., /grill-me) in your AI agent (Claude Code, Codex, etc.).
2. The skill executes a series of steps: asking questions, analyzing input, generating documents, modifying code, or committing changes.
3. You receive the result: an aligned plan, refined terminology, better code architecture, test cases, code review, etc.

What You Need to Provide

• An AI coding agent that supports skill invocation (e.g., Claude Code, Codex).
• On first use per repo, run /setup-matt-pocock-skills to configure: choose an issue tracker (GitHub, Linear, or local files), set triage labels, and specify where docs are saved.
• Depending on the skill, you may need to provide problem descriptions, code files, command-line feedback, etc.

What You'll Get

• A set of reusable engineering practices to collaborate more effectively with AI agents.
• Deep alignment on plans, avoiding misunderstandings.
• A shared domain language that reduces verbose agent output.
• Automated execution of TDD, code review, architecture improvement, and other processes.
• Continuously improving codebase quality.

Usage Example

Here's an example of the shared language effect, from CONTEXT.md in the course-video-manager repo:

• BEFORE: "There's a problem when a lesson inside a section of a course is made 'real' (i.e. given a spot in the file system)"
• AFTER: "There's a problem with the materialization cascade"

This concision pays off session after session.

Selection Guide

• User-invoked skills require you to type the command manually (e.g., /grill-me).
• Model-invoked skills can be triggered by you or automatically linked by the agent when the task fits.
• User-invoked skills may invoke model-invoked skills, but never another user-invoked one.

Important Notes

• This skill set requires an AI coding agent such as Claude Code or Codex.
• Run /setup-matt-pocock-skills once per repo after installation to configure.
• Skill files are independent; you can modify them if installed via skills.sh.
• No specific output quality is guaranteed; actual results depend on the agent's capabilities and your usage.