From 0d74d01cbc64ca27778a49b38599f70c534e76a0 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 1 Jul 2026 16:32:15 +0100 Subject: [PATCH] feat: add the research skill A small, model-invoked skill that spins up a background agent to investigate a question against high-trust primary sources, then leaves a single cited Markdown file wherever the repo keeps such notes. Wires it into the plugin set, both READMEs (Model-invoked), a docs page, and the ask-matt router, per the repo's promoted-skill conventions. Co-Authored-By: Claude Opus 4.8 (1M context) --- .changeset/research-skill.md | 5 +++++ .claude-plugin/plugin.json | 1 + README.md | 1 + docs/engineering/research.md | 29 ++++++++++++++++++++++++++++ skills/engineering/README.md | 1 + skills/engineering/ask-matt/SKILL.md | 1 + skills/engineering/research/SKILL.md | 12 ++++++++++++ 7 files changed, 50 insertions(+) create mode 100644 .changeset/research-skill.md create mode 100644 docs/engineering/research.md create mode 100644 skills/engineering/research/SKILL.md diff --git a/.changeset/research-skill.md b/.changeset/research-skill.md new file mode 100644 index 0000000..f88cda7 --- /dev/null +++ b/.changeset/research-skill.md @@ -0,0 +1,5 @@ +--- +"mattpocock-skills": minor +--- + +Add the **`research`** skill — a small, model-invoked skill that spins up a **background agent** to investigate a question against **primary sources** (official docs, source code, specs, first-party APIs), then leaves a single cited Markdown file wherever the repo keeps such notes. It's delegable reading legwork: you keep working while it reads, and get back a document to grill, plan, or design against. Listed in the top-level and Engineering READMEs (Model-invoked), added to `.claude-plugin/plugin.json`, given a docs page at `docs/engineering/research.md`, and routed as a Standalone in `ask-matt`. diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 9c26f64..3155eb9 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -11,6 +11,7 @@ "./skills/engineering/to-issues", "./skills/engineering/to-prd", "./skills/engineering/prototype", + "./skills/engineering/research", "./skills/engineering/domain-modeling", "./skills/engineering/codebase-design", "./skills/engineering/code-review", diff --git a/README.md b/README.md index d463026..fe6a0ec 100644 --- a/README.md +++ b/README.md @@ -161,6 +161,7 @@ Skills I use daily for code work. - **[prototype](./skills/engineering/prototype/SKILL.md)** — Build a throwaway prototype to answer a design question — a runnable terminal app for state/logic questions, or several radically different UI variations toggleable from one route. - **[diagnosing-bugs](./skills/engineering/diagnosing-bugs/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test. +- **[research](./skills/engineering/research/SKILL.md)** — Investigate a question against high-trust primary sources and capture the findings as a cited Markdown file in the repo, run as a background agent. - **[tdd](./skills/engineering/tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. - **[domain-modeling](./skills/engineering/domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms against the glossary, stress-test with edge-case scenarios, and update `CONTEXT.md` and ADRs inline. - **[codebase-design](./skills/engineering/codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. diff --git a/docs/engineering/research.md b/docs/engineering/research.md new file mode 100644 index 0000000..308765c --- /dev/null +++ b/docs/engineering/research.md @@ -0,0 +1,29 @@ +Quickstart: + +```bash +npx skills add mattpocock/skills --skill=research +``` + +```bash +npx skills update research +``` + +[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/research) + +## What it does + +`research` answers a question by reading the sources that own the answer and leaving a cited Markdown file behind. It works only from **primary sources** — official docs, source code, specs, first-party APIs — never a secondary write-up of them, so what it saves is traceable back to something authoritative rather than a summary of a summary. + +## When to reach for it + +Type `/research`, or the agent reaches for it automatically when a task turns into reading legwork. + +Reach for it when the next step is *finding something out* — how an API behaves, what a spec actually says, whether a claim holds — and you'd rather not stall your own thread doing the reading. For sharpening a plan by interview instead of by reading, use [grilling](https://aihero.dev/skills-grilling); for exploring what to build with throwaway code, use [prototype](https://aihero.dev/skills-prototype). + +## Delegated legwork + +The defining move is that the reading runs as a **background agent**. You keep working; it goes off, follows each claim back to its primary source, and drops a single cited Markdown file into wherever the repo keeps such notes. Research is legwork you delegate, not thinking you outsource — you get back a document to react to, with its sources attached. + +## Where it fits + +A reach-for-it-anytime standalone that feeds the thinking skills: the file it produces is something to grill, plan, or design against, so it sits upstream of work like [grilling](https://aihero.dev/skills-grilling) and [to-prd](https://aihero.dev/skills-to-prd) rather than in the build chain. For the whole map, see [ask-matt](https://aihero.dev/skills-ask-matt). diff --git a/skills/engineering/README.md b/skills/engineering/README.md index dd4e218..2c123f4 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -21,6 +21,7 @@ Model- or user-reachable (rich trigger phrasing so the model can reach for them) - **[prototype](./prototype/SKILL.md)** — Build a throwaway prototype to answer a design question: a runnable terminal app for state/logic, or several toggleable UI variations. - **[diagnosing-bugs](./diagnosing-bugs/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test. +- **[research](./research/SKILL.md)** — Investigate a question against high-trust primary sources and capture the findings as a cited Markdown file in the repo, run as a background agent. - **[tdd](./tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. - **[domain-modeling](./domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms, stress-test with scenarios, update `CONTEXT.md` and ADRs inline. - **[codebase-design](./codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: small interfaces, clean seams, testable through the interface. diff --git a/skills/engineering/ask-matt/SKILL.md b/skills/engineering/ask-matt/SKILL.md index 84a0105..f19a17c 100644 --- a/skills/engineering/ask-matt/SKILL.md +++ b/skills/engineering/ask-matt/SKILL.md @@ -65,6 +65,7 @@ Off the main flow entirely. - **`/grill-me`** — the same relentless interview as `/grill-with-docs`, but for when you have **no codebase**. Stateless: it saves nothing locally, builds no `CONTEXT.md`. Reach for it to sharpen any plan or design that doesn't live in a repo. - **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway from day one — keep the answer, delete the code. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper. +- **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it. - **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace. - **`/writing-great-skills`** — reference for writing and editing skills well. diff --git a/skills/engineering/research/SKILL.md b/skills/engineering/research/SKILL.md new file mode 100644 index 0000000..0ba594a --- /dev/null +++ b/skills/engineering/research/SKILL.md @@ -0,0 +1,12 @@ +--- +name: research +description: Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent. +--- + +Spin up a **background agent** to do the research, so you keep working while it reads. + +Its job: + +1. Investigate the question against **primary sources** — official docs, source code, specs, first-party APIs — not a secondary write-up of them. Follow 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 where the repo already keeps such notes; match the existing convention, and if there is none, put it somewhere sensible and say where.