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); "extra artifact" lists anything generated on top. Validation: all pending until Phase 1.9.

Upstream skill	Bucket	DMI	Classification	Extra artifact	Depends on (skill-tool)	Rationale (abridged; full text in classification.json)
ask-matt	eng	✓	skill	informs pocock system	—	pure router prose; must stay in sync upstream, vendored as-is
code-review	eng		agent+skill	pocock-reviewer	—	two parallel isolated axis reviewers = dedicated read-only subagent; aggregation stays in caller
codebase-design	eng		skill	—	—	shared-vocabulary reference consumed by tdd et al.
diagnosing-bugs	eng		skill	—	—	six-phase inline discipline, no isolation needed
domain-modeling	eng		skill	—	—	dialogue discipline writing GLOSSARY/ADRs; isolation would break it
grill-with-docs	eng	✓	skill	—	grilling, domain-modeling	7-line wrapper; orchestrator verifies both loads (known upstream failure mode)
implement	eng	✓	skill	embodied by pocock-worker	tdd, code-review	thin single-context per-ticket procedure
implement-spec	eng	✓	orchestrator	pocock, pocock-worker	tdd, code-review	frontier + worktree fleet; OpenCode task tool lacks worktrees → agents supply them
improve-codebase-architecture	eng	✓	skill	—	codebase-design, grilling, domain-modeling	interactive survey-and-grill; subagents are internal delegation
pr	eng		skill	—	—	PR-body template; verbatim vendoring preserves Dex Horthy attribution (metadata.credits, CREDITS.md)
prototype	eng		skill	—	—	throwaway-artifact generation procedure
research	eng		skill	—	—	the skill IS a background-agent brief; built-in general executes it (dedicated agent rejected, D8)
retro	eng	✓	skill	—	writing-for-agents	mines the current session — must not be isolated
setup-matt-pocock-skills	eng	✓	skill	—	—	creates docs/agents/* state that 7 skills hard-depend on; required first run per repo
tdd	eng		skill	—	codebase-design	the build discipline; worker allow-list core
to-spec	eng	✓	skill	—	—	synthesis from conversation, no interview
to-tickets	eng	✓	skill	—	—	decomposition + human approval loop
triage	eng	✓	skill	—	grilling, domain-modeling	maintainer-driven state machine; agent rejected (HITL at every step)
wayfinder	eng	✓	skill	—	grilling, domain-modeling, research, prototype	tracker-based map/fog/frontier protocol
wizard	eng		skill	—	—	bash-wizard generator; bundled template.sh ships with the skill dir
grill-me	prod	✓	skill	—	grilling	7-line stateless wrapper
grilling	prod		skill	—	—	the interview primitive; isolation would make it worse
handoff	prod	✓	skill	—	—	handoff doc to OS temp dir
teach	prod	✓	skill	—	—	stateful tutor; state lives in workspace files
to-questionnaire	prod	✓	skill	—	—	interviews + questionnaire template
wait-what	prod	✓	skill	—	—	7-line re-pitch corrective
writing-for-agents	prod		skill	—	—	pure theory reference
git-guardrails-claude-code	misc		plugin	guardrails hook (opt-in)	—	Claude PreToolUse hook → OpenCode ctx.tool.hook on shell; skill text kept verbatim for reference
migrate-to-shoehorn	misc		skill	—	—	codemod recipe (frozen bucket)
scaffold-exercises	misc		skill	—	—	environment-bound: needs Matt's private ai-hero-cli; caveat documented, no fix possible
setup-pre-commit	misc		skill	—	—	husky/lint-staged recipe (frozen bucket)
chief-of-staff	in-prog	✓	orchestrator	excluded (D6)	—	coordinator persona; revisit if upstream promotes
claude-handoff	in-prog	✓	not-convertible	excluded (D6)	handoff	Claude-CLI --bg launcher; harness-bound
loop-me	in-prog	✓	skill	excluded (D6)	grilling	workflow-spec grilling workspace
setup-ts-deep-modules	in-prog	✓	skill	excluded (D6)	codebase-design	dependency-cruiser enforcement setup
writing-beats	in-prog	✓	skill	excluded (D6)	writing-fragments	beat-by-beat exploit writing
writing-fragments	in-prog	✓	skill	excluded (D6)	grilling	explore-phase fragment mining
writing-shape	in-prog	✓	skill	excluded (D6)	writing-fragments	paragraph-level shaping

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.