YouTip

Skills are an extension mechanism of Codex CLI that allows you to create custom workflows and automate tasks. Through skills, you can define how Codex behaves in specific scenarios.\n\n* * *\n\n## What Are Skills?\n\nA skill is a configurable behavior pattern that tells Codex how to handle specific types of tasks. You can create your own skills to:\n\n\n\n* Automate common development tasks\n* Define domain-specific processing workflows\n* Customize code review standards\n* Create project-specific templates and rules\n\n> The skill system allows Codex to adapt to different project and workflow requirements, like having a dedicated development assistant for your team.\n\n* * *\n\n## Skill Directories\n\nCodex loads skills from the following locations:\n\n| Location | Description |\n| --- | --- |\n| `~/.codex/skills/` | Global skill directory, available to all projects |\n| `{project directory}/.codex/skills/` | Project-level skill directory |\n| `Configured directory` | Specified via `skills.directory` in config.toml |\n\n### Configuring Skill Directories\n\n## Custom Skill Directory\n\n```toml\n\nenabled = true\ndirectory = "~/my-codex-skills"\n\n* * *\n\n## Skill File Structure\n\nEach skill is a separate folder containing the following files:\n\nskill-name/\n├── skill.md # Skill definition file (required)\n└── (optional auxiliary files)\n\n### skill.md File Format\n\n## Skill Definition Example\n\n---\n\n name: Code Review\n\n description: Perform deep code review and provide improvement suggestions\n\n trigger: /review\n\n ---\n\n# Code Review Skill\n\nWhen a user requests a code review, the following steps are executed:\n\n## Review Criteria\n\n1. Code readability\n\n2. Performance issues\n\n3. Security vulnerabilities\n\n4. Adherence to best practices\n\n5. Test coverage\n\n## Output Format\n\nProvide the following structured report:\n\n- List of issues (sorted by severity)\n\n- Improvement suggestions\n\n- Code rating (1-10)\n\n* * *\n\n## Skill Metadata\n\nEach skill file must begin with metadata in YAML format:\n\n| Field | Type | Description | Required |\n| --- | --- | --- | --- |\n| `name` | string | Skill name | Yes |\n| `description` | string | Skill description | Yes |\n| `trigger` | string | Trigger keyword | No |\n\n> When your input matches a skill's trigger, Codex will automatically use that skill to process the task.\n\n* * *\n\n## Creating Custom Skills\n\nLet's create a simple skill as an example:\n\n### Step 1: Create Skill Directory\n\n## Create Skill Folder\n\n```bash\nmkdir -p ~/.codex/skills/GenerateTest\n\n### Step 2: Write Skill Definition\n\n## Create skill.md\n\n```markdown\n---\nname: Generate Tests\ndescription: Generate unit tests for code\ntrigger: test\n---\n\n# Generate Tests Skill\n\nWhen a user requests to generate tests, the following steps are executed:\n\n## Steps\n\n1. Analyze existing code functionality\n\n2. Identify edge cases that need testing\n\n3. Choose appropriate testing framework\n\n4. Generate test cases\n\n## Testing Standards\n\n- Coverage should include normal cases, edge cases, and error cases\n\n- Each test case should be independent, not relying on execution order of other tests\n\n- Use clear test function names\n\n## Output Format\n\nGenerate runnable test code with necessary test data.\n\n### Step 3: Using the Skill\n\nNow, when you input something related to "test", Codex will automatically use this skill:\n\n## Triggering the Skill\n\n```text\n# These inputs will trigger the "Generate Tests" skill\n\nHelp me generate tests for this function\n\nPlease test this module\n\n* * *\n\n## Built-in Skills\n\nCodex comes with several commonly used skills:\n\n| Skill Name | Trigger Words | Description |\n| --- | --- | --- |\n| **Code Review** | review, Review | Perform code review and provide improvement suggestions |\n| **Debugging** | debug, Debugging | Help locate and fix issues |\n| **Refactoring** | refactor, Refactor | Optimize code structure without changing functionality |\n| **Documentation** | doc, Documentation | Generate code documentation |\n\n> You can override built-in skills' behaviors to create versions tailored to your project needs.\n\n* * *\n\n## Skill Priority\n\nWhen multiple skills match, Codex selects based on the following priority:\n\n1. Exact match (identical trigger word)\n2. Partial match (input contains trigger word)\n3. Semantic match (AI determines relevance)\n\n### Forcing Specific Skills\n\nYou can force a specific skill using slash commands:\n\n## Force Using a Skill\n\n```text\n# Using skill command\n\n@skill-name your task description\n\n* * *\n\n## Advanced Skill Configuration\n\n### Conditional Triggers\n\nYou can configure skills to trigger under certain conditions:\n\n## Conditional Trigger Example\n\n```markdown\n---\nname: Python Skill\ndescription: Python project-specific handling\ntrigger: python\nwhen:\n file_pattern: "*.py"\n directory: "src/"\n---\n\n# Python Project Skill\n\nThis skill only applies when processing Python files.\n\n### Multi-step Tasks\n\nSkills can define complex multi-step processes:\n\n## Multi-step Skill\n\n```markdown\n---\nname: Full Feature Development\ndescription: Complete workflow from requirement to implementation\ntrigger: develop feature\n---\n\n# Full Feature Development Process\n\n## Phase 1: Requirements Analysis\n\n- Understand feature requirements\n\n- Identify edge cases\n\n- Design data structures\n\n## Phase 2: Design\n\n- Design function/class structure\n\n- Define interfaces\n\n- Select algorithms\n\n## Phase 3: Implementation\n\n- Write code\n\n- Add comments\n\n- Write documentation\n\n## Phase 4: Testing\n\n- Write unit tests\n\n- Verify edge cases\n\n- Check coverage\n\n## Phase 5: Commit\n\n- Create Git commit\n\n- Write commit message\n\n* * *\n\n## Best Practices for Skills\n\n### Naming Conventions\n\n* Use clear and descriptive names\n* Names should reflect the skill’s functionality\n* Avoid Chinese names (may cause encoding issues)\n\n### Trigger Word Selection\n\n* Choose commonly used keywords\n* Avoid overly broad trigger words\n* Consider natural user expressions\n\n### Skill Granularity\n\n* Keep skills focused on one responsibility\n* One skill solves one type of problem\n* Complex workflows can be achieved through skill combinations\n\n> A good skill should make users feel like "Codex understands my needs" rather than requiring them to learn special syntax.\n\n* * *\n\n## Managing Skills\n\n### Listing Available Skills\n\n## View Skill List\n\n```text\n# In Codex, enter\n\n/skills\n\n### Disabling Skills\n\nIf you don't want to use a particular skill, you can delete its corresponding file or move it to another directory.\n\n### Updating Skills\n\nAfter modifying a skill file, restart Codex for changes to take effect.\n\n* * *\n\n## Skill Sample Library\n\nOpenAI provides some pre-built skills for reference and use:\n\nVisit the GitHub repository for more examples: [https://github.com/openai/codex/tree/main/skills](https://github.com/openai/codex/tree/main/skills)\n\n* * *\n\n## Common Issues\n\n### Q: Why isn’t the skill triggering?\n\nCheck if the metadata format in the skill file is correct, ensure the YAML header is properly formatted and the file ends with `.md`.\n\n### Q: How do I debug skills?\n\nUse the `/debug` command in Codex to view detailed information about skill matching.\n\n### Q: Will skills affect Codex's normal behavior?\n\nSkills only provide guidelines; Codex still makes independent judgments. If a skill is misconfigured, Codex will fall back to default behavior.