# How to Contribute to OpenAI Skills: The Complete Developer Workflow

> Learn how to contribute to OpenAI Skills. Follow our developer workflow to scaffold, validate, and submit your own skills to the openai/skills repository.

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

---

**To contribute to OpenAI Skills, scaffold a new skill using [`init_skill.py`](https://github.com/openai/skills/blob/main/init_skill.py), validate it with [`quick_validate.py`](https://github.com/openai/skills/blob/main/quick_validate.py), and submit a pull request following the repository's contribution guidelines.**

OpenAI Skills is a catalog of self-contained extensions that enhance the Codex agent with reusable knowledge and automation. When you contribute to OpenAI skills, you add specialized capabilities—ranging from API integrations to utility scripts—that other developers can install and invoke directly within their Codex environment.

## Understanding the OpenAI Skills Repository Structure

Before you contribute to OpenAI skills, familiarize yourself with the repository layout defined in the `openai/skills` codebase.

### Core System Components

The repository contains two primary system directories under `skills/.system/`:

- **`skill-creator/`** – Provides authoring tools and validation. Key files include [`scripts/init_skill.py`](https://github.com/openai/skills/blob/main/scripts/init_skill.py) for scaffolding and [`scripts/quick_validate.py`](https://github.com/openai/skills/blob/main/scripts/quick_validate.py) for local validation.
- **`skill-installer/`** – Handles discovery and installation. The [`scripts/list-skills.py`](https://github.com/openai/skills/blob/main/scripts/list-skills.py) enumerates available skills, while [`scripts/install-skill-from-github.py`](https://github.com/openai/skills/blob/main/scripts/install-skill-from-github.py) manages downloads and sparse-checkout fallbacks.

### Anatomy of a Skill Folder

Every skill resides in a self-contained folder (typically under `skills/.curated/` for production-ready contributions). The minimum requirement is a [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) file with YAML front-matter containing `name` and `description` fields.

Optional subdirectories include:

- `agents/` – UI metadata (e.g., [`openai.yaml`](https://github.com/openai/skills/blob/main/openai.yaml))
- `scripts/` – Executable code (Python, Bash)
- `references/` – Documentation loaded on demand
- `assets/` – Binary or template files

## Step-by-Step Workflow to Contribute to OpenAI Skills

Follow this workflow to ensure your contribution meets the repository's technical standards.

### 1. Review Contribution Guidelines

Start by reading [`contributing.md`](https://github.com/openai/skills/blob/main/contributing.md) in the repository root. This document outlines community values, security reporting procedures, and pull request etiquette required to contribute to OpenAI skills.

### 2. Initialize a New Skill

Use the helper script to scaffold your skill directory:

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

```

This command creates:

- A normalized folder name (lowercase, hyphen-case, ≤64 characters)
- A starter [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) with TODO placeholders
- An [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml) file for UI metadata
- Example files in each requested resource directory

### 3. Configure SKILL.md and Metadata

Edit [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) to replace TODO sections with actual instructions. Ensure the YAML front-matter adheres to these constraints:

- `name`: lowercase, hyphen-case, maximum 64 characters
- `description`: concise summary, maximum 1024 characters, no angle brackets

Update [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml) to define how the skill appears in the Codex UI.

### 4. Add Scripts, References, and Assets

Populate the subdirectories created in step 2:

- Place executable scripts in `scripts/` and ensure they have proper permissions (`chmod +x`)
- Add long-form documentation to `references/` for complex logic that Codex should load on demand
- Store binary templates or configuration files in `assets/`

Reference these resources from the body of [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) using relative paths.

### 5. Validate Your Skill Locally

Run the validation script before submitting:

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

```

The validator checks:

- YAML front-matter syntax
- Name conventions (lowercase, hyphen-case, ≤64 chars)
- Description length (≤1024 chars) and character restrictions

A successful validation outputs `Skill is valid!`. Fix any reported errors to prevent CI failures.

### 6. Test and Submit a Pull Request

Test your skill by running any scripts and verifying references load correctly. Then open a Pull Request against the `main` branch:

- Follow the PR template if provided
- Describe the skill's purpose and any UI changes
- Note that CI will automatically run [`quick_validate.py`](https://github.com/openai/skills/blob/main/quick_validate.py) on your submission

Once merged, your skill becomes available in the curated set. Users can install it via `$skill-installer <skill-name>`.

## How the Skill Installer Works

Understanding the installation mechanism helps you design skills that integrate seamlessly with Codex. The `$skill-installer` command wraps two Python scripts in `skills/.system/skill-installer/scripts/`:

- **[`list-skills.py`](https://github.com/openai/skills/blob/main/list-skills.py)** – Enumerates available skills from a specified path (default: `skills/.curated`). It supports JSON output (`--format json`) for programmatic access.
- **[`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py)** – Downloads skills from public GitHub repositories. It uses sparse-checkout as a fallback when authentication is required, respecting the `$CODEX_HOME` environment variable for installation paths.

When users invoke `$skill-installer <skill-name>`, the system checks `$CODEX_HOME/skills/<skill-name>` to prevent duplicate installations. After a successful install, Codex must be restarted to load the new skill.

## Summary

- **OpenAI Skills** are self-contained folders that extend Codex with reusable knowledge and automation.
- To **contribute to OpenAI skills**, use [`init_skill.py`](https://github.com/openai/skills/blob/main/init_skill.py) to scaffold, [`quick_validate.py`](https://github.com/openai/skills/blob/main/quick_validate.py) to verify, and submit a PR against `main`.
- Every skill requires a [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) with valid YAML front-matter (name ≤64 chars, description ≤1024 chars).
- Optional subdirectories (`scripts/`, `references/`, `assets/`, `agents/`) organize code, docs, and UI metadata.
- The skill installer ([`list-skills.py`](https://github.com/openai/skills/blob/main/list-skills.py), [`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py)) enables distribution and local installation.

## Frequently Asked Questions

### What is the minimum required structure for an OpenAI skill?

The only mandatory file is [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) placed in a folder named with lowercase, hyphen-case conventions (maximum 64 characters). This file must contain YAML front-matter with `name` and `description` fields. While optional, most production skills include an [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml) file for UI metadata and a `scripts/` directory for executable code.

### How do I validate my skill before submitting a PR?

Run the local validator located at [`skills/.system/skill-creator/scripts/quick_validate.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/scripts/quick_validate.py) against your skill folder. This script checks YAML syntax, enforces naming conventions (lowercase, hyphen-case, ≤64 characters), and verifies that the description does not exceed 1024 characters or contain angle brackets. The CI pipeline runs this same validator automatically when you open a pull request.

### Can I install skills from external GitHub repositories?

Yes. 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) supports installing skills from any public GitHub repository. It attempts a standard download first, then falls back to `git sparse-checkout` when authentication is required. The script respects the `$CODEX_HOME` environment variable to determine the installation directory, placing skills under `$CODEX_HOME/skills/<skill-name>`.

### What naming conventions must I follow when contributing to OpenAI skills?

Skill names must use lowercase, hyphen-case format (e.g., `my-new-skill`) and cannot exceed 64 characters. The `name` field in [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) front-matter must follow these same rules. Descriptions are limited to 1024 characters and must not contain angle brackets (`<` or `>`). These constraints ensure compatibility with the Codex UI and the validation tooling.