### Install an experimental skill from a local folder

Source: https://github.com/openai/skills/blob/main/README.md

Use this command to install an experimental skill by specifying its folder name. The skill will be installed from the '.experimental' folder.

```bash
$skill-installer install the create-plan skill from the .experimental folder
```

--------------------------------

### Install Skill from GitHub

Source: https://github.com/openai/skills/blob/main/_autodocs/QUICK-REFERENCE.md

Install a skill from a GitHub repository. Specify the repository, path, and optionally a reference (branch/tag), destination directory, or installation method.

```bash
python3 install-skill-from-github.py --repo owner/repo --path path [--ref ref] \
  [--dest dir] [--method auto|download|git]
```

--------------------------------

### List and Install Curated Skill

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

Demonstrates listing available skills and then installing a specific curated skill.

```bash
# List and install a curated skill
python3 list-skills.py  # See available skills
python3 install-skill-from-github.py --repo openai/skills \
  --path skills/.curated/gh-address-comments
```

--------------------------------

### Install from Private Repository

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

Installs a skill from a private repository by setting the `GITHUB_TOKEN` environment variable for authentication.

```bash
# Install from private repo with authentication
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
python3 install-skill-from-github.py \
  --repo myorg/private-skills \
  --path skills/internal-skill
```

--------------------------------

### Install a Skill from GitHub

Source: https://github.com/openai/skills/blob/main/_autodocs/README.md

Use these commands to list available skills and install a specific skill from a GitHub repository. Ensure you have the necessary Python scripts installed.

```bash
# List available skills
python3 list-skills.py
```

```bash
# Install a skill
python3 install-skill-from-github.py --repo openai/skills \
  --path skills/.curated/skill-name
```

--------------------------------

### Example Marketplace Configuration

Source: https://github.com/openai/skills/blob/main/_autodocs/types-and-schemas.md

A complete example of a marketplace.json file, demonstrating how to configure multiple plugins with different source types and policies.

```json
{
  "name": "Codex Plugins",
  "interface": {
    "displayName": "Codex Official Plugin Marketplace"
  },
  "plugins": [
    {
      "name": "github-integrations",
      "source": {
        "source": "local",
        "path": "./plugins/github-integrations"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Development"
    },
    {
      "name": "productivity-suite',
      "source": {
        "source": "local",
        "path": "./plugins/productivity-suite"
      },
      "policy": {
        "installation": "INSTALLED_BY_DEFAULT",
        "authentication": "ON_USE"
      },
      "category": "Productivity"
    }
  ]
}
```

--------------------------------

### Use Custom Installation Method

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

Specifies the installation method: `download` for direct download, `git` for sparse checkout, or `auto` to try download and fallback to git.

```bash
# Use custom installation method
python3 install-skill-from-github.py --repo owner/repo --path path \
  --method download   # Direct download only
  --method git        # Git sparse checkout only
  --method auto       # Try download, fallback to git (default)
```

```bash
# Install via git sparse checkout (no download fallback)
python3 install-skill-from-github.py --repo owner/repo --path path \
  --method git
```

--------------------------------

### Install a skill from a GitHub URL

Source: https://github.com/openai/skills/blob/main/README.md

Use this command to install a skill directly from a GitHub directory URL. This is useful for installing skills that are not yet curated or locally available.

```bash
$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan
```

--------------------------------

### Custom Plugin Directory Installation

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

Shows how to install skills to a custom plugin directory, such as `~/plugins`, for home-local plugins.

```bash
--dest ~/.codex/skills  # Preinstalled in Codex
--dest ~/plugins        # Custom plugin directory
```

--------------------------------

### install

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

Main installation function to install skills from a GitHub repository. It supports automatic, download, or git installation methods.

```APIDOC
## install(source: Source, dest_dir: str, method: str)

### Description
Installs a skill from a specified source (e.g., GitHub repository) into a destination directory. Supports automatic, download, or git installation methods.

### Parameters
#### Path Parameters
- **source** (Source) - Required - Repository details including owner, repo, ref, and paths.
- **dest_dir** (string) - Required - The destination directory for the skill installation (e.g., `~/.codex/skills`).
- **method** (string) - Required - The installation method. Accepted values are: `"auto"`, `"download"`, or `"git"`.

### Throws
- **InstallError**: "Skill directory already exists" - If the destination directory already exists and `--force` is not used.
- **InstallError**: "Download failed: HTTP {code}" - If an HTTP error occurs during download.
- **InstallError**: "Git command failed" - If the git sparse checkout command fails.
- **InstallError**: "Invalid skill name" - If the skill name contains path separators or reserved names.
```

--------------------------------

### Install Skill from GitHub

