mattpocock/skills

The mattpocock/skills repository provides a set of user-invoked and model-invoked skills designed to improve AI agent performance in software engineering tasks.

User-Invoked Skills (Orchestration)

These are triggered manually by the user via commands:

• /ask-matt: A router to help find the right skill for your current situation.
• /grill-with-docs: A grilling session that builds a project's domain model, updates CONTEXT.md, and manages ADRs to ensure alignment and shared language.
• /triage: Manages issues through a state machine of triage roles.
• /improve-codebase-architecture: Scans the codebase for design improvements and generates an HTML report.
• /setup-matt-pocock-skills: One-time configuration for issue trackers, triage labels, and doc layouts.
• /to-spec: Synthesizes current discussions into a formal specification.
• /to-tickets: Breaks plans or specs into actionable tickets (local files or tracker links).
• /implement: Executes work based on specs/tickets, driving /tdd and concluding with /code-review.
• /wayfinder: Plans large-scale work by creating a map of investigation tickets on an issue tracker.

Model-Invoked Skills (Discipline)

These are reusable patterns that the agent can invoke automatically or when prompted to maintain engineering discipline (e.g., TDD, debugging, or architectural adherence).

The in-progress directory contains experimental skills that are still under development. These skills may have rough edges, breaking changes, or may be abandoned. They are not yet included in the official plugin or the stable top-level README.

User-invoked experimental skills:

• loop-me: A session-based skill to grill yourself into implementable workflow specs using the current directory as a stateful workspace.
• wizard: Generates an interactive bash wizard to walk a human through manual procedures (e.g., setup, migrations, state transitions), including opening URLs and writing .env or GitHub Actions secrets.
• claude-handoff: Uses claude --bg to hand off the current conversation to a fresh background agent seeded with a handoff summary.
• setup-ts-deep-modules: Configures dependency-cruiser in a TypeScript repo to enforce deep module patterns (hiding implementation in subfolders).
• to-questionnaire: Converts undecided decisions into a Markdown questionnaire for asynchronous or meeting-based input.
• batch-grill-me: A design-tree interview that asks multiple questions per round based on settled prerequisites.

Writing-focused experimental skills:

• writing-beats: Shapes articles as a journey of beats using a choose-your-own-adventure style.
• writing-fragments: A grilling session that mines heterogeneous writing nuggets and appends them to a single document.
• writing-shape: Transforms raw markdown material into a structured article paragraph by paragraph.

The domain-modeling skill is used to actively build and sharpen a project's domain model. Use it when you need to pin down domain terminology (ubiquitous language), record architectural decisions, or maintain the domain model during other engineering tasks.

File Structure Patterns

Single Context Repository: Most repositories use a single context located at the root:

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       └── [ADR-FILES].md
└── src/

Multi-Context Repository: If a CONTEXT-MAP.md exists at the root, the repository uses multiple contexts. The map points to specific sub-directory CONTEXT.md files and their local docs/adr/ directories:

/
├── CONTEXT-MAP.md
├── docs/
│   └── adr/                          ← system-wide decisions
└── src/
    ├── ordering/
    │   ├── CONTEXT.md
    │   └── docs/adr/                 ← context-specific decisions
    └── billing/
        ├── CONTEXT.md
        └── docs/adr/                 ← context-specific decisions

Lazy Creation: Create files only when necessary. Create CONTEXT.md when the first term is resolved, and create docs/adr/ when the first ADR is required.

Wayfinder is a planning skill designed for large-scale engineering efforts that exceed the capacity of a single agent session. Instead of executing work immediately, it charts a shared map of decision tickets on an issue tracker.

Core Mental Model:

• Goal: Finding the path to a destination (a spec, a decision, or a migration), not charging at it.
• The Map: A single canonical issue (labeled wayfinder:map) that acts as an index of decisions made and a guide for what remains to be decided.
• Decision Tickets: Child issues of the map that represent specific questions or investigations. A ticket is resolved when a decision is reached, not when a feature is built.
• The Frontier: The set of open, unblocked, and unclaimed child tickets. This represents the edge of the known path.
• Fog of War: In-scope work that is currently too vague to be turned into a specific ticket. This is tracked in the Not yet specified section of the map.

# Wayfinder Concept
- Map = Index of decisions
- Ticket = A single decision/investigation
- Frontier = Unblocked, unclaimed tickets
- Fog = In-scope but unspecifiable work

A wizard is an interactive bash script generated by an AI agent to walk a human through manual, step-by-step procedures that automation cannot perform alone. This includes wiring up third-party services, running one-off migrations, or moving a project from state A to state B.

Key Characteristics

• Human-driven, Agent-authored: The agent writes the script, but you run it on your local machine. The agent never executes the script itself.
• Stateful: It tracks progress through stages and can write captured values directly to .env files or GitHub Actions secrets/variables.
• Ephemeral or Permanent: Use it as a one-off script in a scripts/ folder and delete it, or commit it to the repo to provide a standardized setup path for other developers.

When to use it

Reach for /wizard when you encounter a task requiring dashboard interaction or manual configuration:

• Service Configuration: Opening multiple dashboards to capture API keys and writing them to .env and CI.
• One-off Migrations: Sequencing irreversible steps behind confirmation gates.
• State Transitions: Walking a project through a transition and reporting failures.
• Documentation Replacement: Creating an executable version of a README setup guide to prevent documentation rot.