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

> Easily list available OpenAI skills using the list-skills.py utility. Compare remote and local skills outputting in plain text or JSON. Query GitHub for curated tools.

- Repository: [OpenAI/skills](https://github.com/openai/skills)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Run the [`list-skills.py`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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:

```bash
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.

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

```

The JSON structure includes installation status:

```json
[
  {"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:

```bash
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:

```bash
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`](https://github.com/openai/skills/blob/main/list-skills.py).
- **Zero Dependencies**: The script requires only Python's standard library and uses [`github_utils.py`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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.