How to Fork the OpenAI Skills Repository: A Complete Guide

To fork the OpenAI skills repository, navigate to the GitHub page, click the Fork button to create your own copy, clone it locally, and use the built-in $skill-installer utility to test and manage skills from your fork.

The OpenAI skills repository is a collection of reusable, self-contained "skills" designed for Codex agents. Each skill includes a SKILL.md manifest and executable scripts. Forking this repository allows you to customize existing skills, develop new ones, and contribute back to the community while maintaining your own stable versions.

What Is the OpenAI Skills Repository?

The repository organizes capabilities into three distinct categories under the skills/ directory:

• skills/.system/skill-installer/ – Core utilities that enable Codex to list, download, and install skills directly from GitHub.
• skills/.curated/ – Production-ready skills (such as yeet and security-best-practices) that have been vetted for stability.
• skills/.experimental/ – Work-in-progress skills that are still under development.

Every skill follows a strict contract: it must contain a SKILL.md file describing prerequisites, usage workflows, and metadata, along with any scripts or assets required for execution.

Step-by-Step Guide to Fork the OpenAI Skills Repository

Fork via GitHub Web UI

1. Navigate to the official repository at https://github.com/openai/skills.
2. Click the Fork button in the upper-right corner.
3. Select your personal GitHub account or an organization as the destination.
4. GitHub will create https://github.com/<your-username>/skills as your independent copy.

Clone Your Fork Locally

Once forked, clone the repository to your local machine to begin development:

# Replace <your-username> with your GitHub handle

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

Set Up the Development Environment

The repository requires no build step, but the installer scripts depend on Python 3.8 or higher. For development and testing, optionally configure a virtual environment:

# Create isolated Python environment

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Optional: Set GitHub token for higher API rate limits

export GITHUB_TOKEN=your_token_here

The github_utils.py module in skills/.system/skill-installer/scripts/ automatically detects GITHUB_TOKEN or GH_TOKEN environment variables to authenticate GitHub API requests.

Test Skills from Your Fork

Verify your fork works correctly by installing a skill directly from your copy:

# Install the yeet skill from your fork

$skill-installer --repo <your-username>/skills --path yeet

This command invokes install-skill-from-github.py, which downloads the skill directory into $CODEX_HOME/skills/.

Working with Skills in Your Fork

Installing Skills from Your Fork

The $skill-installer CLI supports installing skills from any fork or branch. Use the --repo flag to specify your username:

# List available skills in your fork's curated directory

$skill-installer list-skills --repo <your-username>/skills --path skills/.curated

# Install a specific skill

$skill-installer --repo <your-username>/skills --path skills/.curated/security-best-practices

Internally, list-skills.py uses github_utils.github_api_contents_url and github_utils.github_request to query the GitHub API and enumerate skill directories.

Adding New Skills

To create a custom skill in your fork:

1. Create a new directory under skills/.curated/ or skills/.experimental/.
2. Add a SKILL.md file containing the skill name, description, prerequisites, and usage instructions.
3. Include any executable scripts or assets required by the skill.
4. Commit and push to your fork:

git add skills/.curated/my-new-skill/
git commit -m "Add my-new-skill for automated testing"
git push origin main

Contributing Back via Pull Request

If you want to contribute your changes to the upstream repository:

1. Ensure your fork is synced with the upstream openai/skills repository.
2. Create a feature branch:

git checkout -b feature/my-improvement

3. Make your changes and commit them.
4. Push the branch to your fork:

git push -u origin feature/my-improvement

5. Open a pull request from your fork to openai/skills.

The yeet skill includes a reference workflow in its SKILL.md demonstrating automated PR creation using the GitHub CLI:

GH_PROMPT_DISABLED=1 GIT_TERMINAL_PROMPT=0 gh pr create --draft --fill --head $(git branch --show-current)

Key Files and Architecture

Understanding these core files helps you navigate and extend your fork effectively:

File	Purpose
skills/.system/skill-installer/scripts/list-skills.py	Lists available skills via GitHub API using github_utils.github_api_contents_url
skills/.system/skill-installer/scripts/install-skill-from-github.py	Downloads skills from GitHub URLs or performs sparse checkouts into $CODEX_HOME/skills
skills/.system/skill-installer/scripts/github_utils.py	Handles authenticated GitHub requests using GITHUB_TOKEN or GH_TOKEN
skills/.curated/yeet/SKILL.md	Example skill manifest showing complete documentation and Git workflow
README.md	High-level repository overview and basic usage instructions

Summary

• Forking the OpenAI skills repository creates an independent copy under your GitHub account, enabling customization without affecting upstream code.
• The repository structure separates system utilities, curated production skills, and experimental work-in-progress features.
• Use the $skill-installer CLI with the --repo flag to install skills directly from your fork for testing.
• Core installer logic resides in skills/.system/skill-installer/scripts/, specifically list-skills.py and install-skill-from-github.py.
• Contributing back requires creating a feature branch and opening a pull request to the upstream openai/skills repository.

Frequently Asked Questions

What is the difference between curated and experimental skills?

Curated skills located in skills/.curated/ are production-ready, vetted components like yeet and security-best-practices that follow strict documentation standards with complete SKILL.md manifests. Experimental skills in skills/.experimental/ are work-in-progress features that may lack full documentation or testing, intended for rapid iteration and community feedback before potential promotion to curated status.

Do I need a GitHub token to fork and use the repository?

No, you do not need a token to fork the repository or clone it locally—standard git clone operations work with HTTPS or SSH authentication. However, the $skill-installer utility and the list-skills.py script use the GitHub API to enumerate available skills, which has strict rate limits for unauthenticated requests. Setting the GITHUB_TOKEN or GH_TOKEN environment variable enables authenticated API calls with higher rate limits, as handled by github_utils.py.

Can I install skills from a private fork?

Yes, provided your GitHub account has access to the private repository. The install-skill-from-github.py script supports installing from any accessible GitHub URL, including private forks. When using the $skill-installer CLI, ensure your GITHUB_TOKEN environment variable is set with appropriate permissions (repo scope) so that github_utils.github_request can authenticate and access private repository contents.

How do I update my fork with upstream changes?

Sync your fork through the GitHub web interface by navigating to your forked repository and clicking "Sync fork," or use the command line by adding the upstream remote and pulling changes. First, add the upstream repository: git remote add upstream https://github.com/openai/skills.git. Then fetch and merge updates: git fetch upstream followed by git merge upstream/main (or rebase if preferred). Push the updated main branch to your fork with git push origin main to keep your copy current.

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