Codex — Skills
- File format
- Markdown
- Discovery path
.agents/skills- Global install path
~/.agents/skills- Syllago install method
- Symlink, Direct copy
- Symlink support
- Yes
Features
How each feature converts to syllago's canonical format. See format conversion for what these statuses mean.
Fields
Native frontmatter or config fields this provider exposes. The first column is the provider's own field name; the canonical key column links to syllago's cross-provider equivalent.
| Provider field | Conversion | Canonical key | Summary |
|---|---|---|---|
description | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | description | YAML frontmatter key: description (required — empty string triggers MissingField error; max 1024 chars enforced after whitespace normalization) |
name | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | display_name | YAML frontmatter key: name (optional — falls back to parent directory name if absent or empty; max 64 chars enforced after whitespace normalization) |
dependencies.tools | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost.Learn more → | — | Declare required external tools or MCP servers via openai.yaml dependencies.tools (type, value, transport, command, url). |
interface.default_prompt | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost.Learn more → | — | Pre-filled starting prompt for UI invocation via openai.yaml interface.default_prompt (≤1024 chars). |
metadata.short-description | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost.Learn more → | — | Condensed skill description for compact UI; SKILL.md metadata.short-description or openai.yaml interface.short_description (≤1024 chars). |
interface.brand_color | DroppedConversion type: DroppedCan’t be meaningfully preserved. Removed from the output with a portability warning.Learn more → | — | Brand color for the skill card via openai.yaml interface.brand_color (#RRGGBB hex). |
interface.icon_small | DroppedConversion type: DroppedCan’t be meaningfully preserved. Removed from the output with a portability warning.Learn more → | — | Small and large skill icons via openai.yaml interface.icon_small/icon_large; paths must be relative under assets/. |
policy.products | DroppedConversion type: DroppedCan’t be meaningfully preserved. Removed from the output with a portability warning.Learn more → | — | Restrict skill visibility to specific OpenAI products via openai.yaml policy.products (empty = all products). |
Other features
Behaviors, conventions, and capabilities that aren't tied to a single named field — things like path-based activation, discovery rules, and lifecycle behavior.
| Feature | Conversion | Summary |
|---|---|---|
canonical_filename | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | Fixed filename SKILL.md required within each named skill directory (SKILLS_FILENAME constant) |
disable_model_invocation | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | openai.yaml companion file key: policy.allow_implicit_invocation (optional bool; false disables implicit/auto invocation; defaults to true when absent) |
global_scope | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | Skills directory at $HOME/.agents/skills/ or the user config layer's skills/ subdir ($CODEX_HOME/skills, deprecated but kept for backward compatibility) (SkillScope::User) |
project_scope | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | Skills directory at <project_config_folder>/skills/ (SkillScope::Repo) or any .agents/skills/ directory between project root and cwd (monorepo traversal) |
shared_scope | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | Admin scope at /etc/codex/skills on Unix (SkillScope::Admin) — machine-level shared skills readable by all local users; injected via System config layer |
| Monorepo Skill Discovery | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | Walk between project root and cwd collecting .agents/skills/ dirs; capped by MAX_SCAN_DEPTH=6 and MAX_SKILLS_DIRS_PER_ROOT=2000. |
| openai.yaml Companion Metadata File | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | Optional <skill_dir>/agents/openai.yaml file providing interface, dependencies, and policy metadata separate from SKILL.md frontmatter. |
| Plugin Scope | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | Externally-injected plugin_skill_roots assigned User scope with namespaced name prefix; no config file required. |
| Skill Deduplication | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | Skills with duplicate paths are deduped (highest-priority scope wins) then sorted Repo > User > System > Admin, then by name and path. |
| System Scope (Embedded Skills Cache) | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | Fourth scope beyond Repo/User/Admin: embedded skills cached under $CODEX_HOME/skills/.system; symlinks not followed. |