Skills

Skill discovery and invocation

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

Show perCwdExtraUserRoots entry

cwd · string · required

Working directory path

extraUserRoots · string[] · required

Absolute paths to scan as user scope

Response

data · SkillsListEntry[]

Array of skills grouped by working directory

Show SkillsListEntry

cwd · string

Working directory

skills · SkillMetadata[]

Array of skill metadata

errors · SkillErrorInfo[]

Skill loading errors

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

Show SkillInterface

displayName · string

Human-readable skill name

shortDescription · string

Short description for UI

iconSmall · string

Small icon filename

iconLarge · string

Large icon filename

brandColor · string

Hex color code (e.g., #111111)

defaultPrompt · string

Default prompt text

Example

Request

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

{
  "id": 25,
  "result": {
    "data": [
      {
        "cwd": "/Users/me/project",
        "skills": [
          {
            "name": "skill-creator",
            "description": "Create or update a Codex skill",
            "enabled": true,
            "interface": {
              "displayName": "Skill Creator",
              "shortDescription": "Create or update a Codex skill",
              "iconSmall": "icon.svg",
              "iconLarge": "icon-large.svg",
              "brandColor": "#111111",
              "defaultPrompt": "Add a new skill for triaging flaky CI."
            }
          },
          {
            "name": "code-review",
            "description": "Perform automated code review",
            "enabled": true,
            "interface": {
              "displayName": "Code Review",
              "shortDescription": "Automated code review",
              "iconSmall": "review.svg",
              "iconLarge": "review-large.svg",
              "brandColor": "#4A90E2",
              "defaultPrompt": "Review my recent changes"
            }
          }
        ],
        "errors": []
      },
      {
        "cwd": "/Users/me/other-project",
        "skills": [],
        "errors": []
      }
    ]
  }
}

Invoking a Skill

To invoke a skill, include $<skill-name> in the text input and add a skill input item.

turn/start with skill

{
  "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"
      }
    ]
  }
}

{
  "id": 101,
  "result": {
    "turn": {
      "id": "turn_500",
      "status": "inProgress",
      "items": [],
      "error": null
    }
  }
}

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

Request

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

{
  "id": 26,
  "result": {}
}

Skill Scopes

Skills are discovered from multiple scopes:

Built-in

Bundled with Codex

Location: Codex installation directory

User

User-level skills

Location: ~/.codex/skills/

Project

Project-specific skills

Location: {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