Source: https://github.com/openai/skills/blob/main/_autodocs/MANIFEST.txt

Use `install-skill-from-github.py` to install a skill directly from a GitHub repository. This script supports both direct download and Git clone methods for installation.

```python
python -m skills.install_skill_from_github --github-url=https://github.com/openai/skills --skill-name=my_skill
```

--------------------------------

### Example agents/openai.yaml with Fields

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-structure.md

An example of the `agents/openai.yaml` file populated with specific values for display name, description, icons, brand color, and default prompt.

```yaml
interface:
  display_name: "GitHub PR Reviewer"
  short_description: "Review GitHub pull requests with AI guidance"
  icon_small: "./assets/github-icon-400px.png"
  icon_large: "./assets/github-logo.svg"
  brand_color: "#3B82F6"
  default_prompt: "Use $skill-name to review this PR and suggest improvements."
```

--------------------------------

### SKILL.md Frontmatter Example

Source: https://github.com/openai/skills/blob/main/_autodocs/types-and-schemas.md

An example of a complete SKILL.md frontmatter, demonstrating how to populate fields like name, description, metadata, license, and allowed tools. This serves as a template for creating new skill configurations.

```yaml
---
name: github-pr-reviewer
description: |
  Review GitHub pull requests with AI guidance, analyzing code changes
  and identifying potential issues. Use when reviewing PRs, checking code
  quality, security concerns, or architectural improvements.
metadata:
  short-description: "Automated PR review and feedback"
  category: "Development"
license: MIT
allowed-tools:
  - github-mcp
  - codex-api
---
```

--------------------------------

### Install Skill from Curated List

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

Installs a skill from the `openai/skills` curated list by specifying the repository and the skill's path within it.

```bash
# Install from openai/skills curated list
python3 install-skill-from-github.py --repo openai/skills \
  --path skills/.curated/my-skill
```

--------------------------------

### Install to Custom Destination

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

Installs the skill to a custom destination directory instead of the default.

```bash
# Install to custom destination
python3 install-skill-from-github.py --repo owner/repo --path path \
  --dest ~/my-skills
```

--------------------------------

### List Available Skills (CLI)

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

Use this command to list all skills available for installation from a specified path.

```bash
python3 list-skills.py --path skills/.curated
```

--------------------------------

### Install Skill Function Signature

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

The main installation function signature. It takes source repository details, a destination directory, and an installation method.

```python
def install(source: Source, dest_dir: str, method: str) -> None
```

--------------------------------

### Install a Curated Skill from GitHub

Source: https://github.com/openai/skills/blob/main/_autodocs/curated-skills-guide.md

Installs a specified curated skill from a GitHub repository to your local Codex environment. Ensure you restart Codex after installation to load the new skill.

```bash
python3 skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo openai/skills \
  --path skills/.curated/skill-name
```

```bash
python3 skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo openai/skills \
  --path skills/.curated/gh-address-comments
```

--------------------------------

### Install Curated Skill from GitHub

Source: https://github.com/openai/skills/blob/main/_autodocs/curated-skills-guide.md

Install curated skills from a GitHub repository using the `install-skill-from-github.py` script. You can specify the repository, the local path for installation, and the Git reference (e.g., `main` branch or a specific version tag).

```bash
# Install from main branch
python3 install-skill-from-github.py --repo openai/skills --path skills/.curated/skill-name --ref main

# Install from specific release
python3 install-skill-from-github.py --repo openai/skills --path skills/.curated/skill-name --ref v2.1.0
```

--------------------------------

### Install Skill from GitHub (CLI)

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

Install a specific skill from a GitHub repository to a designated local path. Ensure the target path is correctly specified.

```bash
python3 install-skill-from-github.py --repo openai/skills \
  --path skills/.curated/my-skill
```

--------------------------------

### Install Skill from GitHub

Source: https://github.com/openai/skills/blob/main/_autodocs/QUICK-REFERENCE.md

Installs a skill from a specified GitHub repository. The skill will be placed in the designated path within your local skills directory.

```bash
python3 install-skill-from-github.py --repo openai/skills --path skills/.curated/skill-name
```

--------------------------------

### Create Home-Local Plugin with Marketplace Entry

Source: https://github.com/openai/skills/blob/main/_autodocs/plugin-creator-api.md

This example demonstrates creating a plugin located in the user's home directory and registering it in the marketplace, updating the marketplace configuration file in the user's home directory.

```bash
python3 create_basic_plugin.py my-home-plugin \
  --path ~/plugins \
  --marketplace-path ~/.agents/plugins/marketplace.json \
  --with-marketplace

# Creates:
# ~/plugins/my-home-plugin/.codex-plugin/plugin.json
# ~/.agents/plugins/marketplace.json (with plugin entry)
```

