256 lines
6.5 KiB
Markdown
256 lines
6.5 KiB
Markdown
# Codex CLI Implementation
|
|
|
|
Codex CLI-specific implementation details for Agent Skills. For cross-platform concepts, see the main [SKILL.md](../SKILL.md).
|
|
|
|
## Discovery Paths
|
|
|
|
Codex loads skills from multiple locations with this precedence order (higher overrides lower):
|
|
|
|
| Scope | Location | Use Case |
|
|
| ----- | -------- | -------- |
|
|
| `REPO` | `$CWD/.codex/skills` | Project-specific skills in current directory |
|
|
| `REPO` | `$CWD/../.codex/skills` | Parent folder skills (when in Git repo) |
|
|
| `REPO` | `$REPO_ROOT/.codex/skills` | Repository root skills |
|
|
| `USER` | `$CODEX_HOME/skills` (default: `~/.codex/skills`) | User's personal skills |
|
|
| `ADMIN` | `/etc/codex/skills` | System/admin skills |
|
|
| `SYSTEM` | Bundled with Codex | Built-in skills |
|
|
|
|
**Key behaviors:**
|
|
- Skills with the same name from higher precedence scopes overwrite lower ones
|
|
- Skills are discovered at startup by scanning these paths
|
|
- Restart Codex after installing new skills to load them
|
|
|
|
## Enabling Skills
|
|
|
|
Skills are gated behind a feature flag:
|
|
|
|
```bash
|
|
# Check if enabled
|
|
codex features list
|
|
|
|
# Enable once
|
|
codex --enable skills
|
|
|
|
# Enable permanently in ~/.codex/config.toml:
|
|
[features]
|
|
skills = true
|
|
```
|
|
|
|
## Invocation Methods
|
|
|
|
### Explicit Invocation
|
|
|
|
Supported in CLI and IDE extensions:
|
|
|
|
```
|
|
# Skill picker
|
|
Type $ to see available skills
|
|
|
|
# Slash command
|
|
/skills
|
|
|
|
# Direct mention in prompt
|
|
$skill-name analyze this code
|
|
```
|
|
|
|
Not yet supported in Codex Web or iOS.
|
|
|
|
### Implicit Invocation
|
|
|
|
Works across all platforms (CLI, Web, iOS):
|
|
|
|
- Codex auto-detects when task matches a skill's description
|
|
- The `description` field is the primary trigger signal
|
|
- Write descriptions with "Use when..." clauses for better matching
|
|
|
|
```yaml
|
|
# Good: clear trigger conditions
|
|
description: Extracts text and tables from PDFs. Use when working with PDF files or document extraction.
|
|
|
|
# Bad: vague, hard to match
|
|
description: Helps with files
|
|
```
|
|
|
|
## AGENTS.md vs Skills
|
|
|
|
Codex uses `AGENTS.md` for project instructions, separate from skills:
|
|
|
|
| Aspect | AGENTS.md | Skills |
|
|
| ------ | --------- | ------ |
|
|
| **Loading** | Always loaded per-session | Loaded on-demand when invoked |
|
|
| **Purpose** | Project-wide context and rules | Task-specific capabilities |
|
|
| **Scope** | Per-repository | Personal, project, or system |
|
|
| **Location** | Repository root or `~/.codex/` | `skills/` directories |
|
|
|
|
**AGENTS.md discovery order:**
|
|
1. `~/.codex/AGENTS.override.md` (or `AGENTS.md`)
|
|
2. Repository root `AGENTS.md`
|
|
3. Nested `AGENTS.override.md` in subdirectories
|
|
|
|
## Built-in Skills
|
|
|
|
Codex includes utility skills:
|
|
|
|
| Skill | Purpose |
|
|
| ----- | ------- |
|
|
| `$skill-creator` | Creates new skills interactively |
|
|
| `$skill-installer` | Downloads skills from GitHub repos |
|
|
| `$create-plan` | Experimental planning skill |
|
|
|
|
### Skill Installer
|
|
|
|
```bash
|
|
# Install from OpenAI's curated skills
|
|
$skill-installer linear
|
|
$skill-installer notion-spec-to-implementation
|
|
|
|
# Downloads to $CODEX_HOME/skills/
|
|
```
|
|
|
|
## Tool Restrictions
|
|
|
|
The `allowed-tools` field is experimental in Codex:
|
|
|
|
```yaml
|
|
allowed-tools: Bash(git:*) Bash(jq:*) Read
|
|
```
|
|
|
|
**Status:**
|
|
- Marked as "experimental" in the Agent Skills spec
|
|
- "Support for this field may vary between agent implementations"
|
|
- No explicit Codex documentation on implementation
|
|
|
|
**Alternative controls in Codex:**
|
|
- Global `sandbox_mode` setting
|
|
- Global `approval_policy` setting
|
|
- MCP servers support `enabled_tools` and `disabled_tools` arrays
|
|
- No per-skill tool restrictions documented
|
|
|
|
## Testing Skills
|
|
|
|
### Validation
|
|
|
|
Use the skills-ref validator:
|
|
|
|
```bash
|
|
skills-ref validate ./my-skill
|
|
```
|
|
|
|
Checks:
|
|
- YAML frontmatter validity
|
|
- Name/description constraints
|
|
- Naming conventions
|
|
|
|
### Testing Workflow
|
|
|
|
1. Create skill in `~/.codex/skills/my-skill/`
|
|
2. **Restart Codex** to load it (required)
|
|
3. Test explicit invocation: `$my-skill test task`
|
|
4. Test implicit invocation: Use keywords from description
|
|
5. Check `/skills` command to confirm it's loaded
|
|
|
|
### Debugging
|
|
|
|
- Check `~/.codex/log/codex-tui.log` for skill loading errors
|
|
- Validation errors shown at startup if YAML malformed
|
|
- Codex ignores empty files and symlinked directories
|
|
|
|
## Troubleshooting
|
|
|
|
### Skill Not Loading
|
|
|
|
**Check feature flag:**
|
|
|
|
```bash
|
|
codex features list
|
|
# Look for: skills ... true
|
|
```
|
|
|
|
**Verify file location:**
|
|
|
|
```bash
|
|
# Personal skills
|
|
ls ~/.codex/skills/my-skill/SKILL.md
|
|
|
|
# Project skills
|
|
ls .codex/skills/my-skill/SKILL.md
|
|
```
|
|
|
|
**Restart Codex:**
|
|
|
|
Skills are only discovered at startup. After adding a new skill, restart the CLI.
|
|
|
|
### Skill Not Activating
|
|
|
|
**Check description triggers:**
|
|
|
|
The description is the primary trigger for implicit invocation. Ensure it includes:
|
|
- What the skill does
|
|
- "Use when..." conditions
|
|
- Keywords users would naturally say
|
|
|
|
**Try explicit invocation:**
|
|
|
|
```
|
|
$skill-name do the task
|
|
```
|
|
|
|
If explicit works but implicit doesn't, improve the description.
|
|
|
|
### Validation Errors
|
|
|
|
**Check YAML syntax:**
|
|
|
|
```bash
|
|
# Validate YAML
|
|
python3 -c "import yaml; yaml.safe_load(open('SKILL.md').read().split('---')[1])"
|
|
|
|
# Check for tabs (YAML requires spaces)
|
|
grep -P "\t" SKILL.md
|
|
```
|
|
|
|
**Common issues:**
|
|
- Tabs instead of spaces
|
|
- Missing quotes around special characters
|
|
- Missing closing `---` delimiter
|
|
|
|
## Differences from Claude Code
|
|
|
|
| Feature | Codex CLI | Claude Code |
|
|
| ------- | --------- | ----------- |
|
|
| **Skill loading** | Feature flag required | Built-in support |
|
|
| **Discovery paths** | 6 scopes with precedence | Plugin system + `.claude/skills/` |
|
|
| **Invocation** | `$skill-name` syntax | Skill tool, natural language |
|
|
| **Project instructions** | `AGENTS.md` | `CLAUDE.md` |
|
|
| **Restart required** | Yes, after adding skills | No, skills reload on `/clear` |
|
|
| **Tool restrictions** | `allowed-tools` (experimental) | `allowed-tools` (functional) |
|
|
| **Built-in creator** | `$skill-creator` | Manual or via outfitter plugin |
|
|
| **Debug mode** | Log files | `claude --debug` |
|
|
|
|
## Quick Reference
|
|
|
|
```bash
|
|
# Check skills feature is enabled
|
|
codex features list
|
|
|
|
# Find all skills
|
|
find ~/.codex/skills .codex/skills -name "SKILL.md" 2>/dev/null
|
|
|
|
# Validate skill
|
|
skills-ref validate ./my-skill
|
|
|
|
# Check logs for errors
|
|
cat ~/.codex/log/codex-tui.log | grep -i skill
|
|
|
|
# Invoke skill explicitly
|
|
# In Codex prompt: $skill-name do something
|
|
```
|
|
|
|
## Sources
|
|
|
|
- [Codex Skills Overview](https://developers.openai.com/codex/skills)
|
|
- [Create Skills Guide](https://developers.openai.com/codex/skills/create-skill)
|
|
- [AGENTS.md Documentation](https://developers.openai.com/codex/guides/agents-md)
|
|
- [Agent Skills Specification](https://agentskills.io/specification)
|
|
- [Codex Configuration Reference](https://developers.openai.com/codex/config-reference)
|