# Matt Pocock Skills — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT # Matt Pocock Skills Knowledge Base An LLM-maintained knowledge base on **Matt Pocock's Skills for Real Engineers** (github.com/mattpocock/skills, MIT) — agent-skill packages for Claude Code, Codex, and other coding agents. The plugin manifest's promoted set (22 skills) is the supported inventory; each skill has its own catalog entry. Verified against repo snapshot `2ab9580`. ## Concepts - [[concepts/overview|Overview]] - [[concepts/concepts-and-invocation|Concepts and invocation]] - [[concepts/installation-and-distribution|Installation and distribution]] - [[concepts/workflow-recipes|Workflow recipes]] - [[concepts/governance-and-limitations|Governance and limitations]] ## Catalog - [[entities/promoted-catalog|Promoted skill catalog]] — the full promoted inventory (start here) ### Engineering skills (17) - [[entities/ask-matt|ask-matt]] - [[entities/grill-with-docs|grill-with-docs]] - [[entities/triage|triage]] - [[entities/improve-codebase-architecture|improve-codebase-architecture]] - [[entities/setup-matt-pocock-skills|setup-matt-pocock-skills]] - [[entities/to-spec|to-spec]] - [[entities/to-tickets|to-tickets]] - [[entities/implement|implement]] - [[entities/wayfinder|wayfinder]] - [[entities/prototype|prototype]] - [[entities/diagnosing-bugs|diagnosing-bugs]] - [[entities/research|research]] - [[entities/tdd|tdd]] - [[entities/domain-modeling|domain-modeling]] - [[entities/codebase-design|codebase-design]] - [[entities/code-review|code-review]] - [[entities/resolving-merge-conflicts|resolving-merge-conflicts]] ### Productivity skills (5) - [[entities/grill-me|grill-me]] - [[entities/handoff|handoff]] - [[entities/teach|teach]] - [[entities/writing-great-skills|writing-great-skills]] - [[entities/grilling|grilling]] --- title: "Concepts and invocation" type: concept tags: [invocation, foundational, well-established, intermediate] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-readme-md.md", "raw/github_doc-skills-engineering-ask-matt-skill-md.md", "raw/github_doc-skills-engineering-triage-skill-md.md", "raw/github_doc-skills-engineering-tdd-skill-md.md", "raw/github_doc-skills-productivity-grilling-skill-md.md", "raw/github_doc-docs-engineering-setup-matt-pocock-skills-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # Concepts and invocation ## Definition Every promoted skill splits along one axis: **who can invoke it**. The README states this directly: "These split on one axis — who can invoke them. **User-invoked** skills are reachable only when you type them (e.g. `/grill-me`); their job is to orchestrate. **Model-invoked** skills can be invoked by you _or_ reached for automatically by the agent when the task fits; they hold the reusable discipline." ## How It Works The mechanism is a real, checked-in frontmatter flag, not just a README label. Each `SKILL.md` carries a `description:` field the host agent reads to decide relevance; user-invoked skills additionally carry `disable-model-invocation: true`, which the agent's own tooling honors by refusing to reach for that skill on its own. Confirmed directly against the frontmatter of files in `raw/`: - **User-invoked** (flag present): `ask-matt`, `grill-with-docs`, `triage`, `improve-codebase-architecture`, `setup-matt-pocock-skills`, `to-spec`, `to-tickets`, `implement`, `wayfinder` (engineering); `grill-me`, `handoff`, `teach`, `writing-great-skills` (productivity). - **Model-invoked** (flag absent): `prototype`, `diagnosing-bugs`, `research`, `tdd`, `domain-modeling`, `codebase-design`, `code-review`, `resolving-merge-conflicts` (engineering); `grilling` (productivity). This matches the README's own Reference section grouping exactly (see [[entities/promoted-catalog]] for the full table with per-skill sourcing). The composition rule the README states: "A user-invoked skill may invoke model-invoked skills, but never another user-invoked one." `ask-matt`'s own `SKILL.md` demonstrates this in practice — it is itself user-invoked and routes the user toward other user-invoked entry points (`/grill-with-docs`, `/triage`, `/wayfinder`) rather than calling them programmatically, while skills like `/implement` drive model-invoked disciplines (`/tdd`, `/code-review`) internally. ## Key Parameters - **The frontmatter flag** (`disable-model-invocation: true`) is the ground-truth signal, not just README prose — it is the same mechanism the host agent checks at runtime. - **The repo-specific configuration layer.** `setup-matt-pocock-skills` writes files under `docs/agents/` (`issue-tracker.md`, `domain.md`, and `triage-labels.md` when `triage` is installed) that other skills read instead of guessing project facts — see `raw/github_doc-docs-engineering-setup-matt-pocock-skills-md.md`. - **Shared vocabulary artifacts.** `CONTEXT.md` (built and sharpened by `grill-with-docs`/`domain-modeling`) and a **tracer bullet** — the project's term for a thin, end-to-end slice used to establish direction, referenced directly in `to-tickets`' own description ("tracer-bullet tickets, each declaring its blocking edges"). ## When To Use Consult this distinction before assuming a skill will "just happen" or must always be typed: model-invoked skills like `tdd` or `code-review` can be pulled in automatically by an orchestrating skill such as `implement`, but a user-invoked skill like `/wayfinder` or `/to-spec` only starts when a person types it. ## Risks & Pitfalls - Assuming a model-invoked skill (e.g. `research`, `prototype`) will never run without being asked — it can be selected automatically when the task fits its description. - Assuming a user-invoked skill can be chained into another user-invoked skill by an agent — the README's rule forbids this; a human must start each one. - Interactive, human-in-the-loop skills are not built for unattended runs. `triage`'s own `SKILL.md` instructs the agent to "flag it and ask the maintainer before doing anything else" when state roles conflict, and `setup-matt-pocock-skills` is explicitly "prompt-driven — explore, present what it found, confirm, then write — not a deterministic scaffold" (`raw/github_doc-docs-engineering-setup-matt-pocock-skills-md.md`). Treat these as needing an explicit human-decision strategy before running headless. ## Related Concepts - [[entities/promoted-catalog]] — the full 22-skill table with an Invocation class column grounded in this same frontmatter flag. - [[concepts/overview]] — what the collection is and who it's for. - [[concepts/workflow-recipes]] — concrete chains of user-invoked and model-invoked skills. - [[concepts/installation-and-distribution]] — where the `docs/agents/` configuration layer comes from. ## Sources - `raw/github_doc-readme-md.md` — the user-invoked/model-invoked definition and composition rule. - `raw/github_doc-skills-engineering-ask-matt-skill-md.md` — routing behavior across user-invoked entry points. - `raw/github_doc-skills-engineering-triage-skill-md.md` — `disable-model-invocation: true` flag; human-escalation instruction on conflicting state roles. - `raw/github_doc-skills-engineering-tdd-skill-md.md` — example of a model-invoked skill (no flag). - `raw/github_doc-skills-productivity-grilling-skill-md.md` — example of a model-invoked skill (no flag), the primitive behind `grill-me`/`grill-with-docs`. - `raw/github_doc-docs-engineering-setup-matt-pocock-skills-md.md` — `docs/agents/` configuration layer, prompt-driven behavior. --- title: "Governance and limitations" type: concept tags: [governance, advanced, well-established, intermediate] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-readme-md.md", "raw/github_release-v1-1-0.md", "raw/github_doc-skills-engineering-triage-skill-md.md", "raw/github_doc-docs-engineering-setup-matt-pocock-skills-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # Governance and limitations ## Definition Governance here means: which part of the repository is the plugin's supported surface, and what the toolkit does *not* promise. This wiki treats the README's "Reference" section — the list actually shipped in the Claude Code plugin manifest — as the authoritative promoted boundary, not a raw directory listing or a third-party mirror. ## How It Works The repository's source tree is larger than its promoted surface. Alongside the 17 engineering + 5 productivity directories in [[entities/promoted-catalog]], this KB's own `raw/` mirrors include an `in-progress/` bucket (e.g. `batch-grill-me`, `claude-handoff`, `loop-me`, `setup-ts-deep-modules`, `to-questionnaire`, `wizard`, `writing-beats`, `writing-fragments`, `writing-shape`) and a `misc/` bucket (`git-guardrails-claude-code`, `migrate-to-shoehorn`, `scaffold-exercises`, `setup-pre-commit`) — skills that exist in the repo but are not named in the README's promoted Reference section and are therefore out of this wiki's supported catalog. The boundary is not static. The pinned `v1.1.0` release notes (`raw/github_release-v1-1-0.md`) document exactly this kind of movement across a single release: **`code-review`** was renamed from the in-progress `review` skill and moved into `engineering/`, gaining plugin listing it didn't have before; **`research`** was added as a new skill, listed in the READMEs and added to `.claude-plugin/plugin.json`; **`wayfinder`** was renamed from `decision-mapping` and graduated out of `in-progress/` into `engineering/`; and `ask-matt` itself was updated to route five skills it had previously been missing. This is direct evidence that the promoted set changes between releases and must be re-checked at each new snapshot, not assumed stable. ## Key Parameters - **Manifest-as-boundary.** The README's Reference section (mirrored in `raw/github_doc-readme-md.md`) is the clearest statement of the managed Claude distribution's promoted inventory at this snapshot. - **Snapshot-scoped claims.** Every wiki page's `skills_snapshot` frontmatter value pins its claims to commit `2ab958093e83e0ec752e6c1c5932da465bf23e0c`. Re-verify against a fresh README/plugin listing before treating any promoted-set claim as current. - **Release cadence as maintenance evidence.** Four release-note mirrors exist in `raw/` (`github_release-v1-0-0.md`, `github_release-mattpocock-skills-1-0-0.md`, `github_release-v1-0-1.md`, `github_release-v1-1-0.md`), showing a repository under active, versioned change — a time-bounded observation, not a promise of future support or release cadence. ## When To Use Consult this page before citing anything from `in-progress/`, `misc/`, or a third-party listing as if it were part of the supported plugin surface, and before assuming a promoted-skill inventory from an older snapshot still holds. ## Risks & Pitfalls - **Skills are guidance, not execution.** They are instruction packages the host agent interprets; they are not an execution, security, or verification service. Results depend on the host agent, model, repository access, test tooling, and human decisions. - **Interactive workflows resist headless operation.** `setup-matt-pocock-skills` is "prompt-driven — explore, present what it found, confirm, then write — not a deterministic scaffold" (`raw/github_doc-docs-engineering-setup-matt-pocock-skills-md.md`), and `triage`'s own `SKILL.md` instructs the agent to stop and ask the maintainer whenever state-role transitions "look unusual," or when two state roles conflict. Neither is built to run unattended without an explicit human-decision strategy. - **Presence is not promotion.** A skill directory existing in the repository (in-progress, misc, or otherwise) does not mean the managed plugin ships it — check the promoted Reference list, not the directory tree. - **The managed and editable routes have different prerequisites.** The managed plugin requires Claude Code itself; the editable route requires a Node/npm-capable environment and network access to install and later update (see [[concepts/installation-and-distribution]]). ## Related Concepts - [[entities/promoted-catalog]] — the exact 22-skill promoted inventory this page's boundary claim rests on. - [[concepts/overview]] — the "promoted vs. present" distinction introduced at a high level. - [[concepts/installation-and-distribution]] — prerequisites for each distribution route. - [[concepts/concepts-and-invocation]] — why interactive skills escalate to a human instead of proceeding autonomously. ## Sources - `raw/github_doc-readme-md.md` — the promoted Reference section used as the authoritative boundary. - `raw/github_release-v1-1-0.md` — concrete evidence of the promoted set changing across a release (code-review, research, wayfinder). - `raw/github_doc-skills-engineering-triage-skill-md.md` — human-escalation instruction on conflicting or unusual triage transitions. - `raw/github_doc-docs-engineering-setup-matt-pocock-skills-md.md` — "prompt-driven, not a deterministic scaffold" characterization. --- title: "Installation and distribution" type: concept tags: [installation, integration, foundational, well-established, beginner] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-readme-md.md", "raw/github_doc-skills-engineering-setup-matt-pocock-skills-skill-md.md", "raw/github_doc-docs-engineering-setup-matt-pocock-skills-md.md", "raw/github_issue-feature-native-claude-code-marketplace-support.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # Installation and distribution ## Definition Installation is a two-step process regardless of which distribution path is chosen: (1) get the skill files onto the host agent through exactly one of two mutually exclusive routes, then (2) run `/setup-matt-pocock-skills` once per repository to bind the generic skill set to that repository's issue tracker, labels, and documentation layout. ## How It Works **Step 1 — pick one distribution path.** - **Managed Claude Code plugin.** `claude plugins install mattpocock-skills`, or `/plugin install mattpocock-skills` from inside a session. The README states it "is in Claude Code's official marketplace, so there's nothing to add first, and updates arrive automatically." This capability was originally requested by the community rather than built in from day one: a filed feature request (`raw/github_issue-feature-native-claude-code-marketplace-support.md`) proposing a `.claude-plugin/marketplace.json` manifest was initially closed as not-yet-supported by the platform, then reopened and landed via a merged pull request once Claude Code's own marketplace mechanism existed. Consult Claude's own plugin documentation for host-level installation and lifecycle behavior — that layer is platform-defined, not something this wiki's `raw/` mirrors document. - **Editable installation (Codex and other agents).** `npx skills@latest add mattpocock/skills` copies selected skill files directly into the repository as ordinary, editable files. "The installer lets you choose which skills to take — make sure `setup-matt-pocock-skills` is one of them." Nothing updates automatically; pull upstream changes deliberately with `npx skills update`. This is also the documented route for using the skills, editably, inside Claude Code itself ("For tinkerers"). The README is explicit that these are alternatives, not additive: "Pick one — installing both leaves you with every skill twice." A native Codex plugin (matching the managed-plugin experience) is described in the README as "on the roadmap," pointing to an architecture-decision record (`.agents/adr/0002-ship-as-a-claude-code-plugin.md`) not mirrored in this KB's `raw/` set — treat the roadmap status as current only as of the pinned snapshot. **Step 2 — configure the repository once**, by running `/setup-matt-pocock-skills`. Per its own `SKILL.md` and richer docs page, it is prompt-driven rather than a deterministic scaffold: it explores the repository (git remote, existing labels, existing `CONTEXT.md`), proposes an answer for each of three decisions, and writes only after confirmation. - **Issue tracker** — GitHub, GitLab, local Markdown, or another workflow you describe; it proposes the tracker matching the repo's `git remote`. - **Triage labels** — asked only when the `triage` skill is installed; defaults to `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix` unless the repo's tracker already uses different names. - **Domain docs** — assumes a single `CONTEXT.md` + `docs/adr/` at the repo root unless it detects monorepo signals. Output lands under `docs/agents/`: `issue-tracker.md`, `domain.md`, and (only when `triage` is installed) `triage-labels.md`, plus an `## Agent skills` pointer written into whichever of `CLAUDE.md` or `AGENTS.md` the repo already uses. ## Key Parameters - **One path, not two.** Managed plugin (read-only, auto-updating) vs. editable install (owned files, manual `npx skills update`). - **`setup-matt-pocock-skills` is the load-bearing bootstrap.** The engineering skill chain (`triage`, `to-spec`, `to-tickets`, `wayfinder`) assumes the three `docs/agents/*.md` files it produces already exist; running it is a precondition, not an optional nicety. - **The `triage`-installed condition is exact**, not fuzzy: `docs/agents/triage-labels.md` and the triage-label question are gated specifically on whether the `triage` skill is installed, not merely on whether triage "seems relevant." ## When To Use Run this sequence once per new repository, before using any other engineering skill: pick a distribution path → install → run `/setup-matt-pocock-skills` → confirm its proposed tracker/labels/domain-doc choices → proceed to an entry skill such as `ask-matt`, `grill-with-docs`, `research`, or `prototype` (see [[concepts/workflow-recipes]]). Re-run `setup-matt-pocock-skills` only to switch issue trackers or start over; day-to-day tweaks are direct edits to `docs/agents/*.md`. ## Risks & Pitfalls - Installing both the managed plugin and the editable `npx skills` route in the same project duplicates every skill, per the README. - Skipping `/setup-matt-pocock-skills` leaves `triage`/`to-spec`/`to-tickets` guessing at tracker location and applying labels that may not exist in the repo. - The editable route requires a Node/npm-capable environment and network access to fetch and later update the skill files. - Native Codex plugin support does not yet exist per the README's own roadmap note at this snapshot; the documented workaround for Codex is the editable `npx skills` installer, not a managed subscription. ## Related Concepts - [[concepts/overview]] — why two distribution philosophies exist. - [[concepts/concepts-and-invocation]] — the `docs/agents/` configuration layer this setup step produces. - [[concepts/workflow-recipes]] — what to run immediately after setup. - [[entities/promoted-catalog]] — `setup-matt-pocock-skills` and `triage` catalog entries. - [[concepts/governance-and-limitations]] — the boundary between promoted and non-promoted skills you can install. ## Sources - `raw/github_doc-readme-md.md` — installation commands, "pick one" warning, Codex roadmap note. - `raw/github_doc-skills-engineering-setup-matt-pocock-skills-skill-md.md` — frontmatter, user-invoked flag, one-line role. - `raw/github_doc-docs-engineering-setup-matt-pocock-skills-md.md` — the three decisions, output files, prompt-driven behavior, re-run guidance. - `raw/github_issue-feature-native-claude-code-marketplace-support.md` — history of the managed-plugin/marketplace mechanism (closed, then landed via a merged PR). --- title: "Overview" type: concept tags: [catalog, foundational, well-established, beginner] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-readme-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # Overview ## Definition Matt Pocock's Skills ("Skills For Real Engineers", `github.com/mattpocock/skills`, MIT-licensed) is a public repository of agent-skill Markdown packages — small, composable instruction files for Claude Code, Codex, and other coding agents. The README frames them explicitly against process-owning frameworks like GSD, BMAD, and Spec-Kit: those "try to help by owning the process," while these skills are designed to be "small, easy to adapt, and composable," working with any model rather than one autonomous pipeline. ## How It Works The repository ships two parallel structures over the same skill content: a Claude Code plugin (`mattpocock-skills`, installed via `/plugin install mattpocock-skills`) that is a managed, read-only bundle updating on the author's release cadence, and an editable installer (`npx skills@latest add mattpocock/skills`) that copies selected skill files directly into a project for Codex and other agent harnesses. See [[concepts/installation-and-distribution]] for the full mechanics of each path. At any snapshot, the plugin promotes a fixed, named set of skill directories — 22 at the pinned commit `2ab958093e83e0ec752e6c1c5932da465bf23e0c` (17 engineering + 5 productivity). The full [[entities/promoted-catalog]] enumerates every one. The source tree also contains `in-progress/`, `misc/`, and other buckets that are not part of the promoted set (see [[concepts/governance-and-limitations]]). ## Key Parameters - **Snapshot pinning.** Every page in this wiki carries a `skills_snapshot` value tying its claims to one commit. The promoted set, invocation classes, and skill behavior can all change between releases (the v1.1.0 release notes alone promoted `code-review` out of `in-progress/`, added `research`, and graduated `wayfinder` — see [[concepts/governance-and-limitations]]). - **Two adoption philosophies.** "Subscribe" (managed plugin, you don't edit the files) versus "fork" (editable install, you own and can modify the copies). The README states installing both leaves every skill duplicated. - **Promoted vs. present.** Being present in the repository is not the same as being promoted by the plugin manifest; this wiki treats the plugin's promoted list as the supported inventory. ## When To Use This collection targets a developer or team that wants agent assistance while keeping explicit control over their issue tracker, domain vocabulary, documentation locations, tests, and review decisions — as opposed to handing the whole development process to an autonomous framework. The README frames four recurring failure modes it targets: agents that misunderstand what you want, agents that are too verbose because they lack shared vocabulary, code that doesn't work because of weak feedback loops, and codebases that turn into a "ball of mud" under agent-accelerated entropy. ## Risks & Pitfalls - Treating everything under `skills/` as supported — the misc/in-progress/personal buckets are explicitly excluded from the plugin's promoted set (see [[concepts/governance-and-limitations]]). - Assuming the toolkit verifies or executes anything on its own — it is an instructions/guidance layer; results depend on the host agent, model, and human decisions. - Installing via both the plugin and `npx skills` in the same project, which the README says duplicates every skill. ## Related Concepts - [[concepts/concepts-and-invocation]] — how user-invoked and model-invoked skills differ and compose. - [[entities/promoted-catalog]] — the full 22-skill inventory. - [[concepts/installation-and-distribution]] — choosing and setting up a distribution path. - [[concepts/workflow-recipes]] — how the skills chain together in practice. - [[concepts/governance-and-limitations]] — the promoted boundary, maintenance evidence, and limits. ## Sources - `raw/github_doc-readme-md.md` — purpose, philosophy, the four failure modes, distribution philosophy, promoted-count framing. --- title: "Workflow recipes" type: concept tags: [catalog, invocation, intermediate, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-ask-matt-skill-md.md", "raw/github_doc-skills-engineering-triage-skill-md.md", "raw/github_doc-skills-engineering-diagnosing-bugs-skill-md.md", "raw/github_doc-skills-engineering-wayfinder-skill-md.md", "raw/github_doc-readme-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # Workflow recipes ## Definition A workflow recipe is a documented composition of several promoted skills, chained to move a piece of work from a raw starting point to a shipped or resolved state. `ask-matt`'s own `SKILL.md` is the primary source for these compositions — it names itself "a router over the skills in this repo" and lays out the "main flow" plus several "on-ramps" that merge onto it. These are illustrative sequences the skills themselves document, not a mandatory pipeline the plugin enforces. ## How It Works ### The main flow: idea → ship 1. **`/grill-with-docs`** (or **`/grill-me`** with no codebase) — sharpen the idea by interview; `grill-with-docs` is stateful, retaining what it learns in `CONTEXT.md` and ADRs. 2. **Branch — does a question need a runnable answer?** Detour through **`/handoff`** out → **`/prototype`** to answer it with throwaway code → **`/handoff`** back into the original thread. 3. **Branch — is this a multi-session build?** - Yes → **`/to-spec`** (turn the thread into a spec) → **`/to-tickets`** (split into tracer-bullet tickets declaring blocking edges) → **`/implement`** per ticket, clearing context between each. - No → **`/implement`** directly, in the same context window. Either way, `/implement` drives **`/tdd`** internally one red-green slice at a time, then runs **`/code-review`** (a two-axis Standards + Spec review of the diff) before committing. `ask-matt` adds a context-hygiene rule: keep steps 1–3 in one unbroken context window — don't compact or clear until after `/to-tickets` — and watch the "smart zone" (roughly the token window within which the model still reasons sharply); if a session approaches it before `/to-tickets`, use `/handoff` rather than push on degraded. ### On-ramp: an incoming issue or bug report **`/triage`** is the on-ramp for issues "you didn't create" — bug reports, incoming feature requests, anything that arrives raw (including external PRs, which triage treats as "an issue with attached code" running through the same state machine). Per its own `SKILL.md`, triage moves an item through: gather context → recommend a category/state → verify the claim (reproduce a bug, or confirm a PR's diff does what it claims) → grill if the request needs fleshing out (running `/grilling` and `/domain-modeling` together) → apply the outcome (`ready-for-agent`, `ready-for-human`, `needs-info`, or `wontfix`). A `ready-for-agent` outcome hands off to **`/implement`**; tickets `/to-tickets` already produced should not be re-triaged. ### On-ramp: a hard bug **`/diagnosing-bugs`** is for bugs that resist a first glance — an intermittent flake, a regression that crept in between two known-good states. It "refuses to theorise until it has a tight feedback loop — one command that already goes red on this bug — then fixes with a regression test." Its post-mortem hands off to **`/improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down. ### On-ramp: a huge, foggy initiative **`/wayfinder`** is, in `ask-matt`'s own words, "the most cognitively demanding flow here" — for a greenfield project or feature build too big for one session. Its own `SKILL.md` describes it as planning such work "as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear." It produces decisions, not deliverables. When the map clears, it hands off — merging onto the main flow at **`/to-spec`**, then `/to-tickets` and `/implement` as usual; looping the map straight into `/implement` skips that collapse and discards linked detail. ### Codebase health (not feature work — upkeep) **`/improve-codebase-architecture`** — run whenever there's a spare moment to keep a codebase good for agents to operate in. It surfaces "deepening opportunities" as a visual HTML report; picking one generates an idea to take into the main flow at `/grill-with-docs`. **`/codebase-design`** supplies the underlying deep-module vocabulary (module, interface, depth, seam) that `/tdd` and `/improve-codebase-architecture` both draw on. ## Key Parameters - **Vocabulary underneath.** `/domain-modeling` and `/codebase-design` are model-invoked references that run beneath the process-oriented skills above — reach for them directly when the words, not the process, are the problem. - **`/handoff` vs. `/compact`.** `/handoff` forks into a fresh session while preserving the current conversation as a Markdown file; the built-in `/compact` stays in the same conversation, summarizing earlier turns. Use `/handoff` when branching (e.g. into a `/prototype` detour); use `/compact` at intentional breaks between phases. ## When To Use Use the main flow for ordinary feature work with a codebase; drop to `/grill-me` for planning with no codebase yet. Reach for the triage on-ramp when issues arrive from outside (bug reports, external PRs); reach for `/diagnosing-bugs` when something breaks and the cause isn't obvious; reach for `/wayfinder` only for efforts too large to hold in one session — the README explicitly frames it as denser and slower, "save it for exactly that, never a well-scoped feature." ## Risks & Pitfalls - Looping `/wayfinder`'s map directly into `/implement` skips the `/to-spec` collapse and throws away linked decision detail. - Re-triaging tickets that `/to-tickets` already produced — they're already agent-ready. - Compacting mid-phase with the built-in `/compact` instead of `/handoff` when actually branching to a new session — `ask-matt`'s own guidance is that the agent "can lose its way" if compacted mid-phase. - Pushing a long grilling/spec/ticketing session past the "smart zone" instead of using `/handoff` to start fresh. ## Related Concepts - [[entities/promoted-catalog]] — full details and invocation class for every skill named above. - [[concepts/concepts-and-invocation]] — why a user-invoked skill (like `ask-matt`) routes to other user-invoked skills instead of calling them directly. - [[concepts/installation-and-distribution]] — the `/setup-matt-pocock-skills` precondition these recipes assume is already done. - [[concepts/governance-and-limitations]] — human-in-the-loop limits on running these recipes unattended. ## Sources - `raw/github_doc-skills-engineering-ask-matt-skill-md.md` — main flow, on-ramps, codebase-health section, vocabulary-underneath section, handoff-vs-compact guidance. - `raw/github_doc-skills-engineering-triage-skill-md.md` — triage's internal state machine and hand-off to `/implement`. - `raw/github_doc-skills-engineering-diagnosing-bugs-skill-md.md` — diagnosis-loop framing (frontmatter description). - `raw/github_doc-skills-engineering-wayfinder-skill-md.md` — map-of-decision-tickets framing (frontmatter description). - `raw/github_doc-readme-md.md` — corroborating "most cognitively demanding" / scoping guidance for `/wayfinder`. --- title: "ask-matt" type: entity tags: [catalog, invocation, foundational, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-ask-matt-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # ask-matt ## Overview `ask-matt` is a router over every other skill in the repo — "you don't remember every skill, so ask." Its body is a map of the whole collection: the main "idea → ship" flow, the on-ramps that feed it, the codebase-health loop, the vocabulary layer underneath, session-crossing tools, and the standalone skills. It exists so a user unsure which flow fits can ask instead of guessing. ## Characteristics **User-invoked** — its frontmatter carries `disable-model-invocation: true`, so it is reachable only by typing `/ask-matt`, never fired automatically. It targets the same coding-agent harness as the rest of the repo (Claude Code or a compatible agent). It writes nothing itself: it is a decision-tree reference, not a process with file outputs. ## How to Use Type `/ask-matt` when unsure which skill or flow fits the situation at hand. Its body lays out: - **The main flow** (idea → ship): `/grill-with-docs` to sharpen the idea (or `/grill-me` with no codebase) → an optional detour through `/prototype`, bridged by `/handoff` in both directions → branch on whether it's multi-session (`/to-spec` then `/to-tickets`, worked ticket-by-ticket) or single-session (`/implement` directly) → `/implement` drives `/tdd` internally, then runs `/code-review` before committing. - **On-ramps**: `/triage` for incoming issues/PRs, `/diagnosing-bugs` for something broken, `/wayfinder` for a huge foggy effort too big for one session. - **Codebase health**: `/improve-codebase-architecture`, run whenever there's a spare moment. - **Vocabulary underneath**: `/domain-modeling` and `/codebase-design`, model-invoked references other skills pull in. - **Crossing sessions**: `/handoff` (fork to a new session) vs. built-in `/compact` (stay in the same conversation). - **Standalone**: `/grill-me`, `/prototype`, `/research`, `/teach`, `/writing-great-skills`. - **Precondition**: `/setup-matt-pocock-skills`, run once before the first use of the other engineering skills. ## Related Entities - [[entities/grill-with-docs]] — the main flow's entry point for a repo with a codebase. - [[entities/triage]], [[entities/diagnosing-bugs]], [[entities/wayfinder]] — the three on-ramps. - [[entities/improve-codebase-architecture]] — the codebase-health loop. - [[entities/domain-modeling]], [[entities/codebase-design]] — the vocabulary layer. - [[entities/setup-matt-pocock-skills]] — the precondition for every other engineering skill. - [[entities/to-spec]], [[entities/to-tickets]], [[entities/implement]], [[entities/tdd]], [[entities/code-review]], [[entities/prototype]], [[entities/research]] — the rest of the main-flow chain it maps. - [[concepts/concepts-and-invocation]] — the invocation-class mechanism referenced throughout. - [[entities/promoted-catalog]] — the full 22-skill inventory this page routes across. --- title: "code-review" type: entity tags: [catalog, invocation, governance, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-code-review-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # code-review ## Overview `code-review` runs a two-axis review of the diff since a fixed point (commit, branch, tag, or merge-base): **Standards** (does the code follow this repo's documented coding standards, plus a fixed smell baseline) and **Spec** (does the code match what the originating issue/PRD asked for). Both axes run as parallel sub-agents so they don't pollute each other's context, then the findings are reported side by side, never merged. ## Characteristics **Model-invoked** — no `disable-model-invocation` flag; used when the user wants to review a branch, PR, work-in-progress changes, or asks to "review since X." Assumes `docs/agents/issue-tracker.md` exists (run `/setup-matt-pocock-skills` if not). Spawns exactly two `general-purpose` sub-agents in parallel via the `Agent` tool, each briefed to report in under 400 words. Produces no files — just the two reports plus a one-line per-axis summary. ## How to Use (1) **Pin the fixed point** the user names (ask if they didn't); capture `git diff ...HEAD` and `git log ..HEAD --oneline`; confirm the ref resolves (`git rev-parse `) and the diff is non-empty before spawning sub-agents. (2) **Identify the spec source** — issue references in commit messages, a user-passed path, a PRD under `docs/`/`specs/`/`.scratch/`, or ask; if none exists, the Spec sub-agent reports "no spec available." (3) **Identify standards sources** — `CODING_STANDARDS.md`, `CONTRIBUTING.md`, etc., plus an always-on 12-item Fowler smell baseline (Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Repeated Switches, Shotgun Surgery, Divergent Change, Speculative Generality, Message Chains, Middle Man, Refused Bequest) — a documented repo standard always overrides the baseline, and every baseline smell is a judgement call, never a hard violation. (4) **Spawn both sub-agents in parallel** — Standards gets the diff, standards sources, and the full smell baseline pasted in; Spec gets the diff and the spec contents. (5) **Aggregate**: present both reports verbatim under `## Standards` / `## Spec`, never merged or reranked, then a one-line summary of total findings and the worst issue *within each axis*. `/implement` runs this skill automatically once implementation is done, before committing. ## Related Entities - [[entities/implement]] — runs this skill automatically at the end of each implementation. - [[entities/tdd]] — deliberately keeps refactoring judgement out of its own loop, deferring it to this skill. - [[entities/setup-matt-pocock-skills]] — provides the `docs/agents/issue-tracker.md` this skill assumes. - [[entities/ask-matt]] — names this as reachable standalone for reviewing a branch or PR. - [[entities/promoted-catalog]] — full inventory. --- title: "codebase-design" type: entity tags: [catalog, invocation, foundational, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-codebase-design-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # codebase-design ## Overview `codebase-design` is a shared vocabulary and set of principles for designing **deep modules** — a lot of behaviour behind a small interface, at a clean seam, testable through that interface — used wherever code is being designed or restructured, aiming for leverage (callers), locality (maintainers), and testability. ## Characteristics **Model-invoked** — no `disable-model-invocation` flag; used when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the vocabulary. It is a reference skill — no files of its own — pointing to `DEEPENING.md` (deepening a cluster given its dependencies) and `DESIGN-IT-TWICE.md` (parallel sub-agents designing alternative interfaces, compared on depth/locality/seam placement) for deeper process. ## How to Use Use its exact glossary and never substitute "component," "service," "API," or "boundary": **Module** (anything with an interface + implementation, scale-agnostic), **Interface** (everything a caller must know — type signature, invariants, ordering, error modes, config, performance — not just the type-level surface), **Implementation**, **Depth** (leverage per unit of interface learned), **Seam** (Michael Feathers — where behaviour can be altered without editing there), **Adapter** (a concrete thing satisfying an interface at a seam), **Leverage**, **Locality**. Apply the principles: depth is a property of the interface, not the implementation (a deep module can have internal seams too); the **deletion test** (would deleting the module concentrate complexity elsewhere, or just remove a pass-through); the interface is the test surface; **one adapter means a hypothetical seam, two means a real one**. For testability: accept dependencies rather than create them, return results rather than cause side effects, keep a small surface area. `/tdd` and `/improve-codebase-architecture` both speak this vocabulary; `/improve-codebase-architecture` uses it throughout its report and invokes this skill's design-it-twice pattern when exploring alternative interfaces. ## Related Entities - [[entities/improve-codebase-architecture]] — uses this vocabulary and pattern throughout its report and grilling loop. - [[entities/tdd]] — the seam/interface discipline this skill's testability section underlies. - [[entities/domain-modeling]] — the parallel vocabulary layer, for domain language rather than architecture. - [[entities/ask-matt]] — describes this as one of the two vocabulary layers underneath the other skills. - [[entities/promoted-catalog]] — full inventory. --- title: "diagnosing-bugs" type: entity tags: [catalog, invocation, advanced, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-diagnosing-bugs-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # diagnosing-bugs ## Overview `diagnosing-bugs` is a six-phase discipline for hard bugs and performance regressions. It refuses to theorize until it has a tight pass/fail feedback loop for the bug, then reproduces, minimizes, ranks hypotheses, instruments, fixes with a regression test, and closes with a cleanup/post-mortem. ## Characteristics **Model-invoked** — no `disable-model-invocation` flag; triggers on "diagnose"/"debug this" or a report that something is broken, throwing, failing, or slow. Reads `CONTEXT.md` and relevant ADRs before exploring. Tags every debug log with a unique prefix (e.g. `[DEBUG-a4f2]`) so cleanup is a single grep; writes no other dedicated files beyond the eventual regression test and fix. Its post-mortem can hand off explicitly to `/improve-codebase-architecture`. ## How to Use **Phase 1 — build a feedback loop** (the skill itself): construct a tight, red-capable signal via, in rough order, a failing test, a curl/HTTP script, a CLI+fixture diff, a headless-browser script, a replayed captured trace, a throwaway harness, a property/fuzz loop, a bisection harness, a differential loop, or last-resort a HITL bash script (`scripts/hitl-loop.template.sh`). Done when the loop is red-capable, deterministic (or a pinned high reproduction rate for flaky bugs), fast, and agent-runnable — paste the command and its output. If no loop can be built, stop and ask the user for access, a captured artifact, or permission to add temporary instrumentation; never hypothesize without one. **Phase 2 — reproduce + minimise**: confirm the loop reproduces the user's exact symptom, then shrink to the smallest scenario that still goes red, cutting one element at a time. **Phase 3 — hypothesise**: generate 3-5 ranked, falsifiable hypotheses ("If X is the cause, then changing Y will make the bug disappear") and show the ranked list to the user before testing. **Phase 4 — instrument**: one probe per prediction, one variable at a time; prefer a debugger/REPL over logs, and tagged targeted logs over "log everything." Performance regressions get a baseline measurement first, then bisection. **Phase 5 — fix + regression test**: write the failing regression test before the fix, but only at a correct seam that exercises the real bug pattern — if no correct seam exists, that absence is itself the finding to flag. Then fix, watch it pass, and re-run the Phase 1 loop against the original scenario. **Phase 6 — cleanup + post-mortem**: confirm the repro no longer reproduces, the regression test passes (or the seam gap is documented), all `[DEBUG-...]` instrumentation and throwaway prototypes are removed, and the correct hypothesis is stated in the commit/PR message. Then ask what would have prevented the bug — hand off to `/improve-codebase-architecture` if the answer is architectural. ## Related Entities - [[entities/improve-codebase-architecture]] — receives the post-mortem hand-off when the finding is architectural. - [[entities/tdd]] — shares the "write the test before the fix, at a real seam" discipline. - [[entities/code-review]] — the eventual review of the fix. - [[entities/ask-matt]] — names this as the on-ramp for "something's broken." - [[entities/promoted-catalog]] — full inventory. --- title: "domain-modeling" type: entity tags: [catalog, invocation, foundational, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-domain-modeling-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # domain-modeling ## Overview `domain-modeling` actively builds and sharpens a project's domain model as design happens — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. Merely *reading* `CONTEXT.md` for vocabulary is not this skill; this is for when the model is actually changing. ## Characteristics **Model-invoked** — no `disable-model-invocation` flag; used when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or another skill needs to maintain the domain model. Writes/updates `CONTEXT.md` (single-context repos) — or, when a root `CONTEXT-MAP.md` exists, the relevant per-context `CONTEXT.md` — plus ADRs under `docs/adr/`. Files are created lazily, only when there is something to write. ## How to Use During a session: **challenge** terms that conflict with `CONTEXT.md` immediately; **sharpen** vague or overloaded language into a precise canonical term; **discuss concrete scenarios** to stress-test domain relationships and edge cases; **cross-reference with code** and surface contradictions between stated behaviour and what the code actually does; **update `CONTEXT.md` inline**, not batched, the moment a term resolves, using the format in `CONTEXT-FORMAT.md` — `CONTEXT.md` is a glossary only, never a spec, scratch pad, or implementation record. **Offer an ADR** (format in `ADR-FORMAT.md`) only when all three hold: hard to reverse, surprising without context, and the result of a genuine trade-off. This skill runs beneath `/grill-with-docs`, `/improve-codebase-architecture`, `/triage`, and `/wayfinder` as the vocabulary layer they pull in. ## Related Entities - [[entities/grill-with-docs]] — the skill this discipline runs underneath by name. - [[entities/improve-codebase-architecture]] — keeps `CONTEXT.md` current inline during its grilling loop. - [[entities/triage]] — runs this alongside grilling when a request needs sharpening. - [[entities/wayfinder]] — uses this together with grilling to name a destination and resolve grilling tickets. - [[entities/codebase-design]] — the parallel vocabulary layer for architecture rather than domain language. - [[entities/ask-matt]] — describes this as one of the two vocabulary layers underneath the other skills. - [[entities/promoted-catalog]] — full inventory. --- title: "grill-me" type: entity tags: [catalog, invocation, foundational, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-productivity-grill-me-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # grill-me ## Overview `grill-me` is a productivity skill described in its own frontmatter as "A relentless interview to sharpen a plan or design." Its entire instruction body is a single line: "Run a `/grilling` session." It is a thin, user-invoked entry point that delegates all actual interview behavior to the `grilling` skill rather than implementing any interview logic itself. ## Characteristics - **Invocation class: User-invoked.** Frontmatter carries `disable-model-invocation: true`, so `grill-me` is reachable only by a human typing `/grill-me` — it cannot fire automatically and cannot be reached by another skill's own invocation. - **Target agent/harness:** ships as a `SKILL.md` package in the same catalog format as the rest of Matt Pocock's Skills (Claude Code plugin / skills.sh installs). - **Inputs/outputs:** no `argument-hint` is declared, and the skill body writes or reads no files itself — its only effect is to run a `/grilling` session. ## How to Use - **Trigger:** type `/grill-me`. Because of `disable-model-invocation: true`, this must be typed by a person; the agent will not select it on its own. - **Workflow:** the entire instruction, verbatim, is: "Run a `/grilling` session." All of the actual interview mechanics — branch-by-branch questioning, one question at a time, distinguishing lookupable facts from decisions the user must make — live in the `grilling` skill; see [[entities/grilling]] for that behavior. ## Related Entities - [[entities/grilling]] — the skill `grill-me` runs; holds all interview mechanics referenced above. - [[entities/promoted-catalog]] — `grill-me`'s row in the full 22-skill promoted inventory. - [[concepts/concepts-and-invocation]] — the user-invoked/model-invoked mechanism behind `grill-me`'s `disable-model-invocation: true` flag. - Part of the "grill" family alongside `grilling` and the engineering skill `grill-with-docs` (which layers ADR/glossary doc creation onto the same interview primitive); the family relationship is not itself stated in `grill-me`'s own `SKILL.md`. --- title: "grill-with-docs" type: entity tags: [catalog, invocation, foundational, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-grill-with-docs-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # grill-with-docs ## Overview `grill-with-docs` is a relentless interview to sharpen a plan or design, which also creates docs (ADRs and a glossary) as it goes. Its entire `SKILL.md` body is one line: run a `/grilling` session, using the `/domain-modeling` skill. It is the stateful, codebase-backed counterpart to `grill-me` — used when the interview has a repo to retain findings in. ## Characteristics **User-invoked** — frontmatter carries `disable-model-invocation: true`; only reachable by typing `/grill-with-docs`. It has no logic of its own: it composes two other skills (`grilling` for the interview mechanics, `domain-modeling` for capturing terms and decisions). Its side effects are whatever `domain-modeling` produces during the session — updates to `CONTEXT.md` and new ADRs under `docs/adr/` as terms and decisions crystallize. ## How to Use Invoke `/grill-with-docs` to start the interview. Per `ask-matt`, this is the entry point of the main "idea → ship" flow whenever there **is** a codebase — it's stateful, retaining what it learns in `CONTEXT.md` and ADRs, unlike the stateless `grill-me` used when there's no codebase. Both run the same underlying `/grilling` primitive; `grill-with-docs` is the one that leaves a paper trail. ## Related Entities - [[entities/domain-modeling]] — the discipline it runs to capture terms and ADRs during the interview. - [[entities/ask-matt]] — maps where this sits in the main flow. - [[entities/to-spec]] — the typical next step once the idea is sharpened. - [[entities/improve-codebase-architecture]] — hands its chosen candidate into this flow. - [[concepts/concepts-and-invocation]] — invocation-class mechanism. - [[entities/promoted-catalog]] — full inventory (`grilling` and `grill-me` are the productivity-side counterparts). --- title: "grilling" type: entity tags: [catalog, invocation, foundational, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-productivity-grilling-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # grilling ## Overview `grilling` interviews the user relentlessly about a plan, decision, or idea, walking down each branch of the decision tree and resolving dependencies between decisions one at a time until a shared understanding is reached. Its own frontmatter description states it should be used "when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases." It is the reusable interview primitive that other skills (e.g. `grill-me`) invoke rather than reimplement. ## Characteristics - **Invocation class: Model-invoked.** No `disable-model-invocation` flag appears in its frontmatter, so `grilling` can fire automatically when the task fits its description, be typed directly, or be reached for by another skill. - **Target agent/harness:** ships as a `SKILL.md` package in the same catalog format as the rest of Matt Pocock's Skills. - **Inputs/outputs:** purely conversational — no files or arguments are declared. Per its own body, facts that "can be found by exploring the environment (filesystem, tools, etc.)" should be looked up rather than asked of the user, but decisions are always put to the user for confirmation. ## How to Use - **Trigger:** fires automatically on "grill" trigger phrases or when the user wants to stress-test a plan, decision, or idea; can also be invoked directly, or run by another skill such as `grill-me`. - **Workflow**, verbatim from the `SKILL.md` body: - "Interview me relentlessly about every aspect of this until we reach a shared understanding. Walk down each branch of the decision tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer." - "Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering." - "If a *fact* can be found by exploring the environment (filesystem, tools, etc.), look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer." - "Do not act on it until I confirm we have reached a shared understanding." ## Related Entities - [[entities/grill-me]] — user-invoked entry point whose entire body is "Run a `/grilling` session." - [[entities/promoted-catalog]] — `grilling`'s row in the full 22-skill promoted inventory. - [[concepts/concepts-and-invocation]] — the model-invoked mechanism (absent `disable-model-invocation` flag) that lets `grilling` fire automatically or be reached by other skills. - Part of the "grill" family alongside `grill-me` and the engineering skill `grill-with-docs`, which layers ADR/glossary doc creation onto this same interview primitive; the family relationship is not itself stated in `grilling`'s own `SKILL.md`. --- title: "handoff" type: entity tags: [catalog, invocation, foundational, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-productivity-handoff-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # handoff ## Overview `handoff` compacts the current conversation into a handoff document so a fresh agent can continue the work. Its frontmatter describes it simply as: "Compact the current conversation into a handoff document for another agent to pick up." It declares an `argument-hint` of "What will the next session be used for?" — if the user passes arguments, they are treated as a description of the next session's focus and used to tailor the document. ## Characteristics - **Invocation class: User-invoked.** Frontmatter carries `disable-model-invocation: true`, so `handoff` is reachable only by typing `/handoff`. - **Target agent/harness:** ships as a `SKILL.md` package in the same catalog format as the rest of Matt Pocock's Skills. - **Inputs:** an optional argument describing what the next session will focus on (per `argument-hint`). - **Outputs:** a single handoff document saved to "the temporary directory of the user's OS - not the current workspace" (explicit instruction). The document must include a "suggested skills" section naming skills the next agent should invoke, must reference existing artifacts (specs, plans, ADRs, issues, commits, diffs) by path or URL rather than duplicating their content, and must redact sensitive information such as API keys, passwords, or personally identifiable information. ## How to Use - **Trigger:** type `/handoff`, optionally followed by a description of what the next session will be used for. - **Workflow**, verbatim/paraphrased from the `SKILL.md` body: - "Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace." - "Include a 'suggested skills' section in the document, which suggests skills that the agent should invoke." - "Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead." - "Redact any sensitive information, such as API keys, passwords, or personally identifiable information." - "If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly." ## Related Entities - [[entities/promoted-catalog]] — `handoff`'s row in the full 22-skill promoted inventory. - [[concepts/concepts-and-invocation]] — the user-invoked mechanism behind `handoff`'s `disable-model-invocation: true` flag. - [[entities/teach]] — another user-invoked productivity skill; `teach` persists state to a workspace directory across sessions, while `handoff` writes a one-off document to the OS temp directory for a single session transition. --- title: "implement" type: entity tags: [catalog, invocation, foundational, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-implement-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # implement ## Overview `implement` builds a piece of work described by a spec or a set of tickets. Its `SKILL.md` body is four terse instructions: drive `/tdd` at pre-agreed seams, check typing/tests along the way, run `/code-review` when done, then commit. ## Characteristics **User-invoked** — frontmatter carries `disable-model-invocation: true`. It is the shortest skill in the catalog: no branching logic, just an ordered checklist. Side effect: a commit to the current branch once work is done. ## How to Use Given a spec or tickets, use `/tdd` where possible, at pre-agreed seams. Run typechecking regularly and single test files regularly; run the full test suite once at the end. Once done, run `/code-review` to review the work. Commit the work to the current branch. In the main flow, `/implement` is kicked off per ticket (clearing context between each one) for multi-session work, or run directly in the same context window for single-session work — either way it drives `/tdd` internally one red-green slice at a time, then closes out with `/code-review` before committing. ## Related Entities - [[entities/tdd]] — driven internally at each pre-agreed seam. - [[entities/code-review]] — run automatically once implementation is done. - [[entities/to-tickets]], [[entities/to-spec]] — the usual sources of the work this skill builds. - [[entities/diagnosing-bugs]] — feeds fixes into this skill's regular flow. - [[entities/ask-matt]] — maps this as the terminal step of the main flow. - [[entities/promoted-catalog]] — full inventory. --- title: "improve-codebase-architecture" type: entity tags: [catalog, invocation, advanced, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-improve-codebase-architecture-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # improve-codebase-architecture ## Overview `improve-codebase-architecture` scans a codebase for "deepening opportunities" — refactors that turn shallow modules into deep ones — presents them as a visual HTML report, then runs a grilling loop through whichever candidate the user picks. It is codebase upkeep, not feature work: the survey that finds candidates for `/codebase-design` to design and `/grill-with-docs` to sharpen into an idea. ## Characteristics **User-invoked** — frontmatter carries `disable-model-invocation: true`. Uses the `/codebase-design` vocabulary (module, interface, depth, seam, adapter, leverage, locality) for every suggestion, and `CONTEXT.md`/ADRs for domain naming and prior decisions. Uses the `Agent` tool with `subagent_type=Explore` to walk the codebase. Writes a self-contained HTML report (Tailwind CDN + Mermaid CDN) to the OS temp directory as `/architecture-review-.html` — never into the repo — and opens it via `xdg-open`/`open`/`start`. ## How to Use Process: (1) **Explore** — scope by user direction or by walking `git log --oneline` for hot spots, read `CONTEXT.md`/ADRs, then use the `Explore` subagent to note friction (concept understanding scattered across modules, shallow interfaces, extracted-for-testability functions with no locality, leaky seams, untested/hard-to-test areas), applying the deletion test to anything suspected shallow; (2) **present candidates** as HTML cards — Files, Problem, Solution, Benefits, a before/after diagram, and a Recommendation strength badge (`Strong` / `Worth exploring` / `Speculative`) — ending with a Top recommendation, then ask "Which of these would you like to explore?"; (3) **grilling loop** — run `/grilling` on the chosen candidate, updating `CONTEXT.md` inline and offering an ADR when the user rejects a candidate for a load-bearing reason. Picking a candidate generates an idea to take into the main flow at `/grill-with-docs`. ## Related Entities - [[entities/codebase-design]] — the vocabulary this skill's report and grilling loop use throughout. - [[entities/domain-modeling]] — kept current inline as decisions crystallize during the grilling loop. - [[entities/diagnosing-bugs]] — its post-mortem hands off here when the finding is architectural. - [[entities/grill-with-docs]] — where a chosen candidate feeds back into the main flow. - [[entities/ask-matt]] — names this as the codebase-health loop. - [[entities/promoted-catalog]] — full inventory. --- title: "Promoted skill catalog" type: entity tags: [catalog, invocation, foundational, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-readme-md.md", "raw/github_doc-skills-engineering-ask-matt-skill-md.md", "raw/github_doc-skills-engineering-code-review-skill-md.md", "raw/github_doc-skills-engineering-codebase-design-skill-md.md", "raw/github_doc-skills-engineering-diagnosing-bugs-skill-md.md", "raw/github_doc-skills-engineering-domain-modeling-skill-md.md", "raw/github_doc-skills-engineering-grill-with-docs-skill-md.md", "raw/github_doc-skills-engineering-implement-skill-md.md", "raw/github_doc-skills-engineering-improve-codebase-architecture-skill-md.md", "raw/github_doc-skills-engineering-prototype-skill-md.md", "raw/github_doc-skills-engineering-research-skill-md.md", "raw/github_doc-skills-engineering-resolving-merge-conflicts-skill-md.md", "raw/github_doc-skills-engineering-setup-matt-pocock-skills-skill-md.md", "raw/github_doc-skills-engineering-tdd-skill-md.md", "raw/github_doc-skills-engineering-to-spec-skill-md.md", "raw/github_doc-skills-engineering-to-tickets-skill-md.md", "raw/github_doc-skills-engineering-triage-skill-md.md", "raw/github_doc-skills-engineering-wayfinder-skill-md.md", "raw/github_doc-skills-productivity-grill-me-skill-md.md", "raw/github_doc-skills-productivity-grilling-skill-md.md", "raw/github_doc-skills-productivity-handoff-skill-md.md", "raw/github_doc-skills-productivity-teach-skill-md.md", "raw/github_doc-skills-productivity-writing-great-skills-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # Promoted skill catalog ## Overview The Claude Code plugin manifest is the supported inventory for this repo: 22 skill directories, split 17 engineering + 5 productivity, at snapshot `2ab958093e83e0ec752e6c1c5932da465bf23e0c`. This is the navigation hub for that inventory — each skill now has its own entity page grounded in its own `SKILL.md`; this page just points to them. **Invocation class** follows the mechanism described in [[concepts/concepts-and-invocation]]: a skill's own frontmatter carries `disable-model-invocation: true` when it is **User-invoked** (reachable only by typing it); the flag is absent when it is **Model-invoked** (reachable by typing it, or automatically when the task fits). ## Characteristics ### Engineering (17) | Skill | Purpose | Invocation class | Page | |---|---|---|---| | `ask-matt` | Router over which skill or flow fits your situation. | User-invoked | [[entities/ask-matt]] | | `grill-with-docs` | Relentless interview to sharpen a plan/design; creates ADRs and glossary entries as it goes. | User-invoked | [[entities/grill-with-docs]] | | `triage` | Moves issues and external PRs through a state machine of triage roles, producing agent-ready briefs. | User-invoked | [[entities/triage]] | | `improve-codebase-architecture` | Scans a codebase for deepening opportunities, presents a visual HTML report, then grills through the pick. | User-invoked | [[entities/improve-codebase-architecture]] | | `setup-matt-pocock-skills` | Configures a repo's issue tracker, triage labels, and domain-doc layout. Run once first. | User-invoked | [[entities/setup-matt-pocock-skills]] | | `to-spec` | Synthesizes the current conversation into a spec, published to the issue tracker. | User-invoked | [[entities/to-spec]] | | `to-tickets` | Breaks a plan/spec into tracer-bullet tickets with declared blocking edges. | User-invoked | [[entities/to-tickets]] | | `implement` | Implements a spec or set of tickets, driving TDD and code-review internally. | User-invoked | [[entities/implement]] | | `wayfinder` | Plans huge, foggy efforts as a shared map of decision tickets, resolved one at a time. | User-invoked | [[entities/wayfinder]] | | `prototype` | Builds a throwaway prototype to answer a design question. | Model-invoked | [[entities/prototype]] | | `diagnosing-bugs` | Six-phase diagnosis loop for hard bugs and performance regressions. | Model-invoked | [[entities/diagnosing-bugs]] | | `research` | Delegates reading legwork to a background agent, citing primary sources. | Model-invoked | [[entities/research]] | | `tdd` | Reference for the red-green loop — good tests, seams, anti-patterns, loop rules. | Model-invoked | [[entities/tdd]] | | `domain-modeling` | Actively builds and sharpens a project's domain model — glossary and ADRs. | Model-invoked | [[entities/domain-modeling]] | | `codebase-design` | Shared vocabulary for designing deep modules — interface, depth, seam, adapter. | Model-invoked | [[entities/codebase-design]] | | `code-review` | Two-axis review (Standards + Spec) of a diff, run as parallel sub-agents. | Model-invoked | [[entities/code-review]] | | `resolving-merge-conflicts` | Resolves an in-progress git merge/rebase conflict by intent, then verifies. | Model-invoked | [[entities/resolving-merge-conflicts]] | ### Productivity (5) | Skill | Purpose | Invocation class | Page | |---|---|---|---| | `grill-me` | The same relentless interview as `grill-with-docs`, but stateless — for when there's no codebase. | User-invoked | [[entities/grill-me]] | | `handoff` | Compacts the current conversation into a handoff document for another agent/session to pick up. | User-invoked | [[entities/handoff]] | | `teach` | Teaches the user a new skill or concept, using the current workspace as stateful context. | User-invoked | [[entities/teach]] | | `writing-great-skills` | Reference for writing and editing skills well — the vocabulary of a predictable skill. | User-invoked | [[entities/writing-great-skills]] | | `grilling` | The reusable interview primitive underneath both `grill-me` and `grill-with-docs`. | Model-invoked | [[entities/grilling]] | **Totals: 17 engineering + 5 productivity = 22 promoted skills**, matching the README's Reference section and each skill's own frontmatter. ## How to Use Start from [[concepts/overview]] for what the collection is, or [[concepts/installation-and-distribution]] to get the skills installed and the repository configured. Use the tables above to jump straight to a skill's own entity page for its full Overview / Characteristics / How to Use / Related Entities — this hub intentionally stays high-level. [[concepts/workflow-recipes]] shows how several of these compose into end-to-end chains (idea → ship, an incoming issue, a hard bug, a large initiative); [[entities/ask-matt]] is the router skill that performs the same job inside a live session. This catalog is scoped to the 22 promoted skills only. The repository also contains `in-progress/` and `misc/` skill buckets present in the source tree but not part of the plugin's promoted Reference list at this snapshot — see [[concepts/governance-and-limitations]] for why those are excluded here and how the promoted boundary has shifted between releases. ## Related Entities - [[entities/ask-matt]] — the in-session router over this same 22-skill inventory. - [[concepts/concepts-and-invocation]] — the invocation-class mechanism this table's middle column is built on. - [[concepts/workflow-recipes]] — recipes that chain several of these skills together. - [[concepts/overview]] — what the collection is and the promoted-vs-present distinction. - [[concepts/installation-and-distribution]] — how to get these 22 skills installed and configured. - [[concepts/governance-and-limitations]] — why non-promoted buckets (`in-progress/`, `misc/`) are excluded, and how the promoted set has changed across releases. --- title: "prototype" type: entity tags: [catalog, invocation, intermediate, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-prototype-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # prototype ## Overview `prototype` builds a small, throwaway program that answers one design question — does a state model or logic feel right, or what should a UI look like. "A prototype is throwaway code that answers a question. The question decides the shape." ## Characteristics **Model-invoked** — no `disable-model-invocation` flag, so it can fire automatically on a fitting task or be typed as `/prototype`. Two branches, each producing a very different artifact: **LOGIC.md** for "does this feel right" questions (a tiny interactive terminal app pushing a state machine through hard-to-reason-about cases) and **UI.md** for "what should this look like" questions (several radically different UI variations on one route, switchable via a URL search param and a floating bottom bar). No persistence by default — state lives in memory unless the question is explicitly about persistence, in which case it hits a scratch DB or file clearly named "PROTOTYPE — wipe me." ## How to Use Identify which branch answers the question (from the prompt, surrounding code, or by asking); if genuinely ambiguous and the user isn't reachable, default to whichever branch matches the surrounding code (backend module → logic, page/component → UI) and state the assumption at the top of the prototype. Rules for both branches: throwaway from day one and clearly marked as such, located near where it will actually be used; one command to run (whatever the project's task runner supports); no persistence by default; skip polish — no tests, no error handling beyond runnability, no abstractions; surface the full relevant state after every action or variant switch; when done, fold the validated decision into real code, then commit the prototype itself to a throwaway branch out of main with a context pointer left on the implementation issue, capturing the verdict in the issue or a commit. It is the detour bridged by `/handoff` in step 2 of the main flow, and the vehicle for `wayfinder`'s HITL `prototype`-type tickets. ## Related Entities - [[entities/wayfinder]] — resolves its `prototype`-type tickets with this skill. - [[entities/to-spec]], [[entities/to-tickets]] — the one exception allowing a prototype-derived snippet into their otherwise snippet-free templates. - [[entities/handoff]] — bridges into and out of a prototype session in the main flow. - [[entities/ask-matt]] — describes this as the detour in step 2 of the main flow. - [[concepts/concepts-and-invocation]] — invocation-class mechanism. - [[entities/promoted-catalog]] — full inventory. --- title: "research" type: entity tags: [catalog, invocation, intermediate, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-research-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # research ## Overview `research` delegates reading legwork to a background agent: it investigates a question against high-trust primary sources and leaves a cited Markdown file in the repo, so the user can keep working while it reads. ## Characteristics **Model-invoked** — no `disable-model-invocation` flag; used when the user wants a topic researched, docs/API facts gathered, or reading legwork delegated to a background agent. Runs explicitly as a **background agent**. Output: a single Markdown file citing each claim's source, saved wherever the repo already keeps such notes (matching existing convention) or somewhere sensible if there is none — with the location stated. ## How to Use Spin up a background agent whose job is to: (1) investigate the question against primary sources — official docs, source code, specs, first-party APIs, not secondary write-ups — following every claim back to the source that owns it; (2) write the findings to a single Markdown file, citing each claim's source; (3) save it in the repo's existing notes location, or somewhere sensible if none exists, stating where. Per `ask-matt`, its output "feeds the thinking, it doesn't replace it" — take the resulting file into the main flow at `/grill-with-docs`. It is also the mechanism `/wayfinder` uses to resolve `wayfinder:research` tickets, firing one subagent per research ticket in parallel. ## Related Entities - [[entities/grill-with-docs]] — the typical destination for a research file's findings. - [[entities/wayfinder]] — resolves its `research`-type tickets with this skill, run in parallel. - [[entities/ask-matt]] — lists this among the standalone skills. - [[concepts/concepts-and-invocation]] — invocation-class mechanism. - [[entities/promoted-catalog]] — full inventory. --- title: "resolving-merge-conflicts" type: entity tags: [catalog, invocation, intermediate, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-resolving-merge-conflicts-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # resolving-merge-conflicts ## Overview `resolving-merge-conflicts` is a five-step procedure for resolving an in-progress git merge or rebase conflict, grounded in understanding the original intent behind each conflicting change before touching a hunk. ## Characteristics **Model-invoked** — no `disable-model-invocation` flag; used when the user needs to resolve an in-progress git merge/rebase conflict. Acts directly on the repo's working tree and git history; produces no dedicated output files. ## How to Use (1) **See the current state** of the merge/rebase — check git history and the conflicting files. (2) **Find the primary sources** for each conflict — commit messages, PRs, original issues/tickets — to understand deeply why each change was made and its original intent. (3) **Resolve each hunk**, preserving both intents where possible; where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do not invent new behaviour. (4) **Discover the project's automated checks** and run them — typically typecheck, then tests, then format — fixing anything the merge broke. (5) **Finish the merge/rebase** — stage everything and commit; if rebasing, continue the rebase process until all commits are rebased. Always resolve; never `--abort`. ## Related Entities - [[entities/tdd]] — the automated checks this skill re-runs overlap with the test discipline it protects. - [[entities/code-review]] — a natural follow-up once a conflicted branch is resolved and ready to land. - [[entities/ask-matt]] — names this as reachable standalone when a merge/rebase conflict needs resolving. - [[entities/promoted-catalog]] — full inventory. --- title: "setup-matt-pocock-skills" type: entity tags: [catalog, invocation, installation, foundational, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-setup-matt-pocock-skills-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # setup-matt-pocock-skills ## Overview `setup-matt-pocock-skills` scaffolds the per-repo configuration the other engineering skills assume: where the issue tracker lives, the triage label vocabulary, and the domain-doc layout. It is meant to run once, before the first use of any other engineering skill in a repo. ## Characteristics **User-invoked** — frontmatter carries `disable-model-invocation: true`. It is prompt-driven, not a deterministic script: explore, present findings, confirm with the user, then write. Outputs: `docs/agents/issue-tracker.md`, `docs/agents/domain.md`, and (only if `triage` is installed) `docs/agents/triage-labels.md`, plus a `## Agent skills` block added to `CLAUDE.md` or `AGENTS.md` (whichever already exists in the repo; asks the user if neither does, and never creates one when the other already exists). ## How to Use **Explore**: repo's `git remote`/`.git/config`, `CLAUDE.md`/`AGENTS.md`, `CONTEXT.md`/`CONTEXT-MAP.md`, `docs/adr/`, `docs/agents/`, `.scratch/`, whether `triage` is installed, and monorepo signals (`pnpm-workspace.yaml`, `workspaces`, populated `packages/*`). **Present and ask**, section by section, leading with the recommended answer: - **Issue tracker** — GitHub (`gh` CLI) if the remote points there, GitLab (`glab` CLI) if it points there, else offer Local markdown (`.scratch//`) or Other (freeform description). Records the choice in `docs/agents/issue-tracker.md`. - **Triage label vocabulary** — skipped entirely if `triage` isn't installed; otherwise one question, defaulting to the five canonical labels (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). - **Domain docs** — defaults to single-context (`CONTEXT.md` + `docs/adr/` at root) without asking; offers multi-context (`CONTEXT-MAP.md` + per-context `CONTEXT.md`) only when monorepo signals were found. **Confirm and edit**: show drafts of the `## Agent skills` block and the docs files; let the user edit before writing. **Write**: edit the chosen file in place (never append a duplicate block), then write the docs files from the skill's seed templates (`issue-tracker-github.md`, `issue-tracker-gitlab.md`, `issue-tracker-local.md`, `triage-labels.md`, `domain.md`). Re-running is only needed to switch trackers or restart. ## Related Entities - [[entities/triage]] — consumes the label vocabulary this skill records. - [[entities/to-spec]], [[entities/to-tickets]], [[entities/wayfinder]], [[entities/code-review]] — all assume `docs/agents/issue-tracker.md` exists and instruct running this skill first if it doesn't. - [[entities/domain-modeling]] — consumes the domain-doc layout this skill writes. - [[entities/ask-matt]] — names this as the precondition for the other engineering skills. - [[entities/promoted-catalog]] — full inventory. --- title: "tdd" type: entity tags: [catalog, invocation, foundational, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-tdd-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # tdd ## Overview `tdd` is the reference that makes the red → green loop produce tests worth keeping: what a good test is, where tests go (seams), the anti-patterns to avoid, and the rules of the loop. Every section applies on every cycle, consulted before and during the loop, not after. ## Characteristics **Model-invoked** — no `disable-model-invocation` flag; used when the user wants to build features or fix bugs test-first, mentions "red-green-refactor," or wants integration tests. Reads `CONTEXT.md` and ADRs for vocabulary consistency before exploring. Reference skill: produces the tests/implementation from the loop itself, not a dedicated file; points to `tests.md` and `mocking.md` for further examples. ## How to Use A good test verifies behaviour through public interfaces, not implementation details, and reads like a specification. **Seams** — the public boundary tested — must be agreed with the user before any test is written ("What's the public interface, and which seams should we test?"); no test is written at an unconfirmed seam. Avoid three anti-patterns: **implementation-coupled** tests (mock internals, test private methods, or check a side channel); **tautological** tests (the assertion recomputes the expected value the way the code does — expected values must come from an independent source of truth); **horizontal slicing** (writing all tests before all implementation — work in vertical slices instead, one test → one implementation → repeat). Rules of the loop: **red before green** (write the failing test first, then only enough code to pass it, no anticipating future tests); **one slice at a time** (one seam, one test, one minimal implementation per cycle); **refactoring is not part of the loop** — it belongs to `/code-review`, not the red → green cycle. `/implement` drives this skill internally at pre-agreed seams as it builds each ticket or spec. ## Related Entities - [[entities/implement]] — drives this skill internally at each pre-agreed seam. - [[entities/code-review]] — where refactoring judgement belongs, deliberately kept out of this loop. - [[entities/codebase-design]] — shares the seam/interface vocabulary this skill's testability language draws on. - [[entities/diagnosing-bugs]] — shares the "write the test before the fix, at a real seam" discipline. - [[entities/ask-matt]] — names this as reachable standalone for test-first work. - [[entities/promoted-catalog]] — full inventory. --- title: "teach" type: entity tags: [catalog, invocation, foundational, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-productivity-teach-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # teach ## Overview `teach` is described in its own frontmatter as: "Teach the user a new skill or concept, within this workspace." It declares an `argument-hint` of "What would you like to learn about?" Per its own body, this is "a stateful request - they intend to learn the topic over multiple sessions," so `teach` treats the current directory as a persistent **teaching workspace** that accumulates knowledge, skills, and wisdom across sessions rather than a one-off answer. ## Characteristics - **Invocation class: User-invoked.** Frontmatter carries `disable-model-invocation: true`, so `teach` is reachable only by typing `/teach`. - **Target agent/harness:** ships as a `SKILL.md` package in the same catalog format as the rest of Matt Pocock's Skills; state lives in the current working directory, treated as a teaching workspace. - **Inputs:** an optional argument describing what the user would like to learn about (per `argument-hint`). - **Files it reads/writes** (per the "Teaching Workspace" section): - `MISSION.md` — the reason the user is interested in the topic; grounds all teaching (format in `MISSION-FORMAT.md`). - `./reference/*.html` — compressed reference materials (cheat sheets, algorithms, glossaries) designed to print/read well for quick reference. - `RESOURCES.md` — high-quality resources to ground teaching in (format in `RESOURCES-FORMAT.md`). - `./learning-records/*.md` — numbered `0001-.md` records of non-obvious lessons/insights, used to calculate the user's zone of proximal development. - `./lessons/*.html` — the primary teaching unit: numbered `0001-.html` self-contained HTML lessons. - `./assets/*` — reusable components (stylesheets, quiz widgets, simulators, diagram helpers) shared across lessons. - `NOTES.md` — scratchpad for user preferences and working notes. ## How to Use - **Trigger:** type `/teach`, optionally with a description of the topic to learn. - **Workflow**, per the SKILL.md body: 1. If `MISSION.md` is missing or unclear, question the user on why they want to learn the topic before anything else; confirm with the user before changing an existing mission, and log the change as a learning record. 2. Before `RESOURCES.md` is well-populated, prioritize finding high-quality, high-trust resources — "Never trust your parametric knowledge." 3. Determine the user's zone of proximal development by reading `learning-records`, weighing it against the mission, and teaching "the most relevant thing that fits." 4. Before authoring a lesson, read `./assets/` and reuse existing components; write new reusable components there rather than inline duplication. A shared stylesheet is typically the first component a workspace earns. 5. Produce a lesson as one self-contained, beautiful (Tufte-style), quickly completable HTML file in `./lessons/`, titled `0001-.html` and incrementing. It must tie to the mission, sit in the user's zone of proximal development, link via HTML anchors to other lessons/references, recommend the single highest-quality primary source found, and remind the user to ask the agent followup questions. Open the file for the user via a CLI command if possible. 6. Produce reference documents in `./reference/*.html` as the compressed essence of lessons — syntax/snippets, algorithms/flowcharts, glossaries — for later quick reference; once a glossary exists, adhere to it in every lesson. 7. Split teaching between **knowledge** (acquired from trusted, cited resources, difficulty minimized) and **skills** (built through interactive, feedback-loop lessons using retrieval practice, spacing, and interleaving — difficulty is the tool for skill-building, not the enemy). 8. When a question requires **wisdom**, attempt to answer but default to pointing the user toward a high-reputation community, unless the user has said they don't want one. 9. Record user preferences and working notes in `NOTES.md` as they come up. ## Related Entities - [[entities/promoted-catalog]] — `teach`'s row in the full 22-skill promoted inventory. - [[concepts/concepts-and-invocation]] — the user-invoked mechanism behind `teach`'s `disable-model-invocation: true` flag. - [[entities/handoff]] — another user-invoked productivity skill; `handoff` writes a single OS-temp-dir document for a session transition, while `teach` maintains persistent workspace state across many sessions. --- title: "to-spec" type: entity tags: [catalog, invocation, foundational, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-to-spec-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # to-spec ## Overview `to-spec` turns the current conversation into a spec (a PRD) and publishes it to the project issue tracker. It does **not** interview the user — it is pure synthesis of what has already been discussed and of the codebase's current state. ## Characteristics **User-invoked** — frontmatter carries `disable-model-invocation: true`. Requires the issue tracker and triage label vocabulary already provided by `setup-matt-pocock-skills`. Publishes one issue to the configured tracker, tagged `ready-for-agent`, using a fixed spec template. ## How to Use Process: (1) explore the repo to understand current codebase state if not already done, using the domain glossary and respecting ADRs in the touched area; (2) sketch the seams the feature will be tested at — prefer existing seams over new ones, use the highest seam possible, and aim for as few seams as possible (ideally one) — and confirm them with the user; (3) write the spec and publish it with the `ready-for-agent` label, no additional triage needed. The spec template has fixed sections: **Problem Statement**, **Solution**, **User Stories** (a long numbered list, "As an \, I want a \, so that \"), **Implementation Decisions** (modules, interfaces, architectural decisions, schema/API contracts — no file paths or code snippets, except a prototype-derived snippet that encodes a decision precisely), **Testing Decisions** (what makes a good test, which modules, prior art), **Out of Scope**, and **Further Notes**. In the main flow this is the step after `/grill-with-docs` for multi-session work, feeding `/to-tickets` next; it's also where a `/wayfinder` map collapses once its decisions are resolved and the way is clear. ## Related Entities - [[entities/grill-with-docs]] — the interview step that typically precedes this one. - [[entities/to-tickets]] — the next step, breaking the spec into tickets. - [[entities/wayfinder]] — hands off to this skill once its map's decisions are resolved. - [[entities/setup-matt-pocock-skills]] — provides the tracker and label vocabulary this skill assumes. - [[entities/ask-matt]] — maps this into the main flow. - [[entities/promoted-catalog]] — full inventory. --- title: "to-tickets" type: entity tags: [catalog, invocation, foundational, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-to-tickets-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # to-tickets ## Overview `to-tickets` breaks a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring the other tickets that **block** it, published to the configured tracker — blocking edges as text in one file per ticket locally, or as native blocking links on a real tracker. ## Characteristics **User-invoked** — frontmatter carries `disable-model-invocation: true`. Requires the issue tracker and label vocabulary already provided by `setup-matt-pocock-skills`. Writes one file per ticket under `.scratch//issues/-.md` for a local tracker (numbered in dependency order), or publishes one issue per ticket with the `ready-for-agent` label on a real tracker (GitHub, Linear, etc.), using its native blocking/sub-issue relationship where available. ## How to Use Process: (1) gather context from the conversation, or fetch a referenced spec/issue if the user passes one; (2) optionally explore the codebase for prefactoring opportunities ("make the change easy, then make the easy change"), using domain glossary and ADRs; (3) draft **vertical slices** — each a tracer-bullet cutting a narrow but complete path through every layer (schema/API/UI/tests), demoable on its own, sized for one fresh context window. **Wide refactors** (one mechanical change with a codebase-wide blast radius) are the exception — sequence those as expand → migrate-in-batches → contract instead of forcing a vertical slice; (4) quiz the user on granularity and whether blocking edges are correct, iterating to approval; (5) publish in dependency order (blockers first), working the **frontier** (tickets whose blockers are all done). Never closes or modifies a parent issue. Avoids file paths and code snippets in ticket bodies, except a prototype-derived snippet that encodes a decision precisely. ## Related Entities - [[entities/to-spec]] — the typical predecessor, producing the spec this skill slices. - [[entities/implement]] — the consumer that builds each resulting ticket. - [[entities/wayfinder]] — a much larger-scale alternative for work too foggy to ticket directly. - [[entities/prototype]] — the source of the one code-snippet exception allowed in ticket bodies. - [[entities/setup-matt-pocock-skills]] — provides the tracker and label vocabulary this skill assumes. - [[entities/ask-matt]] — maps this into the main flow. - [[entities/promoted-catalog]] — full inventory. --- title: "triage" type: entity tags: [catalog, invocation, governance, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-triage-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # triage ## Overview `triage` moves issues — and, where the tracker config treats external PRs as a request surface, PRs too — through a small state machine of triage roles: categorise (`bug`/`enhancement`), verify the claim, grill if the request needs fleshing out, and write an agent-ready brief. It is only for issues the maintainer didn't create; tickets `to-tickets` already produced are agent-ready and shouldn't be re-triaged. ## Characteristics **User-invoked** — frontmatter carries `disable-model-invocation: true`. It targets whatever issue tracker `setup-matt-pocock-skills` configured (GitHub, GitLab, local markdown, or other) and the label vocabulary it recorded. Outputs: agent-brief or "ready-for-human" comments, triage-notes comments, entries under `.out-of-scope/*.md` for rejected enhancements, and label/state changes. Every comment or issue it posts must open with the disclaimer `> *This was generated by AI during triage.*`. ## How to Use Invoke `/triage` and describe intent in natural language — "Show me anything that needs my attention," "Let's look at #42," "Move #42 to ready-for-agent," "What's ready for agents to pick up?" Process per issue/PR: (1) gather context — full body/comments/labels, prior triage notes, explore the codebase for redundancy (already implemented?) and prior rejection (`.out-of-scope/`); (2) recommend a category + state with reasoning and wait for direction; (3) verify the claim — reproduce a bug, or check out and test a PR's diff; (4) grill if needed, via `/grilling` and `/domain-modeling` together; (5) apply the outcome — post an agent brief (`ready-for-agent`), a human-brief with why it can't be delegated (`ready-for-human`), triage notes (`needs-info`), or close with reasoning (`wontfix`: already-implemented, rejected-bug, or rejected-enhancement written to `.out-of-scope/`). A maintainer saying "move #42 to X" is applied directly, skipping grilling. ## Related Entities - [[entities/setup-matt-pocock-skills]] — provides the tracker and label vocabulary this skill assumes. - [[entities/implement]] — the eventual consumer of a `ready-for-agent` brief. - [[entities/domain-modeling]] — invoked together with grilling when a request needs fleshing out. - [[entities/ask-matt]] — names this as the on-ramp for "bugs and requests piling up." - [[concepts/concepts-and-invocation]] — invocation-class mechanism. - [[entities/promoted-catalog]] — full inventory. --- title: "wayfinder" type: entity tags: [catalog, invocation, advanced, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-engineering-wayfinder-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # wayfinder ## Overview `wayfinder` plans a huge, foggy chunk of work — more than one agent session can hold — as a shared **map** of decision tickets on the issue tracker, resolving them one at a time until the way to a named **destination** is clear. It is planning by default: each ticket resolves a decision, not a slice of a build, and the map is done when nothing is left to decide before someone goes and does the thing. ## Characteristics **User-invoked** — frontmatter carries `disable-model-invocation: true`. Described in its own `SKILL.md` as "the most cognitively demanding flow" in the repo — reserved for a greenfield project or huge feature, never a well-scoped feature. Writes a **map** issue labelled `wayfinder:map` (sections: Destination, Notes, Decisions so far, Not yet specified, Out of scope) plus child ticket issues each labelled `wayfinder:`. Falls back to the local-markdown tracker if none is configured via `setup-matt-pocock-skills`. Uses the tracker's native blocking relationship so the "frontier" (open, unblocked, unclaimed tickets) is visible in the tracker's own UI. ## How to Use Two modes: - **Chart the map** (user invokes with a loose idea): name the destination via `/grilling` + `/domain-modeling`; grill breadth-first to map the fog (if no fog surfaces, the effort is small enough for one session — stop, no map needed); create the map with Decisions-so-far empty and the fog in Not yet specified; create the tickets you can specify now as child issues, then wire blocking edges in a second pass; fire `/research` subagents in parallel for any research tickets. Charting is one session's work — it hand-resolves nothing. - **Work through the map** (user invokes with a map URL/number, optionally naming a ticket): load the map's low-res view; choose and **claim** a frontier ticket (assign it to yourself before any work); resolve it using the skill named by its `wayfinder:` label (research → `/research`; prototype → `/prototype`, HITL; grilling → `/grilling` + `/domain-modeling`, the default case; task → manual work, AFK or HITL); record the resolution as a comment, close the ticket, append a one-line gist to Decisions-so-far; add or graduate newly-specifiable tickets from the fog, or rule out-of-scope tickets closed with a gist. Never resolve more than one ticket per session, except research tickets. When the map clears, it hands off — it doesn't build: merge onto the main flow at `/to-spec`, then `/to-tickets` and `/implement` as usual (going straight to `/implement` only when the effort turned out genuinely small). ## Related Entities - [[entities/to-spec]] — where a cleared map hands off into the main flow. - [[entities/research]] — the subagent resolving `wayfinder:research` tickets. - [[entities/prototype]] — resolves `wayfinder:prototype` tickets. - [[entities/domain-modeling]] — used with grilling to name the destination and resolve grilling tickets. - [[entities/setup-matt-pocock-skills]] — provides the tracker wayfinder operations live on. - [[entities/ask-matt]] — names this as the on-ramp for huge, foggy efforts. - [[entities/promoted-catalog]] — full inventory. --- title: "writing-great-skills" type: entity tags: [catalog, invocation, foundational, well-established] created: 2026-08-02 updated: 2026-08-02 sources: ["raw/github_doc-skills-productivity-writing-great-skills-skill-md.md"] confidence: high skills_snapshot: "2ab958093e83e0ec752e6c1c5932da465bf23e0c" --- # writing-great-skills ## Overview `writing-great-skills` is a reference skill described in its own frontmatter as: "Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable." Its own body states directly, "This skill is all reference" — it defines terms and heuristics (invocation choice, description-writing, an information hierarchy, when to split a skill, pruning, leading words, and named failure modes) rather than walking through an ordered sequence of steps. Its opening line frames the whole skill: "A skill exists to wrangle determinism out of a stochastic system. **Predictability** — the agent taking the same _process_ every run, not producing the same output — is the root virtue; every lever below serves it." ## Characteristics - **Invocation class: User-invoked.** Frontmatter carries `disable-model-invocation: true`, so it is reachable only by typing `/writing-great-skills`. - **Target agent/harness:** ships as a `SKILL.md` package in the same catalog format as the rest of Matt Pocock's Skills. - **Inputs/outputs:** none declared as arguments or written files; it discloses its full term definitions to a sibling file, `GLOSSARY.md`, in the skill folder — an example of the "external reference" / "disclosed reference" pattern it itself describes. ## How to Use - **Trigger:** type `/writing-great-skills` when authoring or editing a skill and needing its shared vocabulary and checklist. - **Core content**, per the SKILL.md body: - **Invocation:** a **model-invoked** skill keeps a description (so the agent can fire it autonomously and other skills can reach it) at the cost of always-loaded **context load**; mechanics — omit `disable-model-invocation`, write a rich model-facing description. A **user-invoked** skill sets `disable-model-invocation: true`, has zero context load, but spends the user's **cognitive load** as the index that must remember it exists. When user-invoked skills multiply past what's memorable, a **router skill** (one user-invoked skill naming the others) cures the pile-up. - **Writing the description:** front-load the leading word; write one trigger per branch (collapse synonym duplicates); cut identity already covered in the body. - **Information hierarchy** (the ladder, ranked by immediacy of need): (1) **in-skill step** — an ordered action in `SKILL.md`, ending on a checkable, ideally exhaustive **completion criterion**; (2) **in-skill reference** — a definition/rule/fact in `SKILL.md` consulted on demand; (3) **external reference** — pushed out to a linked file (e.g. `GLOSSARY.md`) reached via a **context pointer**, loaded only when that pointer fires. **Progressive disclosure** is the move down this ladder; **co-location** keeps a concept's definition, rules, and caveats together wherever it sits. - **When to split** (**granularity**): by **invocation** — split off a model-invoked skill when a distinct leading word or cross-skill reach justifies the new always-loaded description; by **sequence** — split a run of steps when the steps still ahead tempt **premature completion**, hiding them to encourage more **legwork** on the current step. - **Pruning:** keep each meaning in a **single source of truth**; check every line for **relevance**; hunt **no-ops** sentence by sentence and delete the whole sentence rather than trim it. - **Leading words:** compact, already-pretrained concepts (e.g. _lesson_, _fog of war_, _tracer bullets_) that anchor execution in the body and invocation in the description; collapse restated qualities into one leading word (example given: "fast, deterministic, low-overhead" → _tight_; "a loop you believe in" → _red_). - **Failure modes** to diagnose: **premature completion** (fix the completion criterion first; only split as a last resort), **duplication** (same meaning in more than one place), **sediment** (stale layers from a missing pruning discipline), **sprawl** (too long even when every line is live — cure via the ladder and splitting), **no-op** (a line the model already obeys by default — the test is whether it changes behavior versus default), and **negation** (prohibition backfires; state the positive target behavior instead, keeping a hard prohibition only when it can't be phrased positively). ## Related Entities - [[entities/promoted-catalog]] — `writing-great-skills`'s row in the full 22-skill promoted inventory. - [[concepts/concepts-and-invocation]] — the model-invoked/user-invoked vocabulary this skill defines, applied catalog-wide by that concept page. - [[entities/grilling]], [[entities/grill-me]], [[entities/handoff]], [[entities/teach]] — other productivity skills in the same catalog whose invocation-class choice and step/reference structure can be read through this skill's vocabulary. # Change Log ## 2026-08-02 — Initial build Built from a hermes-kanban pipeline draft (Matt Pocock Skills wiki), conformed to the KB contract and re-grounded against a fresh gather of the mattpocock/skills repo (README, docs, and every SKILL.md). Pages carry per-page frontmatter (snapshot `2ab9580`) and folder-qualified wikilinks. ## 2026-08-02 — Production second pass The draft's single dense catalog page was split into **one entity page per promoted skill** (22 total: 17 engineering + 5 productivity), each grounded solely in that skill's own SKILL.md, with an invocation class (user- vs model-invoked) read from each SKILL.md's `disable-model-invocation` flag. Result: 13 user-invoked, 9 model-invoked. `entities/promoted-catalog` was rewritten as a lean navigation hub (two tables linking every skill). The blocking bug from the demo review (an omitted `triage` skill) remains confirmed resolved and `triage` now has its own page. **Pages (28):** 5 concepts + 23 entities (promoted-catalog hub + 22 per-skill). **Cut as ungrounded in raw/:** a package.json-vs-plugin.json version discrepancy, an MIT-license summary, and ADR-0002 reasoning — the manifest/license/ADR files are JSON or non-.md and aren't mirrored (github_docs fetches .md only). A future ingest wanting manifest-level detail should add a fetcher for those files.