--------------------------------

### Example: List Skills from Custom Repository

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

This command demonstrates how to list skills from a custom GitHub repository and a specific path within it.

```bash
# List skills from custom repo
python3 list-skills.py --repo myorg/skill-catalog --path skills/public
```

--------------------------------

### Set Codex Home Directory

Source: https://github.com/openai/skills/blob/main/_autodocs/types-and-schemas.md

Example of setting the CODEX_HOME environment variable to specify the installation location for skills. Skills will be installed under `$CODEX_HOME/skills/`.

```bash
export CODEX_HOME=/opt/codex
# Skills now install to /opt/codex/skills/
```

--------------------------------

### Plugin Installation Policies

Source: https://github.com/openai/skills/blob/main/_autodocs/QUICK-REFERENCE.md

Determines the visibility and installation status of plugins. 'AVAILABLE' is the default policy.

```text
NOT_AVAILABLE           # Hidden from users
AVAILABLE               # Users can install (default)
INSTALLED_BY_DEFAULT    # Pre-installed
```

--------------------------------

### Example SkillInterfaceConfig

Source: https://github.com/openai/skills/blob/main/_autodocs/types-and-schemas.md

A concrete example of a SkillInterfaceConfig for a GitHub PR Reviewer skill, demonstrating required and optional fields.

```yaml
interface:
  display_name: "GitHub PR Reviewer"
  short_description: "Review GitHub pull requests with AI guidance"
  icon_small: "./assets/github-icon-400px.png"
  icon_large: "./assets/github-logo.svg"
  brand_color: "#181717"
  default_prompt: "Use $skill-name to review this GitHub PR and provide feedback."

dependencies:
  tools:
    - type: "mcp"
      value: "github"
      description: "GitHub MCP server for PR operations"
      transport: "streamable_http"
      url: "https://api.githubcopilot.com/mcp/"

```

--------------------------------

### Get Locally Installed Skills

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

Retrieves a set of skill directory names that are already installed locally. It reads the $CODEX_HOME environment variable (defaulting to ~/.codex) and lists directories within its 'skills/' subdirectory.

```python
def _installed_skills() -> set[str]
```

```python
installed = _installed_skills()
# Returns: {"my-custom-skill", "gh-address-comments"}
```

--------------------------------

### Install Multiple Skills

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

Installs multiple skills in a single execution by providing multiple `--path` arguments.

```bash
# Install multiple skills in one run
python3 install-skill-from-github.py --repo openai/skills \
  --path skills/.curated/skill-1 skills/.curated/skill-2
```

```bash
# Install multiple curated skills
python3 install-skill-from-github.py --repo openai/skills \
  --path skills/.curated/pdf \
  --path skills/.curated/figma
```

--------------------------------

### Skill Installer API

Source: https://github.com/openai/skills/blob/main/_autodocs/MANIFEST.txt

APIs for discovering and installing skills from remote repositories like GitHub.

```APIDOC
## list-skills.py

### Description
Discovers and lists available skills from specified GitHub repositories.

### Usage
Use this script to find skills that can be installed into your environment.

## install-skill-from-github.py

### Description
Installs a skill from a GitHub repository, supporting both direct download and Git clone operations.

### Usage
This script handles the process of fetching and setting up a skill from its source repository, including managing dependencies and configurations.

## github_utils.py

### Description
A collection of utility functions for interacting with the GitHub API, used internally by the installer.

### Usage
Provides helper functions for common GitHub operations like cloning repositories and fetching metadata.
```

--------------------------------

### Install a curated skill

Source: https://github.com/openai/skills/blob/main/README.md

Use this command to install a curated skill by its name. The default directory for curated skills is 'skills/.curated'.

```bash
$skill-installer gh-address-comments
```

--------------------------------

### List Available Skills

Source: https://github.com/openai/skills/blob/main/_autodocs/QUICK-REFERENCE.md

This command displays a list of skills that are available for installation from the curated list.

```bash
python3 list-skills.py
```

--------------------------------

### Example: List Experimental Skills

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

This command lists skills from a different path within the repository, specifically the '.experimental' directory.

```bash
# List experimental skills
python3 list-skills.py --path skills/.experimental
```

--------------------------------

### Example: List Curated Skills

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

This command lists the default curated skills from the 'openai/skills' repository.

```bash
# List curated skills (default)
python3 list-skills.py
```

--------------------------------

### Install Specific Git Reference

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

Installs a skill from a specific Git reference, such as a branch name or commit SHA.

```bash
# Install specific git reference
python3 install-skill-from-github.py --repo owner/repo --path path \
  --ref develop
```

