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

The best practices for developing OpenAI skills involve using the skill-creator scaffold to generate metadata-driven definitions, validating with 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 to create a new skill skeleton. This script generates the required folder hierarchy, including the agents/ directory for the openai.yaml definition and a SKILL.md file for documentation.

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 (auto-filled with placeholders)
• SKILL.md with standardized front-matter
• scripts/ directory for custom logic

Automate Metadata Generation

The generate_openai_yaml.py script transforms the front-matter from SKILL.md into a fully-typed 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 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. Specify the model, temperature, and provide a detailed system prompt to ensure deterministic behavior.

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)

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 using the code field or tool definitions.

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 script in the skill-creator module performs lightweight sanity checks on the skill's structure and required fields.

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 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 to enumerate all curated skills available in the repository:

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

Install from GitHub

The 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.

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 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 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 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 and load them via environment variables in your scripts.

The repository root contains README.md for high-level project overview and 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 to ensure proper directory structure and metadata generation.
• Define clear contracts: Write explicit openai.yaml files with JSON Schema inputs/outputs and detailed system prompts.
• Validate early: Run quick_validate.py before committing to catch structural errors and malformed YAML.
• Install safely: Use 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 focused on I/O contracts.
• Document thoroughly: Maintain SKILL.md with usage examples and environment requirements, following the standards in contributing.md.

Frequently Asked Questions

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

The 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 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 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 file using the code field in tool definitions or by invoking them via function calls. This modular approach keeps your 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.

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