How to Contribute to OpenAI Skills: The Complete Developer Workflow

To contribute to OpenAI Skills, scaffold a new skill using init_skill.py, validate it with 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 for scaffolding and scripts/quick_validate.py for local validation.
• skill-installer/ – Handles discovery and installation. The scripts/list-skills.py enumerates available skills, while 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 file with YAML front-matter containing name and description fields.

Optional subdirectories include:

• agents/ – UI metadata (e.g., 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 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:

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 with TODO placeholders
• An agents/openai.yaml file for UI metadata
• Example files in each requested resource directory

3. Configure SKILL.md and Metadata

Edit 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 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 using relative paths.

5. Validate Your Skill Locally

Run the validation script before submitting:

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 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 – Enumerates available skills from a specified path (default: skills/.curated). It supports JSON output (--format json) for programmatic access.
• 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 to scaffold, quick_validate.py to verify, and submit a PR against main.
• Every skill requires a 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, 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 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 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 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 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 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.

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