--------------------------------

### Valid Installation Policies

Source: https://github.com/openai/skills/blob/main/_autodocs/types-and-schemas.md

Specifies the availability of plugins to users. Use 'AVAILABLE' for general access, 'INSTALLED_BY_DEFAULT' for pre-installed plugins, and 'NOT_AVAILABLE' to hide them.

```text
NOT_AVAILABLE         # Hidden from users
AVAILABLE             # Available to install (default)
INSTALLED_BY_DEFAULT  # Pre-installed
```

--------------------------------

### List Available Curated Skills

Source: https://github.com/openai/skills/blob/main/_autodocs/curated-skills-guide.md

Use this command to see a list of all available curated skills and their installation status.

```bash
python3 skills/.system/skill-installer/scripts/list-skills.py
```

--------------------------------

### Initialize a New Skill Project

Source: https://github.com/openai/skills/blob/main/_autodocs/MANIFEST.txt

Use the `init_skill.py` script to create a new skill project from predefined templates. This is the starting point for developing a new skill.

```python
python -m skills.init_skill --template=basic_skill my_new_skill
```

--------------------------------

### Define Installation Source Type

Source: https://github.com/openai/skills/blob/main/_autodocs/types-and-schemas.md

Defines the Python dataclass for specifying a GitHub repository source for skill installation. Includes owner, repository, git reference, and relative paths.

```python
from dataclasses import dataclass

@dataclass
class Source:
    owner: str                  # Repository owner
    repo: str                   # Repository name
    ref: str                    # Git reference (branch/tag/SHA)
    paths: list[str]            # Repository-relative skill paths
    repo_url: str | None        # Full git URL (for git operations)
```

--------------------------------

### Install Pillow with uv

Source: https://github.com/openai/skills/blob/main/_autodocs/imagegen-api.md

Install the Pillow library for image manipulation using uv. This is an optional dependency for certain edit modes.

```bash
uv pip install pillow
```

--------------------------------

### SKILL.md Frontmatter Example

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-structure.md

Example of the frontmatter for a SKILL.md file, including the skill's name, a detailed description, and workflow overview. This frontmatter is validated by `quick_validate.py`.

```markdown
---
name: github-pr-reviewer
description: |
  Review GitHub pull requests with AI guidance. Analyzes code changes,
  identifies potential issues, and suggests improvements. Use when you need
  to review PRs, check for best practices, security issues, or architectural concerns.
---

# GitHub PR Reviewer

This skill helps review PRs by analyzing the diff, code quality, and potential issues.

## Workflow

1. Fetch PR details from GitHub
2. Analyze code changes with scripts/analyze_changes.py
3. Generate review with suggestions
4. Post comments to PR

## API Reference

See references/github-api.md for endpoint details.

## Review Standards

See references/code-standards.md for company standards.
```

--------------------------------

### SKILL.md Description Constraints Example

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-structure.md

Provides an example of a comprehensive skill description that adheres to constraints, including supported operations and usage scenarios.

```yaml
description: |
  Create, edit, and analyze Word documents (.docx files) with full support for 
  tracked changes, comments, formatting preservation, and text extraction. 
  Use when Codex needs to: (1) Create new documents, (2) Modify or edit content, 
  (3) Work with tracked changes, (4) Add comments, (5) Extract text for analysis, 
  or handle any other document manipulation tasks.
```

--------------------------------

### Initialize a Custom Skill

Source: https://github.com/openai/skills/blob/main/_autodocs/curated-skills-guide.md

Use the `init_skill.py` script to scaffold a new custom skill. Specify the skill name, the desired path for its installation, and the resource types to include (scripts, references, assets).

```bash
python3 skills/.system/skill-creator/scripts/init_skill.py \
  my-custom-skill \
  --path ~/.codex/skills \
  --resources scripts,references,assets
```

--------------------------------

### Valid Authentication Policies

Source: https://github.com/openai/skills/blob/main/_autodocs/types-and-schemas.md

Defines when users are prompted for authentication. 'ON_INSTALL' prompts during installation, while 'ON_USE' prompts when the plugin is first utilized.

```text
ON_INSTALL    # Prompted during installation
ON_USE        # Prompted when plugin is used
```

--------------------------------

### Example: Output Skills as JSON

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

This command shows how to request the output in JSON format, which is useful for integrating with other tools or scripts.

```bash
# Output as JSON for programmatic use
python3 list-skills.py --format json
```

--------------------------------

### Args Dataclass

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

Represents parsed command-line arguments for the skill installation process. Includes URL, repository details, paths, reference, destination, name, and installation method.

