📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,255 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user