Codex: Codex Agent Skills
Last updated: 2026-08-31
Agent Skills give Codex domain-specific expertise, similar to professional certifications for humans.
📋 Prerequisites: Understanding Codex basic operations and configuration
1. What You Will Learn
- Agent Skills concepts
- Built-in Skills
- Custom Skills
- Skills marketplace
2. What Are Agent Skills
Agent Skills are Codex's capability extension modules. Each Skill encapsulates domain-specific knowledge and workflows.
| Dimension | Description |
|---|---|
| Definition | Domain-specific capability package |
| Contents | System prompt + tool calls + workflow |
| Format | Markdown file |
| Location | .codex/skills/ directory |
3. Built-in Skills
Codex includes several commonly used Skills:
| Skill | Capability | Best For |
|---|---|---|
| code-review | Code review | PR review |
| debug | Debug & fix | Bug fixing |
| test-gen | Test generation | Supplementing tests |
| doc-gen | Documentation generation | API docs |
| refactor | Refactoring | Code optimization |
| security | Security scanning | Security audit |
(1) Using Built-in Skills
TEXT
📖 Display only
> /skill code-review
> Review the code quality of src/auth.ts
> /skill debug
> Fix TypeError: Cannot read property 'id' of undefined
▶ Example 1: Alice Uses Built-in Skills
TEXT
📖 Display only
# Alice uses the security Skill for a security audit
> /skill security
> Scan the entire project for security vulnerabilities
# Output:
# 🔴 [Critical] src/auth.ts:45 - Hardcoded secret key
# 🟡 [Medium] src/api.ts:23 - SQL concatenation not parameterized
# 🟢 [Low] src/utils.ts:12 - Missing input validation
4. Custom Skills
(1) Create a Skill File
MARKDOWN
<!-- .codex/skills/react-component.md -->
# React Component Generator
## Role
You are a React component development expert, proficient in TypeScript and modern React patterns.
## Rules
- Use functional components
- Use TypeScript type annotations
- Define Props with interface
- Use CSS Modules or Tailwind
- Include Storybook story
- Include unit tests
## Workflow
1. Analyze component requirements
2. Define Props interface
3. Implement component logic
4. Add styles
5. Create Storybook story
6. Write unit tests
7. Verify TypeScript compilation
## Output Format
- Component file: src/components/ComponentName.tsx
- Style file: src/components/ComponentName.module.css
- Story file: src/components/ComponentName.stories.tsx
- Test file: src/components/ComponentName.test.tsx
(2) Using a Custom Skill
TEXT
📖 Display only
> /skill react-component
> Create a DatePicker component with date range selection support
▶ Example 2: Bob Creates a Custom Skill
MARKDOWN
<!-- .codex/skills/api-endpoint.md -->
# API Endpoint Generator
## Role
You are a FastAPI endpoint development expert.
## Rules
- Use Pydantic models for request/response validation
- All endpoints include error handling
- Use dependency injection
- Include Swagger documentation
- Write pytest tests
## Template
Reference src/api/templates/standard_endpoint.py
## Workflow
1. Define Pydantic request model
2. Define Pydantic response model
3. Implement endpoint logic
4. Add error handling
5. Write tests
6. Ensure pytest passes
5. Skills Management
(1) List Skills
TEXT
📖 Display only
/skills list
(2) View Skill Details
TEXT
📖 Display only
/skills info code-review
(3) Enable/Disable Skills
TEXT
📖 Display only
/skills enable react-component
/skills disable doc-gen
(4) Install from Marketplace
TEXT
📖 Display only
/skills install graphql-api
6. Skills Best Practices
| Practice | Description |
|---|---|
| Single Domain | Each Skill covers only one domain |
| Include Templates | Provide code templates as references |
| Clear Workflow | Define explicit execution steps |
| Include Verification | Specify how to verify output |
| Iterate Continuously | Improve Skills based on usage feedback |
❓ FAQ
Q What's the difference between Skills and AGENTS.md?
A AGENTS.md is project-level rules (applies to all tasks); Skills are optional capability extensions (activated on demand).
Q Can I share Skills?
A Yes. Commit Skill files to the repository and team members automatically get them. You can also publish to the Skills marketplace.
Q Do Skills increase token consumption?
A Yes. Skill system prompts occupy context window space, but are more efficient than repeatedly describing without a Skill.
Q Can built-in Skills be modified?
A Not directly, but you can create a custom Skill with the same name to override the built-in version.
Q Can one task use multiple Skills?
A Not recommended. Each task should use only one Skill to avoid instruction conflicts.
📖 Summary
- Skills are Codex's capability extension modules
- Built-in Skills: code-review / debug / test-gen / doc-gen / refactor / security
- Custom Skills: placed in the
.codex/skills/directory - Skills contain: role definition + rules + workflow + output format
- Single domain, include templates, clear workflow
📝 Exercises
- Basic (⭐): Complete a task using a built-in Skill, compare results without a Skill.
- Intermediate (⭐⭐): Create a custom Skill for your common development scenarios.
- Advanced (⭐⭐⭐): Create a complete Skills library covering all your team's development scenarios.