```python
from dataclasses import dataclass

@dataclass
class Args:
    url: str | None         # GitHub URL (alternative to --repo)
    repo: str | None        # Repository (owner/repo)
    path: list[str] | None  # Repository paths (repeatable)
    ref: str                # Git reference
    dest: str | None        # Destination directory
    name: str | None        # Override skill name
    method: str             # Installation method (auto/download/git)
```

--------------------------------

### Text Output Format for Skills

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

The default text format displays a list of skills, indicating which ones are already installed, and prompts the user for installation choices.

```text
Skills from openai/skills (skills/.curated):
1. cli-creator
2. figma (already installed)
3. gh-address-comments
4. ...

Which ones would you like installed?
```

--------------------------------

### Product Management References Directory Structure

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-structure.md

Example directory structure for reference files related to product management.

```tree
references/
├── communication.md (how to draft updates)
├── context_building.md (gathering information)
└── templates.md (message templates)
```

--------------------------------

### Default Marketplace Output Structure

Source: https://github.com/openai/skills/blob/main/_autodocs/plugin-creator-api.md

Example structure for a default marketplace, including name, interface details, and an empty plugins array.

```python
{
    "name": "[TODO: marketplace-name]",
    "interface": {
        "displayName": "[TODO: Marketplace Display Name]"
    },
    "plugins": []
}
```

--------------------------------

### SKILL.md File Format Example

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-structure.md

Illustrates the basic structure of a SKILL.md file, including YAML frontmatter and Markdown body content.

```markdown
---
name: skill-name
description: Comprehensive description of what the skill does and when to use it.
metadata:
  short-description: Optional metadata field
---

# Skill Title

Markdown content describing how to use the skill...
```

--------------------------------

### API Integration References Directory Structure

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-structure.md

Example directory structure for reference files related to API integration.

```tree
references/
├── api-endpoints.md (full API reference)
├── authentication.md (auth schemes)
├── rate-limits.md (quota and throttling)
└── errors.md (error codes and recovery)
```

--------------------------------

### Marketplace Entry Output Structure

Source: https://github.com/openai/skills/blob/main/_autodocs/plugin-creator-api.md

Example structure of a marketplace entry dictionary, including name, source, policy, and category.

```python
{
    "name": "plugin-name",
    "source": {
        "source": "local",
        "path": "./plugins/plugin-name"
    },
    "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
    },
    "category": "Productivity"
}
```

--------------------------------

### Database References Directory Structure

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-structure.md

Example directory structure for reference files related to database operations.

```tree
references/
├── schema.md (full database schema)
├── queries.md (common patterns)
└── performance.md (indexing and optimization)
```

--------------------------------

### Agent Configuration Example (openai.yaml)

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-structure.md

Configuration file for an agent, specifying its display name, short description, icon, brand color, and default prompt. This YAML file is part of the skill's agent definitions.

```yaml
interface:
  display_name: "GitHub PR Reviewer"
  short_description: "Review GitHub pull requests with AI"
  icon_small: "./assets/icons/github-logo.svg"
  brand_color: "#181717"
  default_prompt: "Use $skill-name to review this GitHub PR"
```

--------------------------------

### Complete Skill Directory Structure

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-structure.md

An example of a well-organized directory structure for a complete skill, including markdown, agent configurations, scripts, references, and assets.

```tree
github-pr-reviewer/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
│   ├── fetch_pr_details.py
│   ├── analyze_changes.py
│   └── github_client.py
├── references/
│   ├── pr-review-guide.md
│   ├── github-api.md
│   └── code-standards.md
├── assets/
│   ├── review-template.md
│   └── icons/
│       └── github-logo.svg
└── LICENSE.txt
```

--------------------------------

### Discover Skills from GitHub

Source: https://github.com/openai/skills/blob/main/_autodocs/MANIFEST.txt

The `list-skills.py` script queries GitHub to discover available skills. It helps in finding skills that can be installed into your environment.

```python
python -m skills.list_skills --github-org=openai --github-repo=skills
```

--------------------------------

### Configure GitHub Token for Private Repositories

Source: https://github.com/openai/skills/blob/main/_autodocs/types-and-schemas.md

Example of exporting the GITHUB_TOKEN environment variable for authentication with private GitHub repositories. This is used by the install-skill-from-github.py script.

```bash
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
python3 install-skill-from-github.py --repo myorg/private-skills --path skills/internal
```

--------------------------------

### Build Marketplace Entry

Source: https://github.com/openai/skills/blob/main/_autodocs/plugin-creator-api.md

Generates a dictionary representing a plugin's entry in the marketplace. Requires plugin name, installation policy, authentication policy, and category.

