Author A Codex Skill, Agent, Hook, Or Plugin

Turn a one-line intent into the correct Codex extension artifact. Choose the artifact type first; the wrong type is the easiest way to create brittle automation.

Artifact Judgment

• Skill: reusable procedural knowledge Codex can invoke implicitly or via

$skill-name. Use for context-rich workflows that benefit from model judgment.

• Custom agent: a named, reusable role with its own instructions, usually TOML under

.codex/agents/ for project scope or ~/.codex/agents/ for personal scope. Use for isolated, repeatable subagent work.

• Hook: deterministic automation that must run on an event. Use for validation,

formatting, or guardrails that should not depend on model memory.

• Plugin: packaged distribution unit for Codex skills, agents, MCP/apps, hooks, or

marketplace-backed sharing. Use when the user wants an installable bundle.

Placement

• Personal/global skill: ${CODEX_HOME:-~/.codex}/skills/<name>/SKILL.md.
• Repo/team skill: .agents/skills/<name>/SKILL.md or a plugin-provided skill, when

the repo should carry it.

• Project custom agent: .codex/agents/<name>.toml.
• Personal custom agent: ${CODEX_HOME:-~/.codex}/agents/<name>.toml.
• Plugin: a plugin root with .codex-plugin/plugin.json and optional skills/,

hooks, scripts, assets, MCP, or apps.

Default to project placement when the artifact depends on repo paths, commands, or conventions. Use personal/global placement only for genuinely project-agnostic skills.

Procedure

1. Capture Intent

Use the user's one-line description. If essential information is missing, ask only the smallest number of questions needed: what it does, when it should trigger, and whether it is personal or repo-scoped.

2. Classify

Decide skill, custom agent, hook, or plugin. State the reason in one line before writing. If the user asked for "every time", "before", "after", or "always", bias toward a hook. If they asked for "share/install/package", bias toward a plugin.

3. Pick Name And Path

• Use kebab-case names: lowercase letters, digits, and hyphens.
• Keep names under 64 characters.
• Check for collisions in the selected target and adjacent Codex locations.
• Confirm when placement is ambiguous.

4. Write The Artifact

For a skill:

• Write SKILL.md with only name and description frontmatter unless Codex docs for

the target explicitly allow more.

• Make description trigger-rich: what it does plus concrete user phrases and contexts.
• Keep body concise, procedural, and resource-aware.
• Add agents/openai.yaml only when UI metadata is useful.

For a custom agent:

• Write TOML with name, description, and developer instructions in the Codex custom

agent format used by the target installation.

• Keep the role narrow and specify final output shape.
• Do not grant broader tools or autonomy than the role needs.

For a hook:

• Prefer a small deterministic script plus product config.
• Include a dry-run or logging path where practical.
• Do not install hooks silently; show the config change.

For a plugin:

• Use the Codex plugin scaffold workflow and validate .codex-plugin/plugin.json.

5. Validate

• Parse YAML/TOML/JSON.
• Check skill folder name matches frontmatter name.
• Check the description would trigger for the intended phrases.
• Run any provided validator or the narrowest local syntax check.

6. Hand Off

Report what was created and where. Remind the user that new Codex skills and agents are picked up in a new session.

Guardrails

• Classify before writing.
• Do not create a skill for deterministic always-on automation; use a hook.
• Do not create a custom agent for one-off generic exploration.
• Keep repo-coupled artifacts project-scoped.
• Never clobber an existing skill, agent, hook, or plugin.