Skills Organization 2026 — opencode_initializer¶

Status: Architecture reference (living document) Scope: How the skills in opencode_initializer are categorized, mapped to the AIPDLC control structure, composed into pipelines, tuned for cost/latency, secured, and evolved over time. Canonical version: v15.0.0 Companion docs: LLM Fundamentals 2026, AIPDLC Integration Guide, Agent Role Definitions 2026, Security Model 2026

This document is the skills map: it answers "which skill runs at which point in the lifecycle, under which role, with which model, and within which security boundary." It follows the same honesty convention as the security model:

• [SKILL] — a real .opencode/skills/**/SKILL.md (or ~/.config/opencode/skills/**) protocol that an agent loads.
• [MODULE] — a numbered src/lib/*.sh (or scripts/*) shell/Go/Python artifact — not a skill, but a skill calls it or is governed by it.
• [DOC] — a reference document or registry that a skill reads as ground truth.

This distinction matters throughout: several things a user might think of as "security skills" (governance, audit, PII) are actually modules (43/44/45), while the skills are the protocol layer that dispatches work toward those modules.

0. Skill Inventory at a Glance¶

Skills live in three tiers. Tier 1 is project-local (the AIPDLC protocol spine); Tier 2 is the matt-pocock workflow toolkit; Tier 3 is the globally-installed superpowers/disruptor set.

The canonical (project-owned) set is Tier 1 + the matt-pocock subset that Tier 1 skills invoke by name. The full name→location map is in the Appendix.

1. Skill Categories¶

Skills are grouped by the phase of work they serve, not by their file location. Five functional categories, plus a sixth "meta" category for skills that orchestrate the other five.

flowchart TD
    subgraph DEV["Development Skills"]
        direction TB
        DEV1[brainstorm]:::d
        DEV2[plan]:::d
        DEV3[specify]:::d
        DEV4[implement]:::d
        DEV5[tdd]:::d
        DEV6[code-review]:::d
    end
    subgraph ARCH["Architecture Skills"]
        direction TB
        ARC1[design-docs]:::a
        ARC2[deep-dive]:::a
        ARC3[codebase-review-swarm]:::a
        ARC4[codebase-design]:::a
        ARC5[domain-modeling]:::a
    end
    subgraph OPS["Operations Skills"]
        direction TB
        OPS1[running-tests]:::o
        OPS2[writing-tests]:::o
        OPS3[commit-pr]:::o
        OPS4[phase-wrap]:::o
        OPS5[resume]:::o
    end
    subgraph RES["Research Skills"]
        direction TB
        RES1[deep-research]:::r
        RES2[discover]:::r
        RES3[consult]:::r
        RES4[research]:::r
    end
    subgraph SEC["Security / Governance"]
        direction TB
        SEC1[code-review-swarm]:::s
        SEC2[engineering-conventions]:::s
        SEC3[governance MODULE]:::s
        SEC4[audit MODULE]:::s
    end
    subgraph META["Meta / Orchestration"]
        direction TB
        MET1[loop]:::m
        MET2[council]:::m
        MET3[critic-gate]:::m
        MET4[coprocessor]:::m
        MET5[pre-phase-briefing]:::m
    end

    META --> DEV
    META --> ARCH
    META --> OPS
    META --> RES
    META --> SEC

    classDef d fill:#e3f2fd,stroke:#1565c0
    classDef a fill:#f3e5f5,stroke:#6a1b9a
    classDef o fill:#e8f5e9,stroke:#2e7d32
    classDef r fill:#fff3e0,stroke:#ef6c00
    classDef s fill:#ffebee,stroke:#c62828
    classDef m fill:#eceff1,stroke:#455a64

1.1 Development Skills¶

The write path — turn an intent into merged code.

1.2 Architecture Skills¶

The design / understanding path — structure a system or audit an existing one.

1.3 Operations Skills¶

The verify / ship / continue path — keep work correct and durable.

1.4 Research Skills¶

The read / learn path — gather bounded evidence from code or the world.

1.5 Security / Governance Skills¶

Honesty note: the security concepts the LLM-architecture material names — security-model, governance, audit — are not skills. security-model-2026.md is a [DOC]; 43-governance.sh, 44-audit.sh, 45-pii-guard.sh, 46-offline-bundle.sh, 47-lynis.sh, 48-auditd.sh are [MODULE]s. The skills that engage security are:

The modules enforce what these skills promise: 45-pii-guard.sh redacts before any LLM request, 44-audit.sh hash-chains every tool call, 43-governance.sh allow/denies providers. See §5.

1.6 Meta / Orchestration Skills¶

Skills that coordinate the other skills — the AIPDLC "loop state" layer.

2. Skill Mapping to AIPDLC¶

AIPDLC (aipdlc-integration-guide.md) defines seven pillars: control plane, agent roles, isolation, MCP, security, team topologies, unit economics. Skills are the behavioral surface of each pillar — the pillar's modules provide the deterministic enforcement, and the skill provides the model the deterministic layer supervises.

2.1 Control-Plane Skills¶

The control plane "decides what gets executed, by whom, with what model, in what sandbox." Skills do not implement the control plane — they are supervised by it.

Principle (from the v3 ADR, quoted in llm-fundamentals-2026.md §4.1): the Control Plane is deterministic code, not an LLM. Models propose; the plane disposes. A skill never owns the progress file or writes the WAL directly — it goes through _run_step / _step_done / _wal_locked_append.

2.2 Agent-Role Skills¶

Each AIPDLC role is bound to a skill at dispatch by 54-task-distributor.sh (the SSOT). The skill narrows the role's allowed behavior (§2.3 in agent-roles-2026.md).

The role→skill binding is priority-ordered and deterministic:

complex      ⇒ Commander  (skill: loop)
research     ⇒ Planner    (skill: deep-research)
planning     ⇒ Planner    (skill: plan)
review       ⇒ Reviewer   (skill: code-review)
otherwise    ⇒ Worker     (skill: implement | tdd | diagnosing-bugs …)

2.3 Isolation Skills¶

Isolation in AIPDLC is environment, not behavior. Skills do not implement isolation; they declare the isolation tier they require, and the deterministic layer provides it.

The Isolated Circuit (32-isolated.sh) is the canonical no-network mode: when ISOLATED_CIRCUIT=true, a skill like deep-research that depends on external fetch must degrade to local-only sources or fail fast. There is no skill for isolation — there is an environment, and skills are compatible or not with it.

2.4 MCP-Integration Skills¶

MCP is the tool surface skills consume. Skills do not configure MCP; they consume the tool set that 52-context-selector.sh attaches for their task profile.

Context-cost rule (from llm-fundamentals-2026.md §4.4): every enabled MCP server injects its tool schema into the system prompt — real prefill tokens. disabled_by_default (chrome-devtools, playwright, excalidraw, agent-browser) keeps heavy tool surfaces off by default; a skill must earn them via its task profile.

2.5 Security Skills¶

The security pillar is the one place where the mapping is module-first, skill-second. The table maps each AST10 threat to (a) the enforcing module and (b) the skill that respects it.

3. Skill Composition¶

Skills are not run in isolation; they are composed into pipelines by the meta skills and the task distributor.

3.1 How Skills Work Together — the Lifecycle Pipeline¶

The canonical pipeline is the four-stage DAG (research → plan → implement → verify) that 54-task-distributor.sh emits per complexity tier, with a skill attached to each stage:

flowchart LR
    subgraph SPECIFY
        B[brainstorm] --> C[clarify] --> S[specify]
    end
    subgraph PLAN
        R1[deep-research] --> P[plan]
    end
    subgraph IMPLEMENT
        I[implement] --> T[tdd] --> WT[writing-tests]
    end
    subgraph VERIFY
        CR[code-review] --> RT[running-tests]
    end
    subgraph SHIP
        PR[commit-pr] --> PW[phase-wrap]
    end

    S --> R1
    P --> I
    T --> CR
    RT --> PR

    classDef s fill:#e3f2fd,stroke:#1565c0
    classDef p fill:#fff3e0,stroke:#ef6c00
    classDef i fill:#e8f5e9,stroke:#2e7d32
    classDef v fill:#f3e5f5,stroke:#6a1b9a
    classDef h fill:#ffebee,stroke:#c62828
    class B,C,S s
    class R1,P p
    class I,T,WT i
    class CR,RT v
    class PR,PW h

Complexity tiers trim this pipeline (from routing.json / 54-task-distributor.sh):

simple  → [ implement:Worker ]
medium  → [ research:Planner ] → [ implement:Worker ]
complex → [ research:Planner ] → [ plan:Planner ] → [ implement:Worker ] → [ verify:Reviewer ]

3.2 Skill Dependencies¶

Skills form an acyclic dependency graph. Load-order and fan-out edges:

Hard rule (from agent-roles-2026.md §1.5): delegation is acyclic. A skill may fan out down the role ladder, never up. Worker-bound skills (implement, tdd) are leaves; they never re-plan or self-approve.

3.3 Skill Orchestration¶

Orchestration is who decides which skill runs next:

Parallel fan-out is driven by dispatching-parallel-agents (T3) + 54-task-distributor.sh parallel, gated by disjoint-scope preflight (plan_conflict_check). Skills in a wave are file-disjoint; the Commander enforces wave ordering.

3.4 Skill Fallbacks¶

When a skill's primary path fails, the fallback is structural, not ad-hoc:

4. Skill Performance¶

Skill performance is the AIPDLC unit-economics pillar applied per-skill: each skill has a token budget, a model profile, and a context footprint.

4.1 Token Usage per Skill¶

Token ceilings follow routing.json complexity_rules, and each skill is assigned to the tier that matches its cognitive load:

Prefill vs decode (llm-fundamentals-2026.md §1.4): a review skill pays prefill on the full diff + system prompt every turn; a planning skill pays prefill on the full repo orientation; a leaf implementation skill pays prefill on a small file scope. The skill's own instructions (SKILL.md) are static prefix — the exact thing prompt caching amortizes (§4.3).

4.2 Cost Optimization¶

The levers, in order of leverage (llm-fundamentals-2026.md §6.2), applied to skills:

4.3 Context Management¶

Every skill inherits the context stack (00n-context-mgr.sh, 70-context-engine.sh, 83-context-engineering.sh):

• Prompt-cache ordering — SKILL.md instructions are static blocks first, dynamic input last, preserving provider KV-cache prefix hits (60-caching.sh). This is why the harness principle "static blocks first" exists.
• Memory anchor — every skill response opens with [CTX: domain] so a role resumes after compaction without re-reading all files (coprocessor).
• Tiered memory — WAL (session) → Specs (persistent) → Artifacts (ground truth); a skill reads the cheapest authoritative tier.
• Lost-in-the-middle mitigation — critical constraints at the start and end of long skill instructions.
• Context guard (compression) — truncates/summarizes history to keep n small, directly cutting O(n²) attention cost.

4.4 Model Routing¶

Model selection is orthogonal to skill selection (agent-roles-2026.md §6.4): the Commander picks which skill (§2.2), the router picks which model.

Each profile carries an ordered fallback chain; on provider failure the router walks it before any skill notices. The isolated profile routes all skills to local-only backends — no cloud key exists in air-gap.

5. Skill Security¶

Skills are untrusted actors: each is a prompt that, when loaded, changes what the model is allowed to do. Security is enforced around the skill, not inside it.

5.1 Permission Boundaries¶

Deny-by-default, role-scoped, layered (agent-roles-2026.md §2.3):

5.2 Secret Access Control¶

• Hard gate: no skill may emit secrets; all secrets redacted with *** in logs and output.
• No secrets in skill files — SKILL.md bodies contain instructions, never keys. Pre-commit scans block sk-…, AKIA…, ghp_…, -----BEGIN PRIVATE KEY----- patterns.
• PII guard (45-pii-guard.sh, scripts/pii-guard.py): 9 detector classes run before any LLM request a skill triggers — including deep-research web content and issue-ingest GitHub bodies.
• Secrets arrive via CLI/env only — .env gitignored, chmod 600, _secrets_* API (90-secrets-manager.sh) for the corporate profile.

5.3 Audit Logging¶

Every skill's consequential action is journaled — not by the skill, but by the modules the skill's role calls:

• WAL (37-wal.sh) — append-only JSONL; {ts, domain, decision, rationale, impact, confidence, mode}. loop/phase-wrap/council journal their verdicts.
• Hash-chained audit (44-audit.sh) — seven event types (model_call, tool_call, pii_redacted, …), rotation >10 MB → gzip + Qdrant. commit-pr and swarm-pr-review emit tool_call/checkpoint events.
• Kernel corroboration (48-auditd.sh) — an independent kernel stream a user-space attacker (including a compromised skill) cannot tamper with.

5.4 Trust Levels¶

Skills are mapped to the role trust ladder (agent-roles-2026.md §5.4). The consequence of failure is what determines how much a skill is trusted to act autonomously:

flowchart TD
    T0["T0 — Orchestrator<br/>loop · council · critic-gate<br/>(own loop state + final synthesis)"]
    T1["T1 — Planner<br/>plan · specify · brainstorm<br/>(produce executable contract)"]
    T2["T2 — Implementer<br/>implement · tdd · writing-tests<br/>(only unrestricted write path)"]
    T3["T3 — Verifier<br/>code-review · swarm-pr-review<br/>(independent fresh context)"]

    T0 --> T1 --> T2 --> T3
    T3 -. "adversarial counterweight" .-> T2

    classDef t fill:#e3f2fd,stroke:#1565c0
    class T0,T1,T2,T3 t

Trust flows downhill (T0 most trusted for direction, T3 most trusted for correctness). No Worker skill self-approves: implement/tdd output is always gated by a Reviewer skill (code-review) with independent context.

6. Skill Evolution¶

Skills are versioned artifacts with a lifecycle. The repo currently does not have a dedicated skill-versioning module, but the pattern is established and the seams exist.

6.1 Skill Versioning¶

Recommended: a version: frontmatter field + a CHANGELOG per skill family, mirrored to the docs site. The ADR/versioning discipline already used for modules (v15.0.0 across README/CHANGELOG/package.json/SCRIPT_VERSION) should extend to the Tier-1 skill set.

6.2 Skill Deprecation¶

The existing pattern is the retired marker:

• skill_retire (slug) writes retired.marker; retired skills are excluded from scoring and injection.
• Deprecated skills are not deleted immediately — they are marked, then removed after a migration window.
• The writing-tests/running-tests shadowing across tiers (T1 vs matt-pocock) is the existing case to manage: same name, two locations. Deprecation must resolve shadowing explicitly, not leave an ambiguous load order.

6.3 Skill Migration¶

Migration paths already exercised in this repo:

Migration invariant: a skill's behavioral contract (its description + hard gates) is the public API. Migration must preserve the contract even when the implementation moves.

6.4 Skill Testing¶

Skills are tested like modules, at three levels:

Skill-improver loop (skill_improve, skill_opt): repeated agent successes become skills; repeated mistakes become AGENTS.md rules or programmed gates. This is the harness-engineering loop — the primary mechanism by which the skill set evolves against observed behavior.

Appendix A — Full Skill Inventory¶

Tier 1 — Project protocol skills (.opencode/skills/)¶

Tier 2 — Workflow toolkit (.opencode/skills/matt-pocock/)¶

Tier 3 — Global enablement (~/.config/opencode/skills/)¶

Appendix B — Skill ↔ Module / Doc cross-reference¶

The rule of thumb: modules are deterministic; skills are supervised. A skill expresses what the model should do; a module decides whether it may, where it runs, and what it costs — and records the result.

See also¶

• LLM Fundamentals 2026 — the theory this document maps to skills.
• AIPDLC Integration Guide — the seven-pillar methodology.
• Agent Role Definitions 2026 — the four-role hierarchy skills are bound to.
• Security Model 2026 — the threat model skills operate within.
• Multi-Agent Framework v3 ADR — the operating model.
• Architecture Index — C4 diagrams and module layout.