```python
def build_marketplace_entry(
    plugin_name: str,
    install_policy: str,
    auth_policy: str,
    category: str
) -> dict[str, Any]
```

--------------------------------

### Marketplace Configuration: marketplace.json

Source: https://github.com/openai/skills/blob/main/_autodocs/plugin-creator-api.md

Defines the structure for the marketplace, listing available plugins with their source, installation, and authentication policies. Located at `<repo-root>/.agents/plugins/marketplace.json`.

```json
{
  "name": "Marketplace Name",
  "interface": {
    "displayName": "Marketplace Display Name"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": {
        "source": "local",
        "path": "./plugins/plugin-name"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}
```

--------------------------------

### Marketplace JSON Entry Example

Source: https://github.com/openai/skills/blob/main/_autodocs/plugin-creator-api.md

This JSON structure represents a plugin entry in the marketplace.json file, including its name, interface details, source information, policy, and category.

```json
{
  "name": "[TODO: marketplace-name]",
  "interface": {
    "displayName": "[TODO: Marketplace Display Name]"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}
```

--------------------------------

### Create Plugin and Register in Marketplace

Source: https://github.com/openai/skills/blob/main/_autodocs/plugin-creator-api.md

Create a plugin and simultaneously register it in the marketplace. This command also updates the marketplace configuration file.

```bash
# Create plugin
python3 create_basic_plugin.py my-awesome-plugin \
  --path ./plugins \
  --with-marketplace

# This creates:
# 1. ./plugins/my-awesome-plugin/.codex-plugin/plugin.json
# 2. ./.agents/plugins/marketplace.json (if it doesn't exist, or updates it)
```

--------------------------------

### Create a Basic Plugin with Marketplace Support

Source: https://github.com/openai/skills/blob/main/_autodocs/README.md

Scaffold a new plugin with basic functionality and include marketplace discovery capabilities. This command initializes the plugin structure and configuration files.

```bash
python3 create_basic_plugin.py my-plugin \
  --path ./plugins \
  --with-marketplace
```

--------------------------------

### Create Basic Plugin Command

Source: https://github.com/openai/skills/blob/main/_autodocs/plugin-creator-api.md

Use this command to create a new plugin. Specify the plugin name and optionally set the parent directory, marketplace path, and flags to include additional directories or files.

```bash
python3 create_basic_plugin.py <plugin-name> \
  [--path <parent-directory>] \
  [--marketplace-path <path-to-marketplace-json>] \
  [--force] \
  [--with-skills] \
  [--with-hooks] \
  [--with-scripts] \
  [--with-assets] \
  [--with-mcp] \
  [--with-apps] \
  [--with-marketplace]
```

--------------------------------

### Programmatic Skill Management

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

Manage skills programmatically by listing available and installed skills. This script helps identify which skills can be installed.

```python
from list_skills import _list_skills, _installed_skills
from install-skill-from-github import Source

# List curated skills
available = _list_skills("openai/skills", "skills/.curated", "main")
installed = _installed_skills()

# Show uninstalled skills
uninstalled = [s for s in available if s not in installed]
print(f"Available to install: {uninstalled}")
```

--------------------------------

### Install Pillow with pip

Source: https://github.com/openai/skills/blob/main/_autodocs/imagegen-api.md

Install the Pillow library for image manipulation using pip. This is an optional dependency for certain edit modes.

```bash
pip install pillow
```

--------------------------------

### Initialize New Skill

Source: https://github.com/openai/skills/blob/main/_autodocs/QUICK-REFERENCE.md

Use this command to initialize a new skill project. Specify the skill name, directory, and optional resources or interfaces.

```bash
python3 skills/.system/skill-creator/scripts/init_skill.py <name> \
  --path <dir> [--resources scripts,references,assets] [--examples] \
  [--interface key=value ...]
```

--------------------------------

### Initialize a New Skill

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-creator-api.md

Use this command to create a new skill directory from a template. Specify the skill name and the output path. Optional flags allow for the inclusion of resource directories and custom interface metadata.

```bash
python3 init_skill.py <skill-name> --path <output-directory> \
  [--resources scripts,references,assets] \
  [--examples] \
  [--interface key=value ...]
```

```bash
# Create a basic skill
python3 init_skill.py my-skill --path skills/public
```

```bash
# Create a skill with all resources and examples
python3 init_skill.py my-skill --path skills/public \
  --resources scripts,references,assets \
  --examples
```

```bash
# Create a skill with custom interface metadata
python3 init_skill.py my-skill --path skills/public \
  --interface display_name="My Custom Skill" \
  --interface short_description="A helpful skill"
```

--------------------------------

### Initialize a New Skill

Source: https://github.com/openai/skills/blob/main/_autodocs/QUICK-REFERENCE.md

