Skip to main content
Skills are specialized capabilities that extend Codex’s functionality. They can be user-defined, project-scoped, or shared across workspaces.

​
List Skills

Fetch available skills for one or more working directories.

​
Method

skills/list

​
Parameters

​
cwds
string[]
default:[]
Working directories to scan for skills (defaults to current session cwd if empty)
​
forceReload
boolean
default:false
Bypass the skills cache and re-scan from disk
​
perCwdExtraUserRoots
object[]
Additional roots to scan as user-scoped skills for specific cwds

​
Response

​
data
SkillsListEntry[]
Array of skills grouped by working directory

​
Skill Object

​
name
string
Skill identifier (e.g., skill-creator)
​
description
string
Brief skill description
​
enabled
boolean
Whether the skill is enabled in config
​
interface
SkillInterface
UI metadata for the skill

​
Example

{
  "method": "skills/list",
  "id": 25,
  "params": {
    "cwds": ["/Users/me/project", "/Users/me/other-project"],
    "forceReload": true
  }
}

​
Invoking a Skill

To invoke a skill, include $<skill-name> in the text input and add a skill input item. 
{
  "method": "turn/start",
  "id": 101,
  "params": {
    "threadId": "thr_123",
    "input": [
      {
        "type": "text",
        "text": "$skill-creator Add a new skill for triaging flaky CI and include step-by-step usage."
      },
      {
        "type": "skill",
        "name": "skill-creator",
        "path": "/Users/me/.codex/skills/skill-creator/SKILL.md"
      }
    ]
  }
}
If you omit the skill input item, the model will still parse $<skill-name> and try to locate the skill, but this adds latency. Always include the skill item when possible.

​
Enable or Disable a Skill

Use skills/config/write to enable or disable a skill by path.

​
Method

skills/config/write

​
Parameters

​
path
string
required
Absolute path to the skill’s SKILL.md file
​
enabled
boolean
required
Whether the skill should be enabled

​
Response

​
{}
object
Empty object on success

​
Example

{
  "method": "skills/config/write",
  "id": 26,
  "params": {
    "path": "/Users/me/.codex/skills/skill-creator/SKILL.md",
    "enabled": false
  }
}

​
Skill Scopes

Skills are discovered from multiple scopes:

Built-in

Bundled with CodexLocation: Codex installation directory

User

User-level skillsLocation: ~/.codex/skills/

Project

Project-specific skillsLocation: {cwd}/.codex/skills/

​
Skill Structure

A skill is defined by a SKILL.md file containing: 
# Skill Name

Brief description of what the skill does.

## Instructions

Detailed instructions for the agent on how to use this skill.

## Examples

Example usage scenarios.

## Dependencies

Required tools, packages, or configurations.
Optional companion files:
  • icon.svg - Small icon
  • icon-large.svg - Large icon
  • config.toml - Skill configuration (display name, brand color, default prompt)

​
Remote Skills (Under Development)

The remote skills API is under development. Do not call from production clients yet.

​
List Remote Skills

skills/remote/list
List public remote skills from the skill directory.

​
Export Remote Skill

skills/remote/export
Download a remote skill by hazelnutId into the user’s skills directory.

​
Next Steps

Apps

Discover and use connector apps

Turns

Start a turn with skill invocation