{ "schemaVersion": 1, "updatedAt": "2026-10-15", "contracts": [ { "harness": "codex", "variant": "current", "default": true, "path": "agents/openai.yaml", "format": "yaml", "consumer": "machine-or-harness", "topLevelConstraints": ["Quote all string values.", "Keep mapping keys unquoted."], "fields": [ { "path": "interface.display_name", "requiredness": "optional", "types": ["string"], "semantics": "Human-facing title shown in UI skill lists and chips.", "evidenceStatus": "documented" }, { "path": "interface.short_description", "requiredness": "optional", "types": ["string"], "semantics": "Human-facing short UI blurb for quick scanning.", "constraints": ["Length is 25 through 64 characters, inclusive."], "evidenceStatus": "documented" }, { "path": "interface.icon_small", "requiredness": "optional", "types": ["string"], "semantics": "Path to a small icon asset relative to the skill directory.", "constraints": ["Default location is the skill's ./assets/ directory."], "evidenceStatus": "documented" }, { "path": "interface.icon_large", "requiredness": "optional", "types": ["string"], "semantics": "Path to a larger logo asset relative to the skill directory.", "constraints": ["Default location is the skill's ./assets/ directory."], "evidenceStatus": "documented" }, { "path": "interface.brand_color", "requiredness": "optional", "types": ["string"], "semantics": "Hex color used for UI accents such as badges.", "constraints": ["Value is a hexadecimal color string."], "evidenceStatus": "documented" }, { "path": "interface.default_prompt", "requiredness": "optional", "types": ["string"], "semantics": "Default prompt snippet inserted when invoking the skill.", "constraints": [ "Use a helpful, short example, typically one sentence.", "The prompt must explicitly mention the skill using $skill-name syntax." ], "evidenceStatus": "documented" }, { "path": "dependencies.tools", "requiredness": "optional", "types": ["array"], "semantics": "Tool dependencies advertised by the skill.", "constraints": ["Dependencies are declarations, not permission boundaries."], "evidenceStatus": "documented" }, { "path": "dependencies.tools[].type", "requiredness": "required", "types": ["string"], "semantics": "Dependency category.", "constraints": [ "Only mcp is currently documented as supported.", "The loader drops a dependency item when this field is absent, empty, or longer than 64 characters." ], "evidenceStatus": "documented" }, { "path": "dependencies.tools[].value", "requiredness": "required", "types": ["string"], "semantics": "Identifier of the tool or dependency.", "constraints": [ "The loader drops a dependency item when this field is absent, empty, or longer than 1024 characters." ], "evidenceStatus": "first-party-source" }, { "path": "dependencies.tools[].description", "requiredness": "optional", "types": ["string"], "semantics": "Human-readable explanation of the dependency.", "evidenceStatus": "first-party-source", "constraints": [ "Released 0.162.1 deserializes this field as Option and resolves it without requiring a value." ] }, { "path": "dependencies.tools[].transport", "requiredness": "conditional", "types": ["string"], "semantics": "Connection type for an MCP dependency.", "constraints": ["Applies when dependencies.tools[].type is mcp."], "evidenceStatus": "documented" }, { "path": "dependencies.tools[].url", "requiredness": "conditional", "types": ["string"], "semantics": "MCP server URL for an MCP dependency.", "constraints": ["Applies when dependencies.tools[].type is mcp."], "evidenceStatus": "documented" }, { "path": "dependencies.tools[].command", "requiredness": "optional", "types": ["string"], "semantics": "Command used to launch a tool dependency such as a stdio MCP server.", "constraints": [ "The loader normalizes whitespace and ignores an empty value or one longer than 1024 characters." ], "evidenceStatus": "first-party-source" }, { "path": "dependencies.tools[].oauth.callbackPort", "requiredness": "optional", "types": ["integer"], "semantics": "OAuth callback port for the dependency.", "constraints": [ "The value is parsed as an unsigned 16-bit integer.", "callback_port is accepted as an alias for callbackPort." ], "evidenceStatus": "first-party-source" }, { "path": "policy.allow_implicit_invocation", "requiredness": "optional", "types": ["boolean"], "semantics": "Whether the model may select the skill without the user naming it explicitly.", "constraints": [ "False excludes the skill from the model-visible implicit skill catalog while explicit $skill invocation remains available.", "The field defaults to true when the policy or value is absent." ], "evidenceStatus": "documented" }, { "path": "policy.products", "requiredness": "optional", "types": ["array"], "semantics": "Restricts the skill metadata to matching OpenAI products.", "constraints": [ "An empty list means no product restriction.", "The loader parses values through the Codex Product vocabulary." ], "evidenceStatus": "first-party-source" } ], "evidence": [ "codex-openai-yaml-reference", "codex-openai-yaml-loader-source", "codex-skill-policy-model-source", "codex-openai-yaml-policy-example", "codex-skills-docs", "codex-skill-policy-host-0.160.1-source", "codex-skill-policy-executor-0.160.1-source", "codex-skill-visible-catalog-0.160.1-source", "codex-openai-yaml-0.162.1-loader-source", "codex-openai-yaml-0.162.1-reference", "codex-skill-render-0.162.1-source", "codex-token-accounting-0.162.1-source", "codex-skill-policy-host-0.162.1-source", "codex-skill-policy-executor-0.162.1-source", "codex-skill-visible-catalog-0.162.1-source" ], "reference": "https://github.com/openai/codex/blob/092d3acd6bec3e3a14bdc7e7a2810ab628ab759d/codex-rs/skills/src/assets/samples/skill-creator/references/openai_yaml.md#openaiyaml-fields-full-example--descriptions", "notes": [ "This product-specific file is read by the machine or harness, not as agent instructions; SKILL.md frontmatter is modeled separately.", "Codex source confirms that allow_implicit_invocation defaults to true and controls admission to the model-visible implicit skill catalog; it does not disable explicit $skill invocation.", "Malformed or unreadable optional metadata fails open: Codex ignores agents/openai.yaml metadata and continues loading SKILL.md.", "Serde does not deny unknown fields in the loader structs, so unknown mapping keys are ignored by the observed implementation.", "The source accepts command, OAuth callback-port, and product-policy fields that are not all present in the bundled full-field reference; their evidence status remains first-party-source.", "Source-observed in Codex 0.160.1 (d27764b82f7118f674371e6d6e76271d9d606edb): false removes the skill name, description and path before initial listing budget allocation; explicit invocation still loads instructions into conversation context outside that budget.", "Released 0.162.1 metadata structs and resolver rechecked on October 15; dependency description is optional in the loader. Historical policy evidence remains separately dated." ] } ] }