Creating and Using Codex Skills
Codex does more than generate code. The skills system lets you extend its capabilities by bundling instructions, resources, and scripts into reusable packages. In this lesson, you will learn how to create skills that make Codex work exactly the way your team needs.
What You Will Learn
- What Codex skills are and how they work
- How to use built-in and community skills
- How to create your own custom skills
- How skills bundle instructions, resources, and scripts together
- Practical examples of skills for common workflows
What Are Codex Skills?
A skill is a package that teaches Codex how to perform a specific type of task. Think of it as a set of instructions, templates, and tools bundled together so you do not have to explain the same thing every time.
Without skills, you might need to write a detailed prompt every time you want Codex to follow a specific pattern:
Use the repository's ESLint config, follow the existing naming conventions,
put tests in __tests__/ directories, use the factory pattern for test data,
mock external services using jest.mock, and make sure every test file imports
from the test helpers module...
With a skill, all of that is captured once and reused automatically:
codex --skill our-test-patterns "write tests for the notification service"
Anatomy of a Skill
A Codex skill typically includes:
Instructions
Natural language guidance that tells Codex how to approach tasks. For example, a code review skill might include:
- Check for security vulnerabilities (SQL injection, XSS, CSRF)
- Verify error handling is present for all async operations
- Ensure all public functions have documentation comments
- Flag any hardcoded secrets or credentials
Resources
Files, templates, or reference material that the skill provides to Codex. A deployment skill might include:
- A Dockerfile template
- Kubernetes manifest templates
- Environment variable checklists
- Deployment runbook steps
Scripts
Automation scripts that the skill can execute. A database migration skill might include:
- A script to generate a migration file from schema changes
- A script to test the migration against a local database
- A rollback script for safety
Using Skills
Applying a Skill to a Task
You can apply a skill when launching a Codex task:
codex --skill code-review "review the changes in the last commit"
Or in Codex Cloud, you can attach skills to tasks when you create them.
Listing Available Skills
To see what skills are available:
codex skills list
This shows both built-in skills and any custom skills you have created or installed.
Creating Your Own Skills
Creating a custom skill starts with defining what you want Codex to do consistently. Here is a step-by-step process:
Step 1: Identify the Pattern
What task do you repeatedly ask Codex to do, and what instructions do you always include? Common examples:
- Writing tests with specific patterns
- Creating API endpoints with standard error handling
- Generating documentation in a specific format
- Performing code reviews with team-specific criteria
Step 2: Write the Skill Definition
A skill is defined in a configuration file that specifies instructions, resources, and optionally scripts. Here is a conceptual example of a test-writing skill:
Skill: team-tests
Description: Write tests following our team's conventions
Instructions:
- Place test files in __tests__/ adjacent to the source file
- Use describe/it blocks with clear, readable names
- Follow the Arrange-Act-Assert pattern
- Use factory functions from test/factories/ for test data
- Mock external services using jest.mock at the top of the file
- Include both success and error cases for every function
- Test edge cases: empty inputs, null values, maximum lengths
Resources:
- test/factories/README.md (explains available factories)
- test/helpers/README.md (explains test utility functions)
Step 3: Test the Skill
Apply the skill to a task and verify that Codex follows the instructions correctly:
codex --skill team-tests "write tests for src/services/email.js"
Review the output. If Codex misses any conventions, refine the skill instructions.
Step 4: Share with Your Team
Once the skill works well, share it with your team so everyone benefits from consistent patterns.
Practical Skill Examples
Code Review Skill
Skill: security-review
Description: Review code for security issues
Instructions:
- Check for SQL injection vulnerabilities (parameterized queries required)
- Check for XSS risks in any HTML rendering
- Verify authentication and authorization on all endpoints
- Ensure sensitive data is not logged
- Check that API keys and secrets use environment variables
- Verify CORS configuration is appropriate
- Check for rate limiting on public endpoints
API Endpoint Skill
Skill: rest-endpoint
Description: Create REST API endpoints following team conventions
Instructions:
- Use Express router with the standard middleware chain
- Add request validation using Joi schemas
- Include try-catch with standardized error responses
- Add request logging with correlation IDs
- Return consistent response shapes: \{ data, error, meta \}
- Add JSDoc comments with request/response types
Documentation Skill
Skill: api-docs
Description: Generate API documentation
Instructions:
- Use OpenAPI 3.0 format
- Include request/response examples for every endpoint
- Document all possible error codes and their meanings
- Include authentication requirements
- Add rate limit information where applicable
Skills vs Prompt Templates
You might wonder how skills differ from simply saving prompt templates. The key differences are:
- Skills include resources that are automatically loaded into context
- Skills can execute scripts as part of the workflow
- Skills are composable — you can combine multiple skills for a single task
- Skills are versioned and shareable — they work across team members
Key Takeaways
- Skills extend Codex by bundling instructions, resources, and scripts into reusable packages
- Use skills to enforce consistent patterns across your team without repeating instructions
- Skills include three components: natural language instructions, reference resources, and automation scripts
- Create skills for any task you repeatedly ask Codex to do with specific conventions
- Share skills with your team for consistent code quality and patterns
- Skills are more powerful than simple prompt templates because they include resources and scripts