msd-core/docs/reference/skill-mapping-matrix.md

Per-runtime skill mapping matrix

Reference page. The authoritative source for every cell is the runtime's capabilities/<runtime>/capability.json artifactLayout descriptor, resolved by resolveRuntimeArtifactLayout in gsd-core/src/runtime-artifact-layout.cts. This page is the human-readable projection; when they disagree, the descriptor wins.

Decision record: ADR-1593 — Skill mapping & converter methodology across runtimes. See also ADR-3660 (layout owner) and ADR-1016 (converter enum).

How to read this matrix

GSD ships skills (and commands/agents) as Markdown files under commands/gsd/*.md. Each runtime installs them via a per-runtime layout (where they go) and a per-runtime converter (how their content is rewritten). The layout is a typed ArtifactKindDescriptor:

{ kind, destSubpath, prefix, nesting, recursive, converter }

• dest — the destination subpath under the runtime's config dir (e.g. skills, skills/gsd).
• prefix — the filename/dir prefix (gsd- for every skill-bearing runtime).
• nesting — flat (skills at one level) or nested (concrete skills nested under gsd-ns-* router dirs).
• loader — whether the runtime's skill loader recurses (recursive: true → nesting saves nothing, so the layout stays flat).
• converter — the ConverterName (closed enum, ADR-1016) that rewrites the source command into the runtime's skill format. null means raw-copy (no conversion).

For the transform each converter applies, see ADR-1593 §3 — converter transform-contract categories.

The 16-runtime matrix

Runtime	Skill dest (global)	Prefix	Nesting	Loader	Converter	Notes
claude	skills/	gsd-	flat	one-level (reverted from nested, #924)	convertClaudeCommandToClaudeSkill	Local scope ships commands+agents only (no skills kind). Plugin manifest (ADR-766) ships commands+hooks today; skills field is Phase B-provide.
codex	skills/	gsd-	flat	unconfirmed → conservative	convertClaudeCommandToCodexSkill	TOML config (configFormat: toml). Description truncated to 180 chars (metadata.short-description). sandboxTier: codex-agent-sandbox.
gemini	— (no skills kind)	—	—	—	—	Commands-only (TOML .toml in commands/gsd). No skill surface today — Phase C1 assesses Gemini's extension/skill model.
opencode	skills/	gsd-	flat	recursive (** glob)	convertClaudeCommandToOpencodeSkill	XDG config home. Shares the opencode-family converter entry point (convertClaudeCommandToOpencodeFamilySkill). Also ships command (singular) commands.
kilo	skills/	gsd-	flat	recursive (** glob)	convertClaudeCommandToKiloSkill	OpenCode fork; same ** glob loader. permissionWriter: kilo. Also ships command commands.
cursor	skills/	gsd-	flat	recursive	convertClaudeCommandToCursorSkill	Also ships flat commands/ via convertClaudeCommandToCursorCommand. configFormat: none.
copilot	skills/	gsd-	flat	unconfirmed → conservative	convertClaudeCommandToCopilotSkill	Markdown config. Scope-aware converter (global-home vs workspace-relative).
antigravity	skills/	gsd-	nested	non-recursive (one-level)	convertClaudeCommandToAntigravitySkill	dot-home-nested config home. Scope-aware converter. Nesting confirmed: "will not recursive scan".
windsurf	skills/	gsd-	flat	unconfirmed → conservative	convertClaudeCommandToWindsurfSkill	configFormat: none. installSurface: profile-marker-only.
augment	skills/	gsd-	nested	non-recursive (single-level)	convertClaudeCommandToAugmentSkill	Also ships flat commands/. Settings-json config.
trae	skills/	gsd-	nested	non-recursive (flat; nesting errors)	convertClaudeCommandToTraeSkill	configFormat: none. Trae IDE (trae.ai), not trae-agent.
qwen	skills/	gsd-	nested	non-recursive (flat readdir)	convertClaudeCommandToClaudeSkill	Shares Claude's converter. Emits numeric priority: (QWEN_SKILL_PRIORITY) for /skills ordering. Settings-json config.
hermes	skills/gsd/	gsd-	nested	non-recursive (single-level probe)	convertClaudeCommandToClaudeSkill	Shares Claude's converter. destSubpath: skills/gsd (category dir). Emits required version: field. prefix: gsd- restored by #947.
codebuddy	skills/	gsd-	flat	unconfirmed → conservative	convertClaudeCommandToCodebuddySkill	Also ships flat commands/ via convertClaudeCommandToCodebuddyCommand. dot-home config.
cline	skills/	gsd-	nested	non-recursive (flat fs.readdir)	convertClaudeCommandToClineSkill	Global-only — local: [] (no local skill install). Targets ~/.cline/skills/<name>/SKILL.md (Cline ≥ v3.48.0). markdown-dir config.
kimi	skills/	gsd-	flat	(false)	convertClaudeCommandToKimiSkill	Also ships a special kimi-agents kind (buildKimiAgentArtifacts). Name normalization (normalizeKimiSkillName). generic-agents-root config.

Structural facts

• All 15 skill-bearing runtimes use prefix: "gsd-". Gemini is the only runtime with no skills kind (commands-only TOML).
• Six runtimes nest (cline, qwen, hermes, augment, trae, antigravity) because their skill loaders scan one level deep — nesting drops nested concrete skills out of the eager top-level listing while keeping them readable by file path (the namespace-router contract, #69).
• Eight runtimes stay flat: three because their loaders recurse (cursor, opencode, kilo — nesting saves nothing), one because nesting was reverted (claude — the Skill tool errors on unknown names rather than re-routing, #924), and four conservatively where the loader depth is unconfirmed (codex, copilot, windsurf, codebuddy).
• Three runtimes share convertClaudeCommandToClaudeSkill (claude, qwen, hermes). The converter branches on the runtime arg for per-runtime branding (Hermes version:, Qwen priority:).

Nesting/loader verification (June 2026)

The nesting flag is set per the verified loader behavior of each runtime. Sources:

Behavior	Runtimes	Evidence
NEST (non-recursive / one-level scan)	cline, qwen, hermes, augment, trae, antigravity	cline skills.ts flat fs.readdir; Qwen skill-load.ts flat readdir; hermes single-level subdir probe; augment flat single-level; trae flat (nesting errors, Trae-AI/TRAE#2253); antigravity "will not recursive scan"
FLAT (recursive loader → nesting gives no saving)	cursor, opencode, kilo	cursor walks skills root recursively; opencode skill/index.ts glob skills/**/SKILL.md; kilo (opencode fork, same ** glob)
FLAT (reverted from nested)	claude	anthropics/claude-code#28266 — one-level scan, but Skill-tool errors on unknown names rather than re-routing via the router (#924)
FLAT (unconfirmed → conservative)	codex, copilot, windsurf, codebuddy	Loader depth not independently verified; kept flat to avoid mis-nesting

Plugin / external-skill provision + consumption

Per ADR-1593 §5, each platform's first-party packaging should provide and consume skills through the platform's documented, native mechanism.

Runtime	Provision model	Consumption model	Phase
claude	.claude-plugin/plugin.json skills field / skills/ dir (ADR-766; today commands+hooks only)	Sub-agent skills: preload + runtime Skill tool (PR #1261 — merged)	B-provide / D
gemini	gemini-extension.json (today commands-only, #775)	TBD — assess Gemini's extension/skill model	C1
codex	Codex extension model	TBD	C2
opencode / kilo	Recursive-loader plugin model	TBD	C3
cursor, copilot, windsurf, codebuddy	Flat-skill platform models	TBD	C4
cline, qwen, hermes, augment, trae, antigravity	Nested gsd-ns-* router models	TBD	C5
kimi	kimi-agents CLI module model	TBD	C6

Rejected for all platforms: reading another plugin's ephemeral/undocumented cache (e.g. Claude Code's ${CLAUDE_PLUGIN_ROOT} / ~/.claude/plugins/cache). The platform's native mechanism is the contract; cache-reading is a workaround, not a fix.

Keeping this page in sync

The capabilities/<runtime>/capability.json artifactLayout descriptors are the source of truth. When a runtime's layout changes, update the descriptor first; this page is the projection. Adding a new runtime requires: (1) a new capabilities/<runtime>/capability.json with an artifactLayout, (2) a new converter in the closed ConverterName enum (ADR-1016), and (3) a new row in this matrix.