How to Report a Bug in an Existing OpenAI Skill: A Complete Guide

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/<skill-name>).

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 – Mandatory file describing the capability, trigger phrases, and usage
• 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 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 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.

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:

# 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 at the repository root. This file codifies community values, security contact information ([email protected] 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 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:

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), and validate:

# Clone your fork

git clone https://github.com/<your-user>/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 #<issue-number>" --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 – Repository-wide policy on bug reports and security contacts
• skills/.system/skill-creator/SKILL.md – Canonical specification for skill structure and validation requirements
• 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 – Handles $skill-installer installation, useful for reproducing install-time bugs
• skills/.curated/<skill>/SKILL.md – The actual skill definition where most bugs surface (e.g., 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 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, 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 if validation fails.

How do I reproduce a bug in an experimental skill?

Install the experimental skill using $skill-installer <skill-name> 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), run 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 and email [email protected] instead of opening a public GitHub issue. This ensures vulnerabilities are handled confidentially before public disclosure.

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