Use this command to create a new skill directory and initialize it with the minimal structure. The skill will be placed in the specified path.

```bash
python3 init_skill.py my-skill --path ./skills
```

--------------------------------

### Create Basic Plugin

Source: https://github.com/openai/skills/blob/main/_autodocs/QUICK-REFERENCE.md

Create a new basic plugin with optional components such as skills, hooks, scripts, assets, MCP, apps, and marketplace configuration.

```bash
python3 create_basic_plugin.py <name> [--path <parent-dir>] \
  [--with-skills] [--with-hooks] [--with-scripts] [--with-assets] \
  [--with-mcp] [--with-apps] [--with-marketplace] [--force]
```

--------------------------------

### _validate_model

Source: https://github.com/openai/skills/blob/main/_autodocs/imagegen-api.md

Validates the format of a model ID, ensuring it starts with 'gpt-image-'.

```APIDOC
## Function: _validate_model()

### Description
Validates the format of a model ID, ensuring it starts with 'gpt-image-'.

### Parameters
#### Path Parameters
- **model** (string) - Required - Model ID to validate.

### Throws
- **SystemExit(1)** - Model ID does not start with `gpt-image-`.
```

--------------------------------

### Create a Basic Plugin

Source: https://github.com/openai/skills/blob/main/_autodocs/plugin-creator-api.md

Use this command to create a new plugin with a basic structure, including the essential `.codex-plugin/plugin.json` file.

```bash
python3 create_basic_plugin.py my-awesome-plugin --path ~/code/plugins
```

--------------------------------

### Valid Marketplace Policies

Source: https://github.com/openai/skills/blob/main/_autodocs/plugin-creator-api.md

Defines the set of valid string values for installation and authentication policies.

```python
VALID_INSTALL_POLICIES = {"NOT_AVAILABLE", "AVAILABLE", "INSTALLED_BY_DEFAULT"}
VALID_AUTH_POLICIES = {"ON_INSTALL", "ON_USE"}
```

--------------------------------

### Create Basic Plugin with Marketplace

Source: https://github.com/openai/skills/blob/main/_autodocs/QUICK-REFERENCE.md

Use this command to create a new plugin with basic marketplace integration. You will need to edit the plugin's JSON configuration files afterward.

```bash
python3 create_basic_plugin.py my-plugin --with-marketplace
```

--------------------------------

### Data Processing Scripts Directory Structure

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-structure.md

Example directory structure for scripts related to data processing.

```tree
scripts/
├── process_csv.py
├── transform_json.py
└── validation.py (shared module)
```

--------------------------------

### GitHub Integration Scripts Directory Structure

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-structure.md

Example directory structure for scripts related to GitHub integration.

```tree
scripts/
├── fetch_comments.py
├── inspect_pr_checks.py
└── github_utils.py (shared module)
```

--------------------------------

### PDF Manipulation Scripts Directory Structure

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-structure.md

Example directory structure for scripts related to PDF manipulation.

```tree
scripts/
├── extract_text.py
├── fill_fillable_fields.py
├── rotate_pages.py
└── utilities.py (shared module)
```

--------------------------------

### Validate Relative Path Function Signature

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

Signature for the function that validates if a given path is relative and safe for installation.

```python
def _validate_relative_path(path: str) -> None
```

--------------------------------

### Create Plugin with Full Structure

Source: https://github.com/openai/skills/blob/main/_autodocs/plugin-creator-api.md

Generate a plugin with all possible subdirectories and files, including skills, hooks, scripts, assets, MCP, and apps.

```bash
python3 create_basic_plugin.py my-awesome-plugin \
  --path ~/code/plugins \
  --with-skills \
  --with-hooks \
  --with-scripts \
  --with-assets \
  --with-mcp \
  --with-apps
```

--------------------------------

### Python Function Signature

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-creator-api.md

This is the entry point for the `init_skill.py` script. It parses command-line arguments to create a new skill directory with template files.

```python
def main() -> None
```

--------------------------------

### Full Skill Configuration with Metadata

Source: https://github.com/openai/skills/blob/main/_autodocs/README.md

An extensive skill configuration including name, description, metadata, and license. Use this for skills requiring detailed information and branding.

```yaml
---
name: my-skill
description: What this skill does and when to use it
metadata:
  short-description: "Brief description"
license: MIT
---

```

--------------------------------

### Create a Basic Plugin

Source: https://github.com/openai/skills/blob/main/_autodocs/MANIFEST.txt

Scaffold a new plugin project using `create_basic_plugin.py`. This script sets up the necessary directory structure and boilerplate files for plugin development.

```python
python -m skills.create_basic_plugin --plugin-name=my_plugin
```

