Using Matt Pocock Skills with Codex

The Matt Pocock skills give Codex a structured way to turn an idea into a reviewed change: clarify the problem, make a spec, split the work, implement it, and verify it. They are available globally to Codex in this workspace. Use this page to choose a skill by the problem in front of you. Use the generated skills reference when you need the exact source instructions for a skill.

This guide does not replace this repository’s operating rules. AGENTS.md, the task done gate, the Linear-Codex process, and screenshot-based verification take precedence over any upstream skill instruction.

Start here

Choose the smallest entry point that matches the work:

Situation	Start with	Then
You are unsure which workflow fits	`ask-matt`	Follow its recommended route.
You have an idea that needs pressure-testing	`grill-with-docs`	`to-spec` → `to-tickets` → `implement`.
You have a focused, already-understood change	`implement`	`code-review` and the repository’s verification gate.
A defect is unclear, intermittent, or needs evidence	`diagnosing-bugs`	`tdd` or `implement` once the cause is proven.
You need a throwaway answer to one design question	`prototype`	Bring the result back into the specification.
The work is larger than one planning session	`wayfinder`	`to-spec` after the decision map is resolved.

Do not run every skill for every task. A small, known-path documentation or copy edit should still use the repository’s micro-change fast path. For normal implementation and verification work in this repository, begin with the local qa-task workflow and use the skills below when their specific problem applies.

The primary flow

Idea or request
  -> grill-with-docs (when the idea is not ready)
  -> to-spec (when the outcome is agreed)
  -> to-tickets (when the work needs independent slices)
  -> implement (one slice at a time)
  -> code-review
  -> repository verification and publish gates

handoff is the bridge when the conversation needs to move to a fresh Codex task. prototype is a temporary detour when a runnable experiment will answer a question more reliably than discussion.

Planning and discovery skills

Skill	Use it when	What it produces
`ask-matt`	You cannot tell which skill or sequence fits.	A recommended workflow route.
`grill-me`	You want to sharpen an idea that is not tied to a repository.	A clarified plan in the conversation.
`grill-with-docs`	You need to sharpen a repository-backed idea and preserve decisions.	A clearer plan plus durable context/decision documentation.
`grilling`	You want a focused, rigorous challenge of an assumption, decision, or design.	Exposed assumptions and resolved questions.
`to-spec`	The conversation already contains an agreed outcome and needs a buildable specification.	A specification on the configured tracker.
`to-tickets`	A specification needs independently deliverable vertical slices.	Ordered, dependency-aware tickets.
`wayfinder`	The initiative is too uncertain or large to plan in one session.	A shared map of decision tickets, not implementation tickets.
`research`	A question needs source-backed investigation before deciding or building.	A cited Markdown research artifact.

Building and quality skills

Skill	Use it when	What it protects or produces
`implement`	You have a scoped specification or agent-ready ticket.	The implementation, built in small testable slices.
`tdd`	You want a feature or bug fix driven by a failing behavior test.	Red-green-refactor implementation and regression coverage.
`diagnosing-bugs`	A failure is hard to explain, intermittent, slow, or regressed.	A tight failing feedback loop, confirmed cause, and regression test.
`code-review`	You need an independent review of a diff, branch, or pull request.	Standards and specification review findings.
`improve-codebase-architecture`	You are looking for structural improvements that make the codebase easier to change.	Deepening opportunities and a focused next design problem.
`resolving-merge-conflicts`	A Git merge or rebase is already conflicted.	A deliberate conflict resolution with validation.
`prototype`	One behavior, state model, or interface needs a quick experiment before committing to it.	Throwaway code that answers the question; do not promote it directly to production.

Context, language, and learning skills

Skill	Use it when	What it produces
`handoff`	You need to continue in a fresh task without losing the important context.	A compact handoff document for the next task.
`domain-modeling`	Domain vocabulary is fuzzy, overloaded, or disputed.	A sharper glossary and, when warranted, an ADR.
`codebase-design`	You are choosing a module boundary, interface, seam, or testability strategy.	Shared deep-module vocabulary for the design decision.
`teach`	You want Codex to teach a concept or skill within this workspace.	A tailored explanation or learning path.
`writing-great-skills`	You are creating or editing a skill and need it to be predictable and focused.	A better skill contract and instruction set.

Intake and triage skills

Skill	Use it when	What it produces
`setup-matt-pocock-skills`	You are configuring a new repository for this workflow suite for the first time.	Tracker, triage-label, and domain-doc configuration.
`triage`	Incoming bug reports or feature requests need categorization and an agent-ready brief.	A reviewed, stateful triage outcome.

For this repository, do not rerun setup-matt-pocock-skills to select a tracker without resolving the existing tracker-policy mismatch first. Full Codex tasks use Linear as the ownership source of truth, even where older documentation mentions GitHub Issues.

Repository-specific rules that always win

Tracking: Full-process work must have a Linear issue, task file, handoff, and milestone comments. Do not publish work tickets to GitHub merely because an upstream skill uses GitHub examples.
Verification: User-visible work needs actual end-to-end proof and a screenshot on the canonical route or artifact before it can be described as complete.
Debugging: Observe the running system and identify the first failing boundary before changing product code. diagnosing-bugs complements this requirement; it does not replace it.
UI work: Reuse the canonical shared route, primitive, or pattern first, and apply the Alleato product noise gate.
Publishing: The main application and this ReadMe site have separate Git boundaries. Commit and publish only the files owned by the task in the repository that owns them.

Examples

A new feature that affects several surfaces

Use grill-with-docs to settle the outcome. Use to-spec to capture the accepted behavior, then to-tickets to create vertical slices. Run implement for one slice at a time, followed by code-review and the repository’s browser and screenshot verification gates.

A production bug with an unclear cause

Start with diagnosing-bugs, using browser/runtime evidence to establish a repeatable failure. Once the first broken boundary is known, use tdd or implement for the repair and keep the regression test.

An ambiguous architectural improvement

Use improve-codebase-architecture to find a high-leverage opportunity. Use codebase-design when choosing the seam, then return to the normal planning and implementation flow only after the problem is concrete.

​Using Matt Pocock Skills with Codex

​Start here

​The primary flow

​Planning and discovery skills

​Building and quality skills

​Context, language, and learning skills

​Intake and triage skills

​Repository-specific rules that always win

​Examples

​A new feature that affects several surfaces

​A production bug with an unclear cause

​An ambiguous architectural improvement

​See also

Using Matt Pocock Skills with Codex

Start here

The primary flow

Planning and discovery skills

Building and quality skills

Context, language, and learning skills

Intake and triage skills

Repository-specific rules that always win

Examples

A new feature that affects several surfaces

A production bug with an unclear cause

An ambiguous architectural improvement

See also