How to List Available Skills in OpenAI: Using the list-skills.py Utility

Run the list-skills.py script from the openai/skills repository to query GitHub for curated skills, compare them against your local installation, and output results in plain text or JSON format.

The openai/skills repository provides a curated collection of reusable capabilities for AI agents. To discover which skills are available and which are already installed on your system, the repository includes a dedicated utility script that interfaces directly with the GitHub API. Understanding how to list available skills in OpenAI helps you manage your agent's capabilities efficiently.

Where Skills Are Stored and How They Are Discovered

OpenAI Skills reside in the skills/.curated directory of the repository. Rather than maintaining a static index file, the listing mechanism relies on the GitHub Contents API to enumerate directories at runtime, ensuring you always see the most current collection without pulling repository updates.

The Skill Listing Script Architecture

The primary interface is skills/.system/skill-installer/scripts/list-skills.py. This self-contained script requires only the Python standard library and orchestrates API communication through helper functions defined in skills/.system/skill-installer/scripts/github_utils.py.

Building the GitHub API Request

The script constructs the query URL using github_api_contents_url(repo, path, ref), which formats the endpoint as https://api.github.com/repos/<repo>/contents/<path>?ref=<ref>. By default, it targets the skills/.curated path in the openai/skills repository on the default branch.

Authenticating and Fetching Data

The github_request(url, "codex-skill-list") function executes the GET request, injecting a User-Agent header and automatically detecting OAuth tokens from the GITHUB_TOKEN or GH_TOKEN environment variables to avoid API rate limits.

Parsing the Repository Contents

Inside _list_skills, the script decodes the JSON response and filters for entries where "type": "dir", treating each directory name as a skill identifier. Results are sorted alphabetically before processing.

Detecting Local Installations

The _installed_skills function scans the $CODEX_HOME/skills directory, defaulting to ~/.codex/skills if the environment variable is unset. Any directory found there is marked as installed in the final output.

Running the List Skills Command

Navigate to the repository root and execute the script directly.

Basic listing:

python3 skills/.system/skill-installer/scripts/list-skills.py

This outputs a numbered list:

1. security-ownership-map
2. spreadsheet
3. yeet

Working with JSON Output and Custom Sources

For programmatic integration, use the --format json flag to receive a structured array.

python3 skills/.system/skill-installer/scripts/list-skills.py --format json

The JSON structure includes installation status:

[
  {"name": "security-ownership-map", "installed": false},
  {"name": "spreadsheet", "installed": true},
  {"name": "yeet", "installed": false}
]

Querying Forks or Specific Branches

Override the default repository and reference using command-line arguments:

python3 skills/.system/skill-installer/scripts/list-skills.py \
    --repo myorg/skills-fork \
    --ref develop \
    --path skills/.curated

Configuring the Local Skills Directory

When running in containers or non-standard environments, set CODEX_HOME to change where the script looks for installed skills:

CODEX_HOME=/opt/codex python3 skills/.system/skill-installer/scripts/list-skills.py

Summary

• Storage Location: Curated skills live in skills/.curated and are enumerated via the GitHub API using list-skills.py.
• Zero Dependencies: The script requires only Python's standard library and uses github_utils.py for API handling.
• Authentication: Set GITHUB_TOKEN or GH_TOKEN to avoid API rate limits when querying.
• Local Detection: The script checks $CODEX_HOME/skills (default ~/.codex/skills) to determine installation status.
• Flexible Output: Choose between human-readable numbered lists or machine-readable JSON using the --format flag.

Frequently Asked Questions

Do I need to install any Python packages to run the list-skills script?

No. The list-skills.py script is self-contained and uses only the Python standard library. It relies on urllib for HTTP requests and json for parsing responses, with no external pip dependencies required.

How does the script determine which skills are already installed on my machine?

The _installed_skills function in list-skills.py scans the directory specified by the CODEX_HOME environment variable, defaulting to ~/.codex/skills if unset. Any subdirectory names found there are compared against the remote skill list and marked as installed in the output.

Can I use this script to list skills from a private fork of the openai/skills repository?

Yes. Provide your fork details using the --repo and --ref arguments. Ensure you have set the GITHUB_TOKEN or GH_TOKEN environment variable with a personal access token that has read access to your private repository, as the github_request function automatically includes this token in the API request headers.

Why does the script use the GitHub API instead of a local file list?

The script queries the GitHub Contents API via github_api_contents_url to ensure you always see the most current curated skills without needing to pull the latest repository changes. This dynamic approach allows listing skills from specific branches or forks without switching your local git context.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}