--------------------------------

### Source Dataclass

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-installer-api.md

Represents a GitHub repository source for installing skills. Specifies owner, repository, reference, paths, and optional URL.

```python
from dataclasses import dataclass

@dataclass
class Source:
    owner: str              # Repository owner
    repo: str               # Repository name
    ref: str                # Git reference (branch/tag/SHA)
    paths: list[str]        # Repository paths to install
    repo_url: str | None    # Full git URL (for sparse checkout)
```

--------------------------------

### Plugin Authentication Policies

Source: https://github.com/openai/skills/blob/main/_autodocs/QUICK-REFERENCE.md

Specifies when users are prompted for authentication for a plugin. 'ON_INSTALL' is the default.

```text
ON_INSTALL    # Prompt during installation (default)
ON_USE        # Prompt when skill is used
```

--------------------------------

### Create a New Skill with Resources

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-creator-api.md

Use this command to create a new skill with a specified name and include essential resources like scripts, references, and assets. You can also define display name, short description, and brand color during creation.

```bash
#!/bin/bash
# Create a new skill named "gh-pr-reviewer" with all resources

python3 init_skill.py gh-pr-reviewer \
  --path skills/public \
  --resources scripts,references,assets \
  --interface display_name="GitHub PR Reviewer" \
  --interface short_description="Automate PR review workflows" \
  --interface brand_color="#3B82F6"
```

--------------------------------

### Build Default Marketplace Structure

Source: https://github.com/openai/skills/blob/main/_autodocs/plugin-creator-api.md

Creates a new marketplace structure with default values, including placeholders for the marketplace name and display name, and an empty list of plugins.

```python
def build_default_marketplace() -> dict[str, Any]
```

--------------------------------

### Validate Model ID Format

Source: https://github.com/openai/skills/blob/main/_autodocs/imagegen-api.md

Validates that the provided model ID starts with the required prefix 'gpt-image-'. Exits with an error if the format is invalid.

```python
def _validate_model(model: str) -> None:
    pass
```

--------------------------------

### Initialize New Skill

Source: https://github.com/openai/skills/blob/main/_autodocs/skill-creator-api.md

Initializes a new skill from a template using the `init_skill.py` script. This script parses command-line arguments to create a new skill directory with template files.

```APIDOC
## Initialize New Skill

### Description
Initializes a new skill from a template using the `init_skill.py` script. This script parses command-line arguments to create a new skill directory with template files.

### Command Syntax
```bash
python3 init_skill.py <skill-name> --path <output-directory> \
  [--resources scripts,references,assets] \
  [--examples] \
  [--interface key=value ...]
```

### Parameters
#### Path Parameters
- **skill-name** (string) - Required - Name of the skill in hyphen-case (lowercase, digits, hyphens only). Max 64 characters.
- **--path** (string) - Required - Directory where the skill folder will be created.

#### Query Parameters
- **--resources** (string) - Optional - Comma-separated list of resource directories to create: `scripts`, `references`, `assets`.
- **--examples** (flag) - Optional - If set, create placeholder example files in resource directories.
- **--interface** (key=value) - Optional - Interface metadata overrides. Repeatable. Valid keys: `display_name`, `short_description`, `icon_small`, `icon_large`, `brand_color`, `default_prompt`.

### Output
Creates a skill directory with the following structure:

```
<skill-name>/
├── SKILL.md (with frontmatter and template body)
├── agents/
│   └── openai.yaml (if --interface provided or generated defaults)
├── scripts/ (if --resources includes scripts)
├── references/ (if --resources includes references)
└── assets/ (if --resources includes assets)
```

### Examples
```bash
# Create a basic skill
python3 init_skill.py my-skill --path skills/public

# Create a skill with all resources and examples
python3 init_skill.py my-skill --path skills/public \
  --resources scripts,references,assets \
  --examples

# Create a skill with custom interface metadata
python3 init_skill.py my-skill --path skills/public \
  --interface display_name="My Custom Skill" \
  --interface short_description="A helpful skill"
```

### Constants
- **MAX_SKILL_NAME_LENGTH** (int) - 64 - Maximum allowed length for skill names.
- **ALLOWED_RESOURCES** (set) - `{"scripts", "references", "assets"}` - Valid resource directory names.
```

--------------------------------

### Set OpenAI API Key for Image Generation

Source: https://github.com/openai/skills/blob/main/_autodocs/types-and-schemas.md

Example of exporting the OPENAI_API_KEY environment variable, which is required for features that interact with the OpenAI API, such as image generation.

```bash
export OPENAI_API_KEY=sk-...
python3 image_gen.py --prompt "Generate an image"
```