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

> Learn how to propose changes to an OpenAI skill. Fork the openai/skills repository, implement, test, and submit a pull request for your contributions.

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

---

**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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/skill.yaml)** – Declares the skill's name, description, parameters, and required runtime dependencies.
- **[`main.py`](https://github.com/openai/skills/blob/main/main.py)** (or similar entry point) – Contains the executable logic that the skill runner invokes.
- **[`requirements.txt`](https://github.com/openai/skills/blob/main/requirements.txt)** – Lists third-party Python packages with pinned versions.
- **[`README.md`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/main.py)) to implement new logic or bug fixes.
- **Pin dependencies** in [`requirements.txt`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/pyproject.toml) or [`requirements.txt`](https://github.com/openai/skills/blob/main/requirements.txt):

```bash
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`](https://github.com/openai/skills/blob/main/main.py) to accept a new `temperature` parameter:

```python

# 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`](https://github.com/openai/skills/blob/main/skill.yaml):

```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:

```bash
$ 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`](https://github.com/openai/skills/blob/main/skill.yaml)** and the entry point module (e.g., [`main.py`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/test_main.py) for [`main.py`](https://github.com/openai/skills/blob/main/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.