How to Propose Changes to an OpenAI Skill: A Complete Contributor's Guide

To propose changes to an OpenAI skill, fork the repository from the openai/skills GitHub organization, create a descriptive feature branch, implement your changes following the project's conventions for skill.yaml and entry point modules, run the local test suite with pytest, and submit a pull request using the provided template.

The openai/skills repository hosts self-contained skill implementations that extend OpenAI's capabilities. Whether you are fixing a bug or adding new functionality, understanding how to propose changes to an OpenAI skill ensures your contribution aligns with the project's architecture and review standards.

Understanding the OpenAI Skills Repository Structure

Each skill in the openai/skills organization is a self-contained repository with a standardized layout. Before you propose changes, familiarize yourself with these key files:

• skill.yaml – Declares the skill's name, description, parameters, and required runtime dependencies.
• main.py (or similar entry point) – Contains the executable logic that the skill runner invokes.
• requirements.txt – Lists third-party Python packages with pinned versions.
• README.md – Provides usage examples, authentication instructions, and contribution notes.
• tests/ – Houses the automated test suite that validates skill behavior.

Step-by-Step Workflow to Propose Changes to an OpenAI Skill

Follow this standardized GitHub workflow to ensure your contribution meets the repository's quality gates.

Fork and Branch

Start by creating an isolated workspace for your changes.

1. Fork the repository – Navigate to the specific skill repository under openai/skills and click Fork to create a personal copy on your GitHub account.
2. Clone your fork locally using git clone.
3. Create a new branch with a descriptive name such as fix-typo-README or add-weather-skill-support. Avoid working directly on main.

Implement Your Changes

Edit the relevant files following the project's conventions.

• Update skill.yaml if you modify the skill's interface, such as adding new parameters or changing the entry point.
• Modify the entry point module (e.g., main.py) to implement new logic or bug fixes.
• Pin dependencies in requirements.txt using exact version numbers to prevent runtime surprises.
• Follow stateless design principles – Skills should be pure functions that receive all required data via arguments and return serializable results.
• Never hard-code secrets – Use os.getenv to access API keys or tokens from environment variables.

Test Locally

Validate your changes before submitting.

Run the test suite located in the tests/ directory using the framework specified in pyproject.toml or requirements.txt:

pytest -q

Ensure all existing tests pass and add new tests for any new functionality. The repository requires comprehensive test coverage for new features before merge.

Commit and Push

Prepare your changes for review.

• Commit with a clear message following the conventional-commit style: type(scope): short description. For example: feat(weather): add temperature unit option or fix(docs): correct installation instructions.
• Push the branch to your fork: git push origin <branch-name>.

Open a Pull Request

Submit your contribution for maintainer review.

1. Navigate to the original openai/skills repository and click New pull request.
2. Select the base branch (main) and compare it with your feature branch.
3. Fill out the PR template, which requires:
   • A concise summary of the change.
   • Motivation and related issue numbers.
   • Instructions for testing the change.
   • Any breaking changes and migration notes.

Address Review Feedback

Maintainers may request additional tests, clarification, or code refactoring. Push new commits to the same branch; the PR updates automatically. Once approved and CI passes, a maintainer will merge your contribution into the official skill set.

Practical Example: Adding a Parameter to an OpenAI Skill

Here is a concrete example of proposing a change that adds a new optional parameter to a skill.

Updating the Entry Point

Modify main.py to accept a new temperature parameter:

# main.py

def run(input_text: str, *, temperature: float = 0.7) -> str:
    """Generate a response using the OpenAI chat model."""
    client = openai.ChatCompletion()
    response = client.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": input_text}],
        temperature=temperature,
    )
    return response.choices[0].message["content"]

Updating the Metadata

Reflect the new parameter in skill.yaml:

name: my-skill
description: Demonstrates how to add a temperature parameter.
parameters:
  - name: input_text
    type: string
    description: The text to process.
  - name: temperature
    type: number
    description: Sampling temperature (default 0.7)
    default: 0.7
runtime: python3.11
entrypoint: main.run

Running Tests

Validate the change locally:

$ pytest -q
..                                                                      [100%]
2 passed in 0.42s

Summary

To successfully propose changes to an OpenAI skill, follow these key practices:

• Fork and branch the specific skill repository under openai/skills before beginning work.
• Modify skill.yaml and the entry point module (e.g., main.py) while maintaining stateless design principles.
• Never commit secrets; use environment variables for API keys and tokens.
• Run pytest locally to ensure all tests pass before submitting.
• Use conventional commits and fill out the PR template completely when opening a pull request.

Frequently Asked Questions

What is the standard branch naming convention for OpenAI skill contributions?

Use descriptive, hyphenated names that indicate the purpose of the change, such as fix-typo-README, add-weather-skill-support, or feat-add-temperature-param. Avoid generic names like patch-1 or update that do not convey the change's intent to reviewers.

How do I handle breaking changes when proposing modifications to a skill?

Document all breaking changes explicitly in the pull request template under the designated section. Include migration notes that explain how existing users must update their code or configuration. If the change alters the skill.yaml interface (such as removing a parameter), ensure the version metadata reflects the impact and provide backward-compatible deprecation periods when possible.

Where should I add tests for my proposed changes?

Add new test files to the tests/ directory at the repository root, following the existing test structure. Name test files to mirror the module they validate (e.g., test_main.py for main.py). Use pytest as the test runner, and ensure your tests cover both the new functionality and edge cases. The repository requires comprehensive test coverage before merging new features.

Can I propose changes to multiple skills in a single pull request?

No, you should propose changes to only one skill per pull request. Each skill in the openai/skills organization is a separate repository, so cross-skill changes require individual PRs in their respective repositories. This isolation allows maintainers to review, test, and merge contributions independently without blocking unrelated skill updates.

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