# 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.