csh
/
playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
playbook/outfitter-agents/plugins/outfitter/skills/skills-dev/references/codex.md

6.5 KiB
Raw Blame History

Codex CLI Implementation

Codex CLI-specific implementation details for Agent Skills. For cross-platform concepts, see the main 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:

# 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
# 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

# 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:

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:

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:

codex features list
# Look for: skills ... true

Verify file location:

# 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:

# 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

# 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