# Best Practices for Developing OpenAI Skills: A Complete Guide to the openai/skills Architecture

> Master OpenAI skills development with best practices using the skill-creator scaffold for metadata-driven definitions. Validate and install for reusable agent capabilities.

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

---

**The best practices for developing OpenAI skills involve using the skill-creator scaffold to generate metadata-driven definitions, validating with [`quick_validate.py`](https://github.com/openai/skills/blob/main/quick_validate.py), and installing via the skill-installer pipeline to ensure consistent, reusable agent capabilities.**

The `openai/skills` repository provides a structured framework for building reusable capabilities that OpenAI agents can invoke. Following the established best practices for developing OpenAI skills ensures your contributions are discoverable, validated, and seamlessly integrate into the agent ecosystem.

## Start with the Skill Creator Scaffold

Every new skill should begin with the official scaffolding tools located in `skills/.system/skill-creator/`. This ensures consistent directory layout, front-matter formatting, and metadata generation.

### Generate the Directory Structure

Use [`init_skill.py`](https://github.com/openai/skills/blob/main/init_skill.py) to create a new skill skeleton. This script generates the required folder hierarchy, including the `agents/` directory for the [`openai.yaml`](https://github.com/openai/skills/blob/main/openai.yaml) definition and a [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) file for documentation.

```bash
python -m skills/.system/skill-creator/scripts/init_skill.py \
    --name "weather-lookup" \
    --path skills/.curated/weather-lookup \
    --resources api_key \
    --include-examples

```

This creates `skills/.curated/weather-lookup/` containing:
- [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml) (auto-filled with placeholders)
- [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) with standardized front-matter
- `scripts/` directory for custom logic

### Automate Metadata Generation

The [`generate_openai_yaml.py`](https://github.com/openai/skills/blob/main/generate_openai_yaml.py) script transforms the front-matter from [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) into a fully-typed [`openai.yaml`](https://github.com/openai/skills/blob/main/openai.yaml) file. This ensures the skill's contract is always synchronized with its documentation and follows the OpenAI Agent specification.

## Define the Contract with openai.yaml

The [`openai.yaml`](https://github.com/openai/skills/blob/main/openai.yaml) file serves as the declarative heart of every skill. Located at `skills/.curated/<skill>/agents/openai.yaml`, this metadata-driven definition enables the skill-installer to treat every skill uniformly regardless of internal complexity.

### Declare Inputs and Outputs with JSON Schema

Explicitly define all inputs and outputs using JSON Schema in the [`openai.yaml`](https://github.com/openai/skills/blob/main/openai.yaml). Specify the `model`, `temperature`, and provide a detailed system prompt to ensure deterministic behavior.

```yaml
name: weather-lookup
description: Retrieve the current temperature for a given city.
model: gpt-4o-mini
temperature: 0.0
inputs:
  type: object
  properties:
    city:
      type: string
      description: Name of the city to query.
  required: [city]
outputs:
  type: object
  properties:
    temperature_celsius:
      type: number
      description: Current temperature in Celsius.
    condition:
      type: string
      description: Short weather description.

```

*Reference implementation:* [[`skills/.curated/yeet/agents/openai.yaml`](https://github.com/openai/skills/blob/main/skills/.curated/yeet/agents/openai.yaml)](https://github.com/openai/skills/blob/main/skills/.curated/yeet/agents/openai.yaml)

### Reference Custom Tools

When a skill requires custom code—such as calling external APIs or performing data transformations—encapsulate this logic in the `scripts/` directory and reference it from [`openai.yaml`](https://github.com/openai/skills/blob/main/openai.yaml) using the `code` field or tool definitions.

```yaml
tools:
  - name: get_weather
    description: Fetch current weather for a city.
    input_schema:
      type: object
      properties:
        city:
          type: string
      required: [city]
    output_schema:
      type: object
      properties:
        temperature_celsius:
          type: number
        condition:
          type: string
    code: scripts/get_weather.py

```

## Validate Before Committing

Always run validation before committing a skill to catch structural errors or malformed YAML early. The [`quick_validate.py`](https://github.com/openai/skills/blob/main/quick_validate.py) script in the skill-creator module performs lightweight sanity checks on the skill's structure and required fields.

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

```

Expected output: `✅ Skill validated successfully`.

This validation ensures that the [`openai.yaml`](https://github.com/openai/skills/blob/main/openai.yaml) is parseable, required fields are present, and the directory structure conforms to the expected layout before the skill enters the installation pipeline.

## Install and Distribute Skills

The skill-installer layer in `skills/.system/skill-installer/` handles distribution, ensuring skills can be discovered and installed reliably from remote repositories.

### List Available Skills

Use [`list-skills.py`](https://github.com/openai/skills/blob/main/list-skills.py) to enumerate all curated skills available in the repository:

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

```

### Install from GitHub

The [`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py) script resolves a GitHub URL, performs a sparse checkout of only the specific skill folder (e.g., `skills/.curated/weather-lookup`), validates the skill's structure, and copies it into the user's local skill store.

```bash
python -m skills/.system/skill-installer/scripts/install-skill-from-github.py \
    https://github.com/openai/skills/tree/main/skills/.curated/weather-lookup \
    --dest ~/.openai/skills

```

The installer normalizes skill names and prevents path-traversal attacks, ensuring safe installation from third-party sources.

## Organize Custom Logic with Helper Scripts

Complex tasks—such as transcription with Diarize, spreadsheet styling with `openpyxl`, or Netlify deployment—should be encapsulated in small, well-named Python scripts under each skill's `scripts/` sub-folder.

This modular approach keeps the core [`openai.yaml`](https://github.com/openai/skills/blob/main/openai.yaml) definition focused on I/O contracts while allowing implementation details to evolve independently. For example, a weather skill might implement API error handling, retry logic, or response caching within [`scripts/get_weather.py`](https://github.com/openai/skills/blob/main/scripts/get_weather.py) without modifying the declarative contract.

## Document for Discovery

Comprehensive documentation ensures skills are discoverable and usable by other developers.

Each skill must include a [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) file explaining its purpose, usage examples, required environment variables, and licensing. Never commit secrets to the repository; instead, document required variables (e.g., `OPENWEATHER_API_KEY`) in the [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) and load them via environment variables in your scripts.

The repository root contains [`README.md`](https://github.com/openai/skills/blob/main/README.md) for high-level project overview and [`contributing.md`](https://github.com/openai/skills/blob/main/contributing.md) for coding standards, including requirements for type hints, linting, and testing.

## Summary

- **Use the skill-creator scaffold**: Start every skill with [`init_skill.py`](https://github.com/openai/skills/blob/main/init_skill.py) to ensure proper directory structure and metadata generation.
- **Define clear contracts**: Write explicit [`openai.yaml`](https://github.com/openai/skills/blob/main/openai.yaml) files with JSON Schema inputs/outputs and detailed system prompts.
- **Validate early**: Run [`quick_validate.py`](https://github.com/openai/skills/blob/main/quick_validate.py) before committing to catch structural errors and malformed YAML.
- **Install safely**: Use [`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py) for sparse checkouts, validation, and secure installation from remote repositories.
- **Modularize logic**: Place complex implementations in the `scripts/` directory to keep [`openai.yaml`](https://github.com/openai/skills/blob/main/openai.yaml) focused on I/O contracts.
- **Document thoroughly**: Maintain [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) with usage examples and environment requirements, following the standards in [`contributing.md`](https://github.com/openai/skills/blob/main/contributing.md).

## Frequently Asked Questions

### What is the purpose of the openai.yaml file in an OpenAI skill?

The [`openai.yaml`](https://github.com/openai/skills/blob/main/openai.yaml) file serves as the declarative contract for a skill, located at `skills/.curated/<skill>/agents/openai.yaml`. It defines the skill's inputs and outputs using JSON Schema, specifies the model and temperature, contains the system prompt, and references any custom tools or scripts. This metadata-driven approach allows the skill-installer to treat every skill uniformly, regardless of internal complexity.

### How do I validate my skill before submitting it to the repository?

Run the [`quick_validate.py`](https://github.com/openai/skills/blob/main/quick_validate.py) script from the skill-creator module to perform lightweight validation. Execute `python -m skills/.system/skill-creator/scripts/quick_validate.py <skill-path>` to check for YAML parsing errors, missing required fields, and structural inconsistencies. This validation step ensures your skill meets the repository standards before you commit or attempt installation through the skill-installer pipeline.

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

Yes, the [`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py) script can resolve and install skills from private repositories, provided your Git environment has appropriate authentication credentials (such as SSH keys or personal access tokens with repository access). The installer performs a sparse checkout of only the specific skill folder (e.g., `skills/.curated/<skill-name>`), validates the structure, and copies it to your local skill store while normalizing names and preventing path-traversal attacks.

### Where should I place custom Python logic for my skill?

Place custom Python logic in the `scripts/` subdirectory within your skill folder (e.g., `skills/.curated/<skill>/scripts/`). Reference these scripts from your [`openai.yaml`](https://github.com/openai/skills/blob/main/openai.yaml) file using the `code` field in tool definitions or by invoking them via function calls. This modular approach keeps your [`openai.yaml`](https://github.com/openai/skills/blob/main/openai.yaml) focused on the I/O contract while allowing complex implementations—such as API calls, data transformations, or external service integrations—to evolve independently in well-named helper modules.