writing-commands

Writing Codex User-Invocable Skills

Codex does not use slash-command files. A command-like workflow is a skill in .codex/skills/<skill-name>/SKILL.md with user-invocable: true.

Skill File Format

---
name: workflow-name
description: One-line trigger description for this workflow
user-invocable: true
---

Put argument parsing and workflow phases in the body. Do not include Claude-only tool allow-list metadata.

The Orchestrator Pattern

Most powerful user-invocable skills coordinate phases:

Phase 1: Understand  -> read docs, inspect files, find patterns
Phase 2: Plan        -> output a structured checklist and call update_plan
Phase 3: Execute     -> edit files with apply_patch
Phase 4: Verify      -> run build/typecheck commands with exec_command
Phase 5: Test        -> run or add tests
Phase 6: Review      -> optionally use spawn_agent for independent reviewers
Phase 7: Document    -> update affected docs
Phase 8: Report      -> summarize files changed and verification

Not every workflow needs all phases. Simple workflows such as lint or test may have 2-3 phases.

Dispatching Subagents

Use spawn_agent only when the user has authorized subagents or parallel agent work. Good subagent prompts are self-contained:

Review the TypeScript changes listed below.
Context: <diff/stat/intent>
Files: <filtered list>
Return only findings in the standard severity/confidence format.

Use wait_agent only when the next step depends on the result. Keep local critical-path work moving while independent agents run.

Auto-Detection Pattern

For multi-stack projects, detect stack markers with rg --files:

go.mod exists?                    -> Go project
package.json + tsconfig.json      -> TypeScript project
pyproject.toml / requirements.txt -> Python project
Cargo.toml exists?                -> Rust project

Use existing project commands from AGENTS.md, package.json, Makefile, or CI before inventing new commands.