matt-skills-on-openspec
Skill25 starsChanged 23 days agoMITView on GitHub
Wire Matt Pocock's engineering skills onto a repo whose work items are OpenSpec changes — which skill maps to which change artifact or /opsx command, and which need no wiring at all. Use when installing or running to-spec, to-tickets, triage, wayfinder, implement, research, domain-modeling, or code-review in an OpenSpec repo.
In this repository10 other files it gives its agents.
- afkSkill
- capability-pruningSkill
- concurrent-worktreesSkill
- e2e-first-testingSkill
- llm-agent-surfaceSkill
- minimal-design-gateSkill
- progressSkill
- repo-audit-loopSkill
- site-annotated-gatesSkill
- structural-fixSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Only setup-matt-pocock-skills is a prerequisite.
- Very specific: line 20
Run /setup-matt-pocock-skills once.
- Very specific: line 22
Issue tracker → "Other": Not GitHub, not local markdown.
- Very specific: line 30
Use it when the destination is too big for one session and not yet knowable.
- Very specific: line 39
When the map empties, run /to-spec to converge the decisions into proposal.md and specs/.
- Distinctive: line 71
Keep the method intact: OpenSpec says nothing about how to slice, so the tracer-bullet discipline is the whole reason to run this skill.
- Distinctive: line 91
If the finding is a trade-off that shouldn't be casually reversed, that's an ADR, and the note becomes its evidence attachment.
- Distinctive: line 95
Keep the boundaries sharp, because all three describe the project and it's tempting to merge them:
- Distinctive: line 107
Keep the reviewing agent read-only.
- Distinctive: line 125
Is the pointer resident?: Only checkable in a session that started *after* you wrote it — context is fixed at session start.
- Very specific: line 126
Does an invocation land correctly?: Run /to-spec or /to-tickets for real and look at where the output went: openspec/changes/ means it …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Matt Skills on OpenSpec
The engineering skills carry a method — how to slice work, how to advance through fog. OpenSpec is the carrier — where the result lives as proposal.md, a spec delta, tasks.md, and an archive entry. Keep the method; redirect its output onto the carrier.
Only setup-matt-pocock-skills is a prerequisite. Every other skill is an optional install, so each section below applies only if you have that skill — skip the rest.
First, the gate: does this need a change?
OpenSpec is for work that alters the meaning of a SHALL/MUST clause. A typo, a pure refactor, a bug fix that leaves every clause intact — do it and commit it, no change.
This gate runs before any skill's output reaches the carrier. A skill handing you a plan does not oblige you to open a change for it.
Setup
Run /setup-matt-pocock-skills once. Two answers matter:
Issue tracker → "Other". Not GitHub, not local markdown. Describe the OpenSpec workflow: work items are openspec/changes/<kebab-name>/, opened with /opsx:propose, closed with /opsx:archive; the issue body is proposal.md, the spec is specs/<capability>/spec.md, the checklist is tasks.md; state comes from openspec status --change "<name>" --json, never from a Status: line.
Domain docs → single-context, plus one thing the template doesn't know about. Besides CONTEXT.md and docs/adr/, the repo has openspec/specs/ — the live capability specs. Write that into docs/agents/domain.md, or skills will explore the codebase without reading the specs that govern what they're about to change.
Setup then writes an ## Agent skills block into CLAUDE.md or AGENTS.md, whichever exists, CLAUDE.md winning. Confirm it landed in the file your harness loads at session start. If it wrote AGENTS.md and the harness only loads CLAUDE.md, no skill ever sees the pointer — and each falls back to its own default, which for /wayfinder is explicitly local markdown, bypassing OpenSpec entirely. A CLAUDE.md containing @AGENTS.md fixes it.
/wayfinder — the stage before a change has a shape
Use it when the destination is too big for one session and not yet knowable. /opsx:propose assumes you already know what to build; wayfinder is what runs before that.
One effort is one change. Put the map and its decision tickets in openspec/changes/<effort>/wayfinding/ — deliberately clear of the artifact names OpenSpec generates (proposal, design, tasks, specs), so /opsx:* and wayfinder don't overwrite each other.
- Map →
wayfinding/map.md, holding Destination / Notes / Decisions-so-far / Not yet specified / Out of scope.proposal.mdcarries only a destination summary and a link. - Tickets →
wayfinding/NN-<slug>.mdfrom01, withType:andStatus:lines at the top. - Blocking → a
Blocked by: NN, NNline; unblocked when every listed file is resolved. - Frontier → the unresolved, unclaimed, unblocked files, lowest number first.
When the map empties, run /to-spec to converge the decisions into proposal.md and specs/. wayfinding/ archives with the change as decision provenance.
/to-spec — split the template across three artifacts
OpenSpec already decomposes a spec, so don't paste the whole to-spec template into proposal.md:
| to-spec section | goes to |
| Problem Statement / Solution / Out of Scope | proposal.md |
| User Stories | specs/<capability>/spec.md, rewritten as SHALL/MUST clauses |
| Implementation Decisions / Testing Decisions | design.md |
| Further Notes | into whichever of the three fits |
User stories are requirements in spoken form; spec clauses are requirements in checkable form. One story often becomes several clauses — don't force a one-to-one transcription.
The skill ends by telling you to apply a ready-for-agent label. See /triage below: usually you skip it.
/to-tickets — N tickets become N tasks, not N changes
Tickets land as entries in one change's tasks.md. Only split into a separate change when the scope is genuinely independent and archivable on its own.
tasks.md is a flat checklist with no native blocking, so use its numbering:
## 2. Core predicate
- [ ] 2.1 <task>
- [ ] 2.3 <task> (blocked by 1.2, 2.1)Section order should already be dependency order, so most tasks need no annotation — mark only genuine cross-section dependencies.
Keep the method intact: OpenSpec says nothing about how to slice, so the tracer-bullet discipline is the whole reason to run this skill. Vertical slices, each independently verifiable. The wide-refactor exception applies unchanged — expand as its own section, migrate in blast-radius batches, contract last.
Its closing line says to work the frontier with /implement. Use /opsx:apply instead.
/implement — superseded by /opsx:apply
Installed or not, you won't use it here. Its content — use TDD, typecheck, run tests, review, commit — is what /opsx:apply plus the repo's own gates and commit discipline already do, and /opsx:apply additionally drives tasks.md checkbox by checkbox. Running both gives you two implementation entry points for one checklist.
/triage — usually nothing to do
Changes have no labels. The five canonical roles live as a triage: key in openspec/changes/<name>/.openspec.yaml, alongside category:. Both are custom keys; openspec validate and openspec status --json accept them and don't interpret them.
But a change opened by /opsx:propose is a ticket you wrote yourself — spec finalised means ready to implement, with no assessment stage in between. Most changes carry no triage: key, and that is the expected state, not an oversight. Only two cases earn one: a raw problem nobody has decided on yet, and anything explicitly ready-for-human (needs a person, hardware, or an external dependency, so no unattended agent should grab it).
Archiving is closing — archived changes leave the triage queue. Query by file scan: grep -l 'triage: ready-for-agent' openspec/changes/*/.openspec.yaml.
/research — notes are not work items
Research notes go wherever the repo already keeps documentation, not into a change directory — they aren't work items and they don't archive on a change's schedule. Reference the note's path from the change.
If the finding is a trade-off that shouldn't be casually reversed, that's an ADR, and the note becomes its evidence attachment.
/domain-modeling — three sources, three questions
Keep the boundaries sharp, because all three describe the project and it's tempting to merge them:
CONTEXT.md— what a term meansdocs/adr/— why it's locked this way, and at what cost; deliberately not casually reversibleopenspec/specs/— what the contract currently is; amended by the next change as a matter of course
New terms and new decisions land in the first two. Don't write them into a spec delta, and don't copy spec clauses into an ADR.
/code-review — the Spec axis finally has a spec
Most repos give this skill nothing concrete for its Spec axis. Here, review against this change's specs/ delta and proposal.md, not a vague sense of the requirement.
Keep the reviewing agent read-only. Given write tools it will fix things it noticed in passing, and report that it changed nothing.
/prototype — throwaway, except the decision
Prototypes don't live in the change directory. When one produces a snippet that pins a decision more precisely than prose can — a state machine, a schema, a type shape — inline the decision-bearing part into design.md and note it came from a prototype.
/diagnosing-bugs — usually ends without a change
Most diagnoses end in a fix, and a fix that leaves every clause intact doesn't get a change (see the gate above). Propose one only when the repair changes what a SHALL/MUST means.
Skills needing no wiring
/grilling, /tdd, /codebase-design, /improve-codebase-architecture, /resolving-merge-conflicts, /handoff, /teach, /find-skills, /writing-great-skills produce no work items and never touch the tracker. Install and use them as-is.
Proving the wiring conducts
Configuration written is not behaviour changed.
- Is the pointer resident? Only checkable in a session that started after you wrote it — context is fixed at session start.
- Does an invocation land correctly? Run
/to-specor/to-ticketsfor real and look at where the output went:openspec/changes/means it conducts,.scratch/means it never saw the pointer. This is the only check that proves the whole chain.
These skills are external and get updated while your adapter file is hand-written, with nothing verifying they still agree. A renamed command or restructured template leaves the adapter pointing somewhere plausible — silently.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

