# How to Report a Bug in an Existing OpenAI Skill: A Complete Guide > Learn how to report a bug in an existing OpenAI skill. Follow our guide to file a GitHub issue with all necessary details for a quick resolution. - Repository: [OpenAI/skills](https://github.com/openai/skills) - Tags: how-to-guide - Published: 2026-02-16 --- **To report a bug in an existing OpenAI skill, file a GitHub issue in the `openai/skills` repository with a reproducible description, environment details, and the specific skill path (e.g., `skills/.curated/`).** OpenAI Skills are self-contained capability folders designed for the Codex agent. When you encounter defects in curated or experimental skills—whether incorrect instructions, broken scripts, or inaccurate metadata—knowing how to report a bug in an existing OpenAI skill ensures maintainers can triage and fix issues efficiently. ## Understanding the OpenAI Skills Architecture Before filing a report, you need to understand how skills are structured. This knowledge helps you pinpoint exactly where the defect lives. ### Skill Folder Structure Each skill is a folder that serves as the canonical unit of deployment. According to the source code in `openai/skills`, skills reside in: - `skills/.curated/` – Publicly released, production-ready skills - `skills/.experimental/` – Work-in-progress skills Every skill folder contains: - **[`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md)** – Mandatory file describing the capability, trigger phrases, and usage - **[`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml)** – Optional agent configuration - **`scripts/`** – Optional executable scripts - **`references/`** – Optional reference materials - **`assets/`** – Optional binary assets ### The Role of SKILL.md and Validation The [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) file uses front-matter to drive triggering. Bugs often stem from malformed `name` or `description` fields that prevent the skill from being discovered. The repository uses [`skills/.system/skill-installer/scripts/quick_validate.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/scripts/quick_validate.py) to validate skills during CI. Any failing validation blocks merges, so include validation output in your bug report if applicable. ## Step-by-Step Guide to Reporting Bugs Follow this workflow to ensure your report is reproducible, well-scoped, and actionable. ### 1. Identify the Affected Skill Locate the skill directory under `skills/.curated/` or `skills/.experimental/`. Note the exact folder name—this is the canonical unit of versioning, and any bug fix must stay inside this directory. For example, the `yeet` skill lives at [`skills/.curated/yeet/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.curated/yeet/SKILL.md). ### 2. Verify and Reproduce the Bug Run any bundled scripts from the `scripts/` directory to confirm the failure. If the skill is experimental, use the skill-installer: ```bash # Install the skill (example: yeet) $skill-installer yeet # Run a script that the skill ships cd skills/.curated/yeet/scripts python3 example_script.py ``` Capture any tracebacks or error messages. Reproducible failures make issues actionable for maintainers. ### 3. Review the Contribution Guidelines Read [`CONTRIBUTING.md`](https://github.com/openai/skills/blob/main/CONTRIBUTING.md) at the repository root. This file codifies community values, security contact information (`security@openai.com` for vulnerabilities), and the requirement to include minimal reproduction steps. ### 4. Create a Minimal Reproducible Description Structure your bug report with: - **Title**: Mention the skill name and symptom (e.g., "`yeet` – PR description not rendered in GitHub PR") - **Steps to reproduce**: Command lines, expected vs. actual output - **Environment details**: `$skill-installer` version, OS, Python version - **Validation output**: If [`quick_validate.py`](https://github.com/openai/skills/blob/main/quick_validate.py) fails, include the logs ### 5. Open a GitHub Issue Use the web UI at `https://github.com/openai/skills/issues/new` or the GitHub REST API: ```bash REPO="openai/skills" TOKEN="YOUR_PERSONAL_ACCESS_TOKEN" TITLE="Bug in \`yeet\`: PR description not rendered" BODY="**Skill**: yeet **Problem**: The PR description generated by the skill contains escaped newlines..." curl -X POST \ -H "Authorization: token $TOKEN" \ -H "Accept: application/vnd.github+json" \ https://api.github.com/repos/$REPO/issues \ -d "$(jq -n --arg title "$TITLE" --arg body "$BODY" '{title: $title, body: $body, labels: ["bug"]}')" ``` Assign the `bug` label. If the fix is straightforward, request the "good first issue" label for newcomers. ### 6. Optional: Submit a Fix Fork the repository, edit the offending files (e.g., [`skills/.curated/yeet/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.curated/yeet/SKILL.md)), and validate: ```bash # Clone your fork git clone https://github.com//skills.git cd skills # Create a branch git checkout -b fix/yeet-pr-body-escaping # Edit files sed -i '' 's/\\n/\n/g' skills/.curated/yeet/SKILL.md # Validate scripts/quick_validate.py skills/.curated/yeet # Commit and push git add skills/.curated/yeet/SKILL.md git commit -m "Fix PR body newline escaping in yeet skill" git push origin fix/yeet-pr-body-escaping # Open PR gh pr create --title "Fix PR body newline escaping in yeet" \ --body "Closes #" --base main --head fix/yeet-pr-body-escaping ``` The skill-creation workflow encourages contributors to ship fixes alongside bug reports, speeding up resolution. ## Key Files and Scripts for Bug Reporting Understanding these files helps you write precise bug reports: - **[`CONTRIBUTING.md`](https://github.com/openai/skills/blob/main/CONTRIBUTING.md)** – Repository-wide policy on bug reports and security contacts - **[`skills/.system/skill-creator/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/SKILL.md)** – Canonical specification for skill structure and validation requirements - **[`skills/.system/skill-installer/scripts/quick_validate.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/scripts/quick_validate.py)** – CI validation script that checks front-matter, naming, and folder layout - **[`skills/.system/skill-installer/scripts/install-skill-from-github.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/scripts/install-skill-from-github.py)** – Handles `$skill-installer` installation, useful for reproducing install-time bugs - **`skills/.curated//SKILL.md`** – The actual skill definition where most bugs surface (e.g., [`skills/.curated/yeet/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.curated/yeet/SKILL.md)) ## Summary - **Scope your bug** to a specific skill folder under `skills/.curated/` or `skills/.experimental/`. - **Reproduce locally** using `$skill-installer` and scripts from the skill's `scripts/` directory. - **Validate** your findings against [`quick_validate.py`](https://github.com/openai/skills/blob/main/quick_validate.py) and include any validation errors in your report. - **Document** environment details, steps to reproduce, and expected vs. actual behavior. - **File** a GitHub issue with the `bug` label at `https://github.com/openai/skills/issues`. - **Fix** the bug by editing files within the skill folder only, validating with [`quick_validate.py`](https://github.com/openai/skills/blob/main/quick_validate.py), and submitting a pull request that references the issue. ## Frequently Asked Questions ### What information should I include when reporting a bug in an OpenAI skill? Include the skill name and path (e.g., `skills/.curated/yeet`), a descriptive title mentioning the symptom, steps to reproduce with exact commands, expected versus actual output, environment details (`$skill-installer` version, OS, Python version), and any output from [`scripts/quick_validate.py`](https://github.com/openai/skills/blob/main/scripts/quick_validate.py) if validation fails. ### How do I reproduce a bug in an experimental skill? Install the experimental skill using `$skill-installer ` after locating it in `skills/.experimental/`. Navigate to the skill's `scripts/` directory and execute the relevant Python scripts. Capture any tracebacks or error messages to include in your GitHub issue. ### Can I fix a bug myself and submit a pull request? Yes. Fork the `openai/skills` repository, create a branch for your fix, edit only the files within the specific skill folder (e.g., [`skills/.curated/yeet/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.curated/yeet/SKILL.md)), run [`scripts/quick_validate.py`](https://github.com/openai/skills/blob/main/scripts/quick_validate.py) to ensure the skill still validates, commit your changes, push to your fork, and open a pull request referencing the original issue. ### Where do I report security vulnerabilities in OpenAI skills? For security-related bugs, follow the disclosure process described in [`CONTRIBUTING.md`](https://github.com/openai/skills/blob/main/CONTRIBUTING.md) and email `security@openai.com` instead of opening a public GitHub issue. This ensures vulnerabilities are handled confidentially before public disclosure.