# How to Submit a New Skill to OpenAI: Complete Contributor Guide

> Learn how to submit a new skill to OpenAI by forking the repository, scaffolding your skill, validating configuration, and opening a pull request to the official openai/skills repo.

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

---

**Submitting a new skill to OpenAI requires forking the repository, scaffolding your skill using the [`init_skill.py`](https://github.com/openai/skills/blob/main/init_skill.py) script, validating the configuration with [`quick_validate.py`](https://github.com/openai/skills/blob/main/quick_validate.py), and opening a pull request targeting the `skills/.curated` directory.**

The `openai/skills` repository hosts the Agent Skills system that powers OpenAI Codex. Submitting a new skill to OpenAI involves creating a self-contained package with YAML front-matter, markdown instructions, and optional deterministic scripts that Codex can interpret and execute. This guide provides the exact commands, file paths, and validation steps required to create and contribute a production-ready skill.

## Understanding the OpenAI Skills Architecture

Before submitting a new skill to OpenAI, you must understand how the repository organizes capabilities. The `openai/skills` repository contains three top-level groups:

- **`.system/`** – Core installer and creator utilities pre-installed in Codex.
- **`.curated/`** – Production-ready skills available to all users via the skill installer.
- **`.experimental/`** – Work-in-progress skills not automatically listed in the skill picker.

Each skill is a self-contained folder within these directories. According to the source code in [`skills/.system/skill-creator/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/SKILL.md), a complete skill consists of the following components:

| Component | Purpose | Example Location |
|-----------|---------|------------------|
| [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) | YAML front-matter plus Markdown instructions that Codex reads when triggered | `skills/.curated/<skill-name>/SKILL.md` |
| [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml) | UI metadata including display name and description for the skill picker | `skills/.curated/<skill-name>/agents/openai.yaml` |
| `scripts/` | Optional deterministic code executed without loading into the model's context | `skills/.curated/<skill-name>/scripts/` |
| `references/` | Optional documentation loaded only when needed | `skills/.curated/<skill-name>/references/` |
| `assets/` | Templates, icons, and other output files | `skills/.curated/<skill-name>/assets/` |

## Prerequisites for Submitting a New Skill

To begin submitting a new skill to OpenAI, ensure your environment meets these requirements:

- **Git** – Ability to fork and push to a personal repository.
- **Python 3.9+** – The creator scripts require Python 3.9 or newer.
- **Access to `$CODEX_HOME`** (optional) – Required only for local testing with `$skill-installer`.
- **Familiarity with the skill format** – Review the Skill Creator guide at [`skills/.system/skill-creator/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/SKILL.md).

Verify your Python version:

```bash
python --version

```

## Step-by-Step Process for Submitting a New Skill to OpenAI

The following workflow details the exact process for submitting a new skill to OpenAI, from initial scaffolding to final pull request.

### Step 1: Fork the Repository

Create a personal fork of the `openai/skills` repository and clone it locally:

```bash
git clone https://github.com/<your-username>/skills.git
cd skills

```

This fork provides an isolated branch where you can push commits without affecting the upstream repository.

### Step 2: Scaffold Your Skill

Use the **Skill Initializer** script located at [`skills/.system/skill-creator/scripts/init_skill.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/scripts/init_skill.py) to generate the required folder structure:

```bash
python -m skills/.system/skill-creator/scripts/init_skill.py \
    my-new-skill \
    --path skills/.curated \
    --resources scripts,references,assets \
    --examples

```

Parameters explained:

- `my-new-skill` – The folder name (must be lowercase and hyphenated).
- `--path skills/.curated` – Places the skill in the production-ready collection.
- `--resources` – Creates empty directories for `scripts/`, `references/`, and `assets/`.
- `--examples` – Adds placeholder files demonstrating typical content.

This script generates a ready-to-edit [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) and a minimal [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml).

### Step 3: Edit Skill Content

Modify the generated files to define your skill's behavior:

1. **Update [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md)** – Ensure the YAML front-matter contains accurate `name` and `description` fields. Codex uses these to determine when to invoke the skill. Add imperative instructions in the Markdown body.
2. **Configure [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml)** – Adjust the UI metadata for the skill picker.
3. **Populate `scripts/`** – Add deterministic code that executes without loading into the model's context.
4. **Add `references/`** – Include documentation that Codex loads only when needed.

Refer to the Skill Creator documentation at [`skills/.system/skill-creator/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/SKILL.md) for best-practice patterns including progressive disclosure and resource linking.

### Step 4: Validate Your Skill

Run the validation script to catch missing fields, naming violations, or malformed YAML:

```bash
python -m skills/.system/skill-creator/scripts/quick_validate.py \
    skills/.curated/my-new-skill

```

The script at [`skills/.system/skill-creator/scripts/quick_validate.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/scripts/quick_validate.py) checks for:

- Presence of [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md).
- Valid YAML front-matter with required `name` and `description` fields.
- Skill folder name matching the `name` field (maximum 64 characters).

If errors appear, edit the files and re-run until the script outputs **"Skill validation passed."**

### Step 5: Test Locally (Optional)

If you have a Codex development environment with `$CODEX_HOME` configured, test your skill locally:

```bash
$skill-installer my-new-skill

```

This invokes the installer script at [`skills/.system/skill-installer/scripts/install-skill-from-github.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/scripts/install-skill-from-github.py) to load your skill from the local `.curated` directory. Restart Codex to verify the skill appears in the skill picker and functions correctly.

### Step 6: Commit and Push

Create a feature branch and push your changes:

```bash
git checkout -b add-my-new-skill
git add skills/.curated/my-new-skill
git commit -m "Add my-new-skill: <short description>"
git push origin add-my-new-skill

```

### Step 7: Open a Pull Request

1. Navigate to your fork on GitHub.
2. Click **"New pull request"**, targeting `openai/skills:main`.
3. Provide a concise description of the skill's purpose and usage.
4. Add the **"skill"** label if you have maintainer permissions.

OpenAI contributors will review your submission. Once approved and merged, your skill becomes available to all Codex users via `$skill-installer`.

## Key Files and Scripts Reference

When submitting a new skill to OpenAI, you will interact with these specific files:

| File Path | Purpose |
|-----------|---------|
| [`skills/.system/skill-creator/scripts/init_skill.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/scripts/init_skill.py) | Scaffolds new skill folders with required structure |
| [`skills/.system/skill-creator/scripts/quick_validate.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/scripts/quick_validate.py) | Validates YAML front-matter and naming constraints |
| [`skills/.system/skill-creator/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/SKILL.md) | Comprehensive guide on skill creation best practices |
| [`skills/.system/skill-installer/scripts/install-skill-from-github.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/scripts/install-skill-from-github.py) | Installs skills locally for testing |
| `skills/.curated/<skill-name>/SKILL.md` | Your skill's main definition file with front-matter |
| `skills/.curated/<skill-name>/agents/openai.yaml` | UI metadata for the Codex skill picker |

## Summary

Submitting a new skill to OpenAI follows a standardized workflow designed to ensure quality and consistency across the Codex ecosystem:

- Fork the `openai/skills` repository and clone it locally.
- Scaffold your skill using [`init_skill.py`](https://github.com/openai/skills/blob/main/init_skill.py) with the `--path skills/.curated` flag.
- Edit [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) with accurate YAML front-matter and imperative instructions.
- Validate your submission using [`quick_validate.py`](https://github.com/openai/skills/blob/main/quick_validate.py) before committing.
- Test locally with `$skill-installer` if you have Codex development access.
- Submit a pull request targeting `openai/skills:main` for review.

Once merged, your skill becomes immediately available to all Codex users through the skill installer.

## Frequently Asked Questions

### What is the difference between `.curated` and `.experimental` skill directories?

The `.curated` directory contains production-ready skills that undergo review and are automatically available to all Codex users via `$skill-installer`. The `.experimental` directory holds work-in-progress skills that are not automatically listed in the skill picker and may not meet production standards. When submitting a new skill to OpenAI, you should target `skills/.curated` unless specifically instructed otherwise.

### How does the [`init_skill.py`](https://github.com/openai/skills/blob/main/init_skill.py) script structure a new skill?

The [`init_skill.py`](https://github.com/openai/skills/blob/main/init_skill.py) script located at [`skills/.system/skill-creator/scripts/init_skill.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/scripts/init_skill.py) generates a complete skill folder structure including [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) with YAML front-matter, [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml) for UI metadata, and optional directories for `scripts/`, `references/`, and `assets/` based on the `--resources` flag. It ensures the skill name is lowercase and hyphenated, creating a standardized foundation that passes initial validation.

### What validation does [`quick_validate.py`](https://github.com/openai/skills/blob/main/quick_validate.py) perform?

The [`quick_validate.py`](https://github.com/openai/skills/blob/main/quick_validate.py) script at [`skills/.system/skill-creator/scripts/quick_validate.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/scripts/quick_validate.py) checks for the presence of [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md), validates that the YAML front-matter contains required fields (`name` and `description`), and verifies that the skill folder name matches the `name` field with a maximum of 64 characters. It catches naming violations and malformed YAML before submission, outputting "Skill validation passed" when all checks succeed.

### Can I test my skill before submitting a pull request?

Yes, if you have access to a Codex development environment with `$CODEX_HOME` configured, you can test your skill locally using the `$skill-installer` command followed by your skill name. This invokes the installer script at [`skills/.system/skill-installer/scripts/install-skill-from-github.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/scripts/install-skill-from-github.py) to load your skill from the local `.curated` directory. After installation, restart Codex to verify the skill appears in the skill picker and functions correctly before opening your pull request.