Which SKILL.md frontmatter fields each harness reads, and how it treats the file. Fields marked “standard” come from the Agent Skills specification; the rest are specific to one harness. A dash means the harness does not document the field. Harness names link to their skill docs.
Fields
| Field | Codex CLI | Claude Code | Cursor Agent | OpenCode | pi |
|---|---|---|---|---|---|
namestandard | Required Discovery name text | Optional Display and invocation name; defaults from the directory text | Required Skill name text | Optional Display name; absent name uses path-derived ID. No directory match or length constraint in the parser. text | Required Skill name text; lowercase letters, digits and single hyphens; at most 64 characters |
descriptionstandard | Required Discovery and implicit-invocation description text | Optional Discovery description; may be inferred from content text | Required Discovery description text | Optional Full description used in listing; missing description suppresses model advertisement but does not unregister the skill. text | Required Discovery description text; at most 1024 characters Tested 0.84.2: 10,000 characters still load, with a warning above 1024. Tested 1.1.0: 10,000 characters still load, with a warning above 1024. |
licensestandard | Not established Agent Skills portable metadata text | Optional Portable license metadata text | Optional Portable license metadata text | ignored Not interpreted by the loader. any | Optional Portable license metadata text |
compatibilitystandard | Not established Agent Skills portable environment requirements text; at most 500 characters | Optional Portable environment requirements text; at most 500 characters | Optional Portable environment requirements text; at most 500 characters | ignored Not interpreted by the loader. any | Optional Portable environment requirements text; at most 500 characters |
metadatastandard | Not established Agent Skills portable extension metadata map of text | Optional Free-form metadata object | Optional Portable extension metadata map of text | Optional opencode/autoinvoke is interpreted when metadata is an object; other metadata does not alter skill instructions. any | Optional Portable extension metadata map of text |
allowed-toolsstandard | Not supported Codex permissions are not declared by SKILL.md frontmatter text or list | Optional Tools allowed while the skill is active; not a portable restriction text or list | — | — | — |
disable-model-invocation | — | Optional Disable implicit model invocation true or false | Optional Disable automatic invocation true or false | Optional Truthy boolean-like value disables automatic listing unless metadata opencode/autoinvoke overrides it. true or false or text or number | — |
user-invocable | — | Optional Control user invocation true or false | — | — | — |
argument-hint | — | Optional Invocation UI hint text | — | — | — |
context | — | Optional Execution context text; one of: fork | — | — | — |
agent | — | Optional Subagent used with forked context text | — | — | — |
hooks | — | Optional Skill-scoped hooks object | — | — | — |
icon | — | — | Optional Cursor presentation metadata text | — | — |
color | — | — | Optional Cursor presentation metadata text | — | — |
How the file is read
| Codex CLI | Claude Code | Cursor Agent | OpenCode | pi | |
|---|---|---|---|---|---|
| Needs a --- frontmatter block | Yes | No; plain Markdown also loads | Yes | No; plain Markdown also loads | Yes |
| Skill name comes from | The name field | The name field, or the folder name if it is missing | The name field | The name field | The name field |
| Name must match its folder | Not established | No | Not established | No | Not established |
| Invalid YAML | Not established | Not established | Not established | The skill is not loaded | A warning, and the skill is skipped |
| Fields it does not know | Not established | Not established | Not established | Ignored | Ignored |
Notes and sources
Codex CLI
- Invocation policy and tool dependencies live in agents/openai.yaml, not SKILL.md frontmatter.
- Codex: Agent Skills, Documentation, checked 2026-08-27
- Agent Skills specification, standard, checked 2026-08-25
- vitest-harness Codex skill conformance tests, test, checked 2026-08-27
Claude Code
- 2.1.304: a main-conversation skill whose hooks are excluded by plugin-only hook policy no longer receives its allowed-tools grant. Skill hook registration is capped per source at 1,024 hooks and 16,384 matcher characters per session; see the October 21 release review.
- Claude Code: Extend Claude with skills, Documentation, checked 2026-10-15
- Agent Skills specification, standard, checked 2026-08-25
- vitest-harness Claude skill conformance tests, test, checked 2026-08-27
- Claude Code 2.1.304 published changes; no runtime probe, Documentation, checked 2026-10-21
Cursor Agent
- Cursor Agent Skills, Documentation, checked 2026-08-27
- Agent Skills specification, standard, checked 2026-08-25
OpenCode
- Released 2.0.29 source at 042d0832f5f3a73eaa039a58a7d565776f6d4290; no model invocation was performed.
- The parser retries selected unquoted-colon YAML through sanitization; remaining malformed YAML or wrong name/description types skip the skill.
- ID comes from the file or containing directory, independently of the display name.
- No parser description cap was found; this does not guarantee provider acceptance of an arbitrarily large prompt.
- OpenCode 2.0.29 skill parser, Source code, checked 2026-10-15
- OpenCode 2.0.29 Markdown YAML sanitization and rejection, Source code, checked 2026-10-15
- Released OpenCode 2.0.29 skill roots, identity, precedence and loading, Documentation, checked 2026-10-15
pi
- Validation is intentionally lenient in some versions; pin the client version when converting warnings into compatibility claims.
- Pi 0.84.2 and 1.1.0 warn above 1024 UTF-16 code units but still load and format the entire description, including 10000 ASCII characters. This maxLength is a warning threshold, not a rejection or truncation limit. See docs/research/evidence/skill-description-length-2026-10-08.json.
- pi skills documentation, Documentation, checked 2026-08-27
- Agent Skills specification, standard, checked 2026-08-25