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

Submitting a new skill to OpenAI requires forking the repository, scaffolding your skill using the init_skill.py script, validating the configuration with 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, a complete skill consists of the following components:

Component	Purpose	Example Location
SKILL.md	YAML front-matter plus Markdown instructions that Codex reads when triggered	skills/.curated/<skill-name>/SKILL.md
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.

Verify your Python version:

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:

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 to generate the required folder structure:

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 and a minimal agents/openai.yaml.

Step 3: Edit Skill Content

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

1. Update 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 – 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 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:

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 checks for:

• Presence of 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:

$skill-installer my-new-skill

This invokes the installer script at 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:

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	Scaffolds new skill folders with required structure
skills/.system/skill-creator/scripts/quick_validate.py	Validates YAML front-matter and naming constraints
skills/.system/skill-creator/SKILL.md	Comprehensive guide on skill creation best practices
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 with the --path skills/.curated flag.
• Edit SKILL.md with accurate YAML front-matter and imperative instructions.
• Validate your submission using 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 script structure a new skill?

The init_skill.py script located at skills/.system/skill-creator/scripts/init_skill.py generates a complete skill folder structure including SKILL.md with YAML front-matter, 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 perform?

The quick_validate.py script at skills/.system/skill-creator/scripts/quick_validate.py checks for the presence of 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 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.

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