mattpocock-skills-opencode/docs/skill-mapping.md

Skill mapping — mattpocock/skills → OpenCode v2

Upstream: mattpocock/skills@49dd158 (v1.3.1, 2026-10-09). Analyzed 2026-10-14. Machine-readable source of truth: .opencode/state/classification.json (this doc will be generated from it once scripts/generate.ts exists — until then keep both in sync by hand).

Validation status legend: pending = not yet runtime-verified (Phase 1.9); validated = loads and behaves correctly in a real OpenCode v2 session.

Summary

Classification	Count	Skills
skill	27	all vendored verbatim; see matrix
agent+skill	1	code-review (+ pocock-reviewer subagent)
orchestrator	2	implement-spec (→ pocock + pocock-worker), chief-of-staff (excluded, in-progress)
plugin	1	git-guardrails-claude-code (→ opt-in guardrails hook)
not-convertible	1	claude-handoff (Claude-CLI-bound, excluded)
agent (dedicated, no skill)	0	research evaluated → rejected as dedicated agent (D8)

Vendored: 31 skills (engineering 20, productivity 7, misc 4). Excluded: 7 in-progress + deprecated bucket (empty upstream). 23 of 31 vendored skills are user-invoked upstream (disable-model-invocation: true) → manifest sets autoinvoke: false; OpenCode v2 honors this natively (hidden from model auto-selection, still loadable via /name or explicit id).

Generated agents

Agent	Mode	Purpose	Key permissions
pocock	primary	Orchestrator: routes via ask-matt, walks grill→spec→tickets→build→review→retro, gates user-invoked skills behind explicit proposals, runs the implement-spec dispatch loop (integration branch, one worktree per ticket, frontier from own merge record, merges, cleanup)	edit/shell allow; destructive-git denies on main checkout; skill * allow; task allow
pocock-worker	subagent	Builds one ticket test-first (tdd at the spec's seams) inside its prepared worktree; merges integration tip; reports; never pushes/PRs/stashes/worktrees; asks nothing	skill deny * + allow-list (tdd, codebase-design, diagnosing-bugs + stack skills); shell denies push/stash/reset --hard/clean/worktree/switch, gh pr/issue-close; edit allow
pocock-reviewer	subagent	Read-only executor of one code-review axis (Standards or Spec) with the skill's fully-specified prompt; findings returned to the caller for verbatim aggregation	edit deny; shell allow git-read only; skill allow code-review only

Rejected agents (recorded so they are not re-proposed without new evidence): pocock-researcher (D8 — built-in general + the 12-line research brief is equivalent), per-phase agents (spec-writer/ticket-planner/debugger/... — Matt's phases are conversation steps sharing one context, not roles; splitting them shreds the grilling→spec context the methodology depends on), triage agent (every step waits on the maintainer), teach/tutor agent (continuous human dialogue).

Matrix

DMI = disable-model-invocation: true upstream (user-invoked). All vendored skills ship verbatim (D1); "Artifacts" lists everything generated for the skill. Status analyzed = classification reviewed by a human; needs-review = new upstream skill, drift test fails until reviewed. Runtime validation of every artifact is tracked in .opencode/state/status.md (all pending until Phase 1.9).

Upstream skill	Bucket	DMI	Classification	Artifacts	Depends on	Status	Rationale
ask-matt	eng	✓	skill	skill:verbatim		analyzed	Pure router prose over all skills; no execution or isolation. Its routing logic also informs the pocock agent's system prompt.
code-review	eng		agent+skill	skill:verbatim, agent:pocock-reviewer		analyzed	Skill stays verbatim (aggregation protocol), but its core mechanic is two parallel isolated axis reviewers with large self-contained prompts -> dedicated read-only pocock-reviewer subagent hosts each axis. Caller (pocock or user) aggregates per the skill.
codebase-design	eng		skill	skill:verbatim		analyzed	Canonical shared-vocabulary reference consumed by tdd/improve-arch/setup-ts-deep-modules; DESIGN-IT-TWICE parallel subagents run via task tool from the loading agent.
diagnosing-bugs	eng		skill	skill:verbatim		analyzed	Six-phase procedural discipline run inline; no isolation or special permissions needed.
domain-modeling	eng		skill	skill:verbatim		analyzed	Interactive writing discipline + bundled format files (GLOSSARY/ADR); must run in the main conversation to challenge user wording - an isolated agent would break it.
grill-with-docs	eng	✓	skill	skill:verbatim	grilling, domain-modeling	analyzed	7-line composition wrapper; OpenCode skill tool loads the two named skills. Preserve verbatim; orchestrator verifies both load (known upstream wrapper failure mode).
implement	eng	✓	skill	skill:verbatim	tdd, code-review	analyzed	Thin single-context per-ticket procedure composing tdd + code-review; the pocock-worker agent embodies its discipline for parallel builds.
implement-spec	eng	✓	orchestrator	skill:verbatim, agent:pocock, agent:pocock-worker	tdd, code-review	analyzed	The repo's clearest orchestrator: task-graph frontier, background implementers in git worktrees, merger, fixer. OpenCode's task tool provides no worktrees, so the pocock agent supplies worktree creation, frontier scheduling from its own merge record, and merges; skill text stays verbatim.
improve-codebase-architecture	eng	✓	skill	skill:verbatim	codebase-design, grilling, domain-modeling	analyzed	Interactive survey-and-grill; its exploration/design-it-twice subagents are internal delegation via task tool, not its identity.
pr	eng		skill	skill:verbatim		analyzed	Pure PR-body template/reference. Verbatim vendoring preserves required attribution (metadata.credits + CREDITS.md, Dex Horthy's show-me).
prototype	eng		skill	skill:verbatim		analyzed	Generation procedure with two branch docs (LOGIC/UI); user reacts to artifacts in main conversation.
research	eng		skill	skill:verbatim		analyzed	The 12-line skill IS a background-agent brief; OpenCode's built-in general subagent + background:true executes it as written. Dedicated pocock-researcher agent evaluated and REJECTED (D8): the brief is self-contained, a branded agent adds drift risk and no capability.
retro	eng	✓	skill	skill:verbatim	writing-for-agents	analyzed	Analysis over the current session's history - isolating it in a subagent would starve it of the session context it mines.
setup-matt-pocock-skills	eng	✓	skill	skill:verbatim		analyzed	Interactive per-repo scaffolding + seed assets; it creates the docs/agents/* state that to-spec/to-tickets/triage/implement/implement-spec/code-review/wayfinder hard-depend on. Keep verbatim; README flags it as required first run.
tdd	eng		skill	skill:verbatim	codebase-design	analyzed	The reusable build discipline; consumed by implement and every pocock-worker via skill allow-list.
to-spec	eng	✓	skill	skill:verbatim		analyzed	Synthesis + template + publish procedure; explicitly no interview, needs main-conversation context (grilling output).
to-tickets	eng	✓	skill	skill:verbatim		analyzed	Decomposition with human approval loop; needs the spec conversation in context.
triage	eng	✓	skill	skill:verbatim	grilling, domain-modeling	analyzed	Maintainer-driven interactive state machine; heavy human-in-the-loop design fits a skill. A dedicated triage agent was considered and rejected: every step waits on the maintainer.
wayfinder	eng	✓	skill	skill:verbatim	grilling, domain-modeling, research, prototype	analyzed	Stateful planning protocol over the tracker (map/fog/frontier); its research dispatches use the research skill + built-in subagents.
wizard	eng		skill	skill:verbatim		analyzed	Code generator with bundled template.sh asset; the generated artifact is a human-run script, no harness integration needed.
grill-me	prod	✓	skill	skill:verbatim	grilling	analyzed	7-line stateless wrapper around grilling.
grilling	prod		skill	skill:verbatim		analyzed	The interview primitive the whole methodology builds on; 100% human interaction in the main conversation - converting to an agent would make it worse (isolated context can't grill the user). Fact-finding subagents dispatch via task tool.
handoff	prod	✓	skill	skill:verbatim		analyzed	Document-generation instructions writing to OS temp dir.
teach	prod	✓	skill	skill:verbatim		analyzed	Stateful multi-session tutor with bundled format files; workspace state lives in files, so no agent isolation needed. A tutor agent was considered and rejected: continuous human dialogue belongs in the primary conversation.
to-questionnaire	prod	✓	skill	skill:verbatim		analyzed	Two structured interviews + document template.
wait-what	prod	✓	skill	skill:verbatim		analyzed	7-line corrective re-pitch instruction, usable mid-any-skill.
writing-for-agents	prod		skill	skill:verbatim		analyzed	Pure theory reference; the most instructions-only skill in the repo.
git-guardrails-claude-code	misc		plugin	skill:verbatim, plugin:guardrails		analyzed	Only skill needing executable integration: a Claude Code PreToolUse hook. OpenCode equivalent = opt-in ctx.tool.hook('execute.before') on shell inside our plugin (D7), default off, porting the bundled block-dangerous-git.sh pattern list. Skill text stays vendored verbatim for reference/fidelity.
migrate-to-shoehorn	misc		skill	skill:verbatim		analyzed	Mechanical codemod recipe. Frozen misc bucket - vendored as-is.
scaffold-exercises	misc		skill	skill:verbatim		analyzed	Environment-bound: hard-depends on Matt's private ai-hero-cli, only works in his course repos. Vendored verbatim with caveat noted in mapping doc; no OpenCode artifact can fix an external private tool.
setup-pre-commit	misc		skill	skill:verbatim		analyzed	Setup recipe, npm ecosystem only. Frozen misc bucket - vendored as-is.
chief-of-staff	in-prog	✓	orchestrator	excluded		analyzed	EXCLUDED per D6 (in-progress beta). Would map to a coordinator persona over background subagents; revisit only if upstream promotes it.
claude-handoff	in-prog	✓	not-convertible	excluded	handoff	analyzed	EXCLUDED per D6 + harness-bound: hard-depends on Claude CLI --bg/agents launcher. OpenCode analogue would need its own background-session mechanism; handoff skill covers the portable half.
loop-me	in-prog	✓	skill	excluded	grilling	analyzed	EXCLUDED per D6 (in-progress). Grilling + workflows/*.md workspace convention; converts trivially if promoted.
setup-ts-deep-modules	in-prog	✓	skill	excluded	codebase-design	analyzed	EXCLUDED per D6 (in-progress). Dependency-cruiser setup with bundled config + prove-it-bites self-check; converts cleanly if promoted.
writing-beats	in-prog	✓	skill	excluded	writing-fragments	analyzed	EXCLUDED per D6 (in-progress).
writing-fragments	in-prog	✓	skill	excluded	grilling	analyzed	EXCLUDED per D6 (in-progress).
writing-shape	in-prog	✓	skill	excluded	writing-fragments	analyzed	EXCLUDED per D6 (in-progress).

Cross-cutting notes for the conversion

• Hard dependency chain: setup-matt-pocock-skills writes docs/agents/{issue-tracker,domain, triage-labels}.md + the ## Agent skills block; to-spec, to-tickets, triage, implement, implement-spec, code-review, wayfinder all break without it. README + pocock agent must flag it.
• Wrapper semantics: grill-me/grill-with-docs/wait-what are 7-line compositions relying on cross-skill invocation ("Call the Skill tool with X"). OpenCode's skill tool loads by name — the loading agent must load both named skills itself (upstream docs report wrappers failing to chain; pocock agent verifies).
• Invariant: user-invoked skills are never callable from other skills upstream; V2's autoinvoke: false reproduces exactly this (hidden from model, loadable by human via slash).
• Frontmatter census: only name, description, disable-model-invocation, argument-hint (4 skills), metadata.credits (pr) exist upstream — no allowed-tools/model/context fields, so all permission/isolation design is ours (authored fresh in agent templates, not translated).
• agents/openai.yaml in every skill dir is Codex UI metadata (display_name, short_description, policy mirroring DMI) — stripped from the generated OpenCode tree by the generator.
• 17 pending upstream changesets (patch) target code-review, to-tickets, wayfinder, wizard, tdd, teach, implement, grilling, handoff, diagnosing-bugs, ask-matt, setup — the next upstream release will touch ~1/3 of the vendored skills; the nightly sync + drift tests are the safety net.
• scaffold-exercises only works in Matt's course repos (private ai-hero-cli); vendored for fidelity, documented as environment-bound.