opencode

Compatibility: OpenCode (SKILL.md)

Claim (Tier B, narrow). An MDA-compiled SKILL.md whose frontmatter stays inside the field surface OpenCode documents at https://opencode.ai/docs/skills/ is discovered and parsed by OpenCode when installed at ~/.config/opencode/skills/<name>/SKILL.md. name, description, body, plus the documented optional fields (license, compatibility, metadata) survive the round-trip from .mda source to runtime ingest.

Claim (negative). OpenCode's public docs enumerate exactly five top-level frontmatter fields (name, description, license, compatibility, metadata) and explicitly state "unknown frontmatter fields are ignored". MDA may emit allowed-tools (an agentskills.io v1 envelope field), and integrity/signatures (MDA additions), but OpenCode's documented behavior treats anything outside the five-field surface as ignored. This kit does not claim OpenCode honors allowed-tools, integrity, or signatures at load.

Last verified: 2026-05-26 against @markdown-ai/cli@1.1.7, OpenCode 1.15.10.

Directory contents

• source.mda — dedicated MDA source for this kit (do not reuse for unrelated examples)
• build/SKILL.md — reproducible compile output
• verify.sh — structural verification, no live install needed
• install.sh — optional live install to ~/.config/opencode/skills/mda-compat-opencode/SKILL.md
• uninstall.sh — removes the live install
• notes.md — scope, gaps, caveats, graduation criteria

Quick verify (offline, modifies nothing on your system)

./compat/opencode/verify.sh

Re-compiles source.mda, validates the output against the SKILL.md JSON Schema, and confirms the documented field surface is intact. Exit 0 means the structural claim holds.

Live verify (writes one file under ~/.config/opencode/)

./compat/opencode/install.sh
opencode debug skill | grep -A 5 mda-compat-opencode

Copies build/SKILL.md to ~/.config/opencode/skills/mda-compat-opencode/SKILL.md. opencode debug skill enumerates discovered skills with parsed frontmatter — confirms both discovery and parse without invoking a model.

To remove:

./compat/opencode/uninstall.sh

How OpenCode's loader actually behaves

From the official OpenCode skills documentation (https://opencode.ai/docs/skills/):

• Documented top-level frontmatter fields: name (req), description (req), license, compatibility, metadata.
• Unknown frontmatter fields are documented as ignored.
• name constraints: 1-64 chars, regex ^[a-z0-9]+(-[a-z0-9]+)*$, no leading/trailing hyphen, no consecutive hyphens. The name field MUST match the directory name. (These constraints are identical to MDA spec §06-2.1.)
• Discovery (in order, project-local first, then global):
  • Project: .opencode/skills/, .claude/skills/, .agents/skills/ (walked from cwd up to repo root)
  • Global: ~/.config/opencode/skills/, ~/.claude/skills/, ~/.agents/skills/
• The docs make no mention of agentskills.io v1 as an upstream contract.

What MDA emits today (v1.0)

The SKILL.md schema (schemas/frontmatter-skill-md.schema.json) permits these top-level fields, exactly:

Field	Source	OpenCode status
name	author	Documented, required.
description	author	Documented, required.
license	author	Documented, optional.
compatibility	author	Documented, optional.
allowed-tools	author	Not in OpenCode's documented surface; "unknown fields are ignored".
metadata	author	Documented, optional. metadata.mda.* for MDA extensions; OpenCode does not document reading any nested namespace.
integrity	compiler	Not in OpenCode's documented surface; ignored.
signatures	compiler/signer	Not in OpenCode's documented surface; ignored.

Everything in MDA's source schema that lives inside the OpenCode-documented surface survives the round-trip. Everything else passes through harmlessly because OpenCode ignores unknown fields.

What this kit does NOT claim

• That OpenCode parses MDA-extended frontmatter (metadata.mda.*, metadata.opencode.*, etc.).
• That signed MDA artifacts are verified at load time by OpenCode.
• That ~/.config/opencode/skills/<name>/SKILL.md is the only path OpenCode reads. OpenCode also walks .opencode/skills/, .claude/skills/, .agents/skills/ (project-local) and ~/.claude/skills/, ~/.agents/skills/ (global). This kit defaults to OpenCode's own canonical user-level path.
• That allowed-tools is honored. The kit deliberately omits it from source.mda to mirror OpenCode's documented surface exactly.

Anything stronger belongs in a future Tier-C section, behind explicit runtime opt-in to MDA extensions.