Guides practical Codex CLI usage with an evidence-first, command-oriented workflow.
Scope
Use this skill for:
- Installing or upgrading Codex CLI
- Authentication and account/session issues
- Model selection and runtime behavior questions
- Agent and tool usage patterns
- Creating and maintaining local custom skills
- Diagnosing common command or environment failures
Safety rules
- Prefer read-only diagnostics before making changes.
- Use minimal-impact, reversible actions first.
- Do not run destructive commands unless the user explicitly asks.
- Ask one focused question when requirements are ambiguous.
Setup (always run first)
- Gather runtime facts:
pwd
uname -a
codex --version || true
echo "$SHELL"
- Classify context:
- OS and shell
- Repository or non-repository workspace
- Whether the request is usage help, troubleshooting, or skill authoring
- Load shared references:
- reference/diagnostics.md
- reference/skills.md
Command menu
If no argument is provided, show this table and ask what to run.
| Command |
Focus |
Typical checks |
triage [symptom] |
General intake |
scope, impact, errors, recent changes |
setup [goal] |
Install and environment setup |
binary, PATH, version, shell profile |
auth [symptom] |
Sign-in and token issues |
auth state, account, credential store |
models [goal] |
Model selection and behavior |
model id, capability, cost/speed tradeoff |
skills [goal] |
Custom skill creation/maintenance |
directory layout, metadata, references |
agents [goal] |
Sub-agent strategy |
delegation boundaries, background handling |
workflow [goal] |
Day-to-day CLI workflow |
search/edit/test loops, batching, verification |
If the first word matches a command, focus on that area.
If not, treat the full input as a symptom and run triage.
Output contract
For each run, provide:
- Diagnosis: likely cause and confidence
- Immediate fix: lowest-risk next step
- Durable fix: longer-term improvement
- Rollback: exact undo path
- Verification: commands and healthy expected output
1---2name: codex-cli3description: Use when working with Codex CLI workflows, troubleshooting, and custom skill authoring.4version: 1.0.05user-invocable: true6argument-hint: "[triage|setup|auth|models|skills|agents|workflow] [goal]"7license: Apache-2.08---91011Guides practical Codex CLI usage with an evidence-first, command-oriented workflow.1213## Scope1415Use this skill for:1617- Installing or upgrading Codex CLI18- Authentication and account/session issues19- Model selection and runtime behavior questions20- Agent and tool usage patterns21- Creating and maintaining local custom skills22- Diagnosing common command or environment failures2324## Safety rules25261. Prefer read-only diagnostics before making changes.272. Use minimal-impact, reversible actions first.283. Do not run destructive commands unless the user explicitly asks.294. Ask one focused question when requirements are ambiguous.3031## Setup (always run first)32331. Gather runtime facts:3435```bash36pwd37uname -a38codex --version || true39echo "$SHELL"40```41422. Classify context:4344- OS and shell45- Repository or non-repository workspace46- Whether the request is usage help, troubleshooting, or skill authoring47483. Load shared references:4950- [reference/diagnostics.md](reference/diagnostics.md)51- [reference/skills.md](reference/skills.md)5253## Command menu5455If no argument is provided, show this table and ask what to run.5657| Command | Focus | Typical checks |58|---|---|---|59| `triage [symptom]` | General intake | scope, impact, errors, recent changes |60| `setup [goal]` | Install and environment setup | binary, PATH, version, shell profile |61| `auth [symptom]` | Sign-in and token issues | auth state, account, credential store |62| `models [goal]` | Model selection and behavior | model id, capability, cost/speed tradeoff |63| `skills [goal]` | Custom skill creation/maintenance | directory layout, metadata, references |64| `agents [goal]` | Sub-agent strategy | delegation boundaries, background handling |65| `workflow [goal]` | Day-to-day CLI workflow | search/edit/test loops, batching, verification |6667If the first word matches a command, focus on that area.68If not, treat the full input as a symptom and run `triage`.6970## Output contract7172For each run, provide:73741. **Diagnosis**: likely cause and confidence752. **Immediate fix**: lowest-risk next step763. **Durable fix**: longer-term improvement774. **Rollback**: exact undo path785. **Verification**: commands and healthy expected output
w0pal