#Agent Skills

Skills package repeatable workflows into modules the agent can discover and execute. Codex Skills follow the open Agent Skills standard—the same SKILL.md can move between Claude Code, Cursor, Gemini CLI, and Codex.

#What is a Skill?

A Skill is usually a directory:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable scripts
├── references/       # Optional: supplementary docs
└── agents/
    └── openai.yaml   # Optional: Codex App UI + MCP dependency declarations

#Minimal SKILL.md example

---
name: commit
description: Stage and commit in semantic groups. Use when the user mentions commit, clean up commits, or pre-push branch hygiene.
---

1. Never `git add .`; stage in logical groups.
2. Suggested order: feat → test → docs → refactor → chore.
3. Keep each commit message concise and scoped to its diff.
4. Confirm `git status` has no unexpected files before committing.

#Locations

#Invocation

#1. Explicit

In the TUI:

$commit

Or list Skills:

/skills

#2. Implicit

When the user task matches the Skill description, Codex may select it automatically.
Write descriptions with trigger scenarios, not vague titles.

#3. Disable implicit (optional)

In agents/openai.yaml:

policy:
  allow_implicit_invocation: false

Only $skill-name triggers—good for high-risk flows.

#Progressive disclosure

Codex does not load every Skill body at startup:

1. Startup: name + description metadata only
2. On selection: full SKILL.md body
3. On demand: references or scripts/

You can maintain many Skills in a monorepo without blowing the context window.

#Built-in and curated Skills

Codex provides $skill-installer for official curated skills, e.g.:

$skill-installer gh-address-comments

Common built-in / official Skills (version-dependent):

• skill-creator — interactive Skill authoring
• plugin-creator — package a Plugin
• openai-docs — search OpenAI documentation

#Plugins: distribution unit for Skills

Skill = author format; Plugin = installable bundle that may include:

• Multiple Skills
• MCP server configuration
• App UI metadata

Prefer Plugins for team rollout; use directory Skills for personal experiments.

#Combining with MCP

When a Skill needs GitHub, Linear, a browser, etc.:

1. Document which MCP tools to call in Skill steps
2. Declare dependencies.tools in agents/openai.yaml (type: mcp)
3. With features.skill_mcp_dependency_install enabled (default), Codex can prompt to install missing MCP servers

Example dependency snippet:

dependencies:
  tools:
    - type: mcp
      value: openaiDeveloperDocs
      description: OpenAI Docs MCP server
      transport: streamable_http
      url: https://developers.openai.com/mcp

#Writing effective Skills

1. Single responsibility: one Skill per task class (release, review, migrate)
2. Verifiable steps: each step has a done criterion (“tests pass”, “diff only touches .ts”)
3. Constraints first: forbid force push, lockfile edits, etc.
4. Scripts for validation: put checks in scripts/validate.sh to limit model improvisation

#Migrating from Claude Code

The Skill format is highly compatible with Claude Code. Copy .agents/skills or skills/ into Codex—no JSON→TOML migration needed for Skills themselves.

#Next steps

• MCP Integration: wire external systems for Skills
• Practical Examples: release workflow as a Skill