OpenAI Skills Code Review Guidelines: A Complete Guide for Contributors

OpenAI skills code review guidelines require contributors to use codex/ prefixed branches, write imperative one-line commit messages, and open draft PRs with structured markdown bodies that explain the problem, solution, and test coverage.

The openai/skills repository hosts self-contained skill folders that bundle instructions, scripts, and assets for Codex agents. Following the official OpenAI skills code review guidelines ensures that every contribution maintains consistency, traceability, and safety across the ecosystem. These standards are defined across several canonical files including skills/.curated/yeet/SKILL.md, contributing.md, and skills/.system/skill-creator/SKILL.md.

Branch and Naming Conventions

Every contribution must start with a properly named branch to maintain repository hygiene and searchability.

Branch Prefix Rule

All feature branches must start with codex/ followed by a short, hyphen-case description of the change. For example: codex/add-pdf-skill or codex/fix-validate-script.

Skill Folder Naming

The folder that holds the skill must match the hyphen-case name exactly (e.g., skills/.curated/pdf). According to the guidelines in skills/.system/skill-creator/SKILL.md, names must use only lowercase letters, digits, and hyphens—spaces or special characters are prohibited.

Commit Message Standards

The Yeet skill enforces a strict commit message style to maintain a clean, readable history.

• One-line summary: Write a terse, imperative description limited to approximately 50 characters.
• No trailing period: Keep the line clean (e.g., Add PDF rotation script not Add PDF rotation script.).
• Optional body: Only include additional explanation if a non-trivial decision requires context; otherwise omit the body.

The canonical format is:

git commit -m "{description}"

Where {description} matches the short phrase used in the branch name.

Pull Request Workflow

The OpenAI skills code review guidelines define a specific PR workflow using the GitHub CLI (gh) to ensure consistency.

Creating the Branch

Start from the main branch:

git checkout -b "codex/{description}"

Committing Changes

Stage all changes and commit using the imperative style:

git add -A
git commit -m "{description}"

Pushing the Branch

Push with upstream tracking:

git push -u origin $(git branch --show-current)

Opening the Draft PR

The Yeet skill requires opening a draft PR with a standardized title format. Use the following command:

GH_PROMPT_DISABLED=1 GIT_TERMINAL_PROMPT=0 \
gh pr create --draft --fill --head $(git branch --show-current)

This generates a PR title in the format [codex] {description}.

PR Body Requirements

After creating the draft, update the PR body using a markdown file that explains:

• The problem being solved
• The root cause
• The fix or solution implemented
• Any tests or checks that were added

Update the body with:

gh pr edit --body-file pr-body.md

Review Requirements

Assign at least one reviewer with domain knowledge (e.g., a security reviewer for security-related skills). Reviewers must verify proper naming, clean commit history, linted scripts, and that the skill's SKILL.md follows the "Important guidelines" section from skills/.system/skill-creator/SKILL.md (no deep nesting, TOC for long reference files).

Merge Strategy

After approval, maintainers merge using squash-and-merge to maintain linear history. The merge commit message is automatically generated from the PR title.

Review Checklist

When reviewing a PR according to the OpenAI skills code review guidelines, verify the following:

• Branch follows codex/… pattern – Ensures repository tidiness and searchability
• SKILL.md front-matter contains name and description only (no extra fields) – Guarantees Codex can trigger the skill reliably
• References are shallow – No more than one level deep from SKILL.md to avoid circular loading and keep skills lightweight
• Long reference files have a Table of Contents (if > 100 lines) – Allows Codex to preview the full file efficiently
• Scripts are executable (proper shebang, chmod) and pass the skill's quick-validate test – Prevents runtime failures at install time
• Security notice – Any new external dependencies are vetted according to the security-best-practices skill – Maintains responsible AI standards
• PR title & body follow the Yeet template (draft, full description, markdown body) – Provides clear context and ensures reproducibility

Automated Validation

The repository includes automated checks to enforce the OpenAI skills code review guidelines:

• The Yeet skill runs local checks (e.g., scripts/quick_validate.py) before a PR can be merged
• A GitHub Actions workflow defined in skills/.curated/gh-fix-ci/SKILL.md automatically runs the same validation on every PR
• If a check fails, the gh-fix-ci skill can automatically open an issue with the log snippet using skills/.curated/gh-fix-ci/scripts/inspect_pr_checks.py

Example Workflow

Here is a complete end-to-end example following the OpenAI skills code review guidelines:

# 1️⃣ Create branch

git checkout -b "codex/add-pdf-rotate"

# 2️⃣ Implement the skill (scripts, assets, references)

# ... edit files ...

# 3️⃣ Stage & commit

git add -A
git commit -m "add pdf rotate script"

# 4️⃣ Push

git push -u origin $(git branch --show-current)

# 5️⃣ Open draft PR (Yeet workflow)

GH_PROMPT_DISABLED=1 GIT_TERMINAL_PROMPT=0 \
gh pr create --draft --fill --head $(git branch --show-current)

# 6️⃣ Add detailed PR body (pr-body.md)

cat > pr-body.md <<'EOF'

# Add PDF rotation skill

## Problem

Users need to rotate PDFs without manual editing.

## Solution

Implemented `scripts/rotate_pdf.py` that uses `pdftoppm` and `pdfunite`.

## Tests

Added unit test `tests/test_rotate_pdf.py` and validated with `quick_validate.py`.

## Checklist

- [x] Branch follows naming convention
- [x] `SKILL.md` front-matter is correct
- [x] Reference files shallow, TOC added
- [x] Security review performed (no new deps)
EOF

# 6️⃣ Update PR body

gh pr edit --body-file pr-body.md

After the PR passes GitHub Actions and receives at least one reviewer approval, the maintainer merges it with Squash and merge.

Summary

• Branch naming: Use the codex/ prefix with hyphen-case descriptions to keep the repository organized and searchable.
• Commit style: Write imperative one-line summaries without trailing periods to maintain clean git history.
• PR workflow: Open draft PRs with the [codex] {description} title format and detailed markdown bodies explaining the problem, solution, and tests.
• Review criteria: Verify shallow references, proper SKILL.md front-matter, executable scripts, and security compliance before approving.
• Automation: Leverage the Yeet skill's quick_validate.py and the gh-fix-ci GitHub Actions workflow to catch issues before merge.

Frequently Asked Questions

What is the correct branch naming convention for OpenAI skills contributions?

All feature branches must start with the codex/ prefix followed by a short, hyphen-case description of the change, such as codex/add-pdf-skill or codex/fix-validate-script. This convention is enforced in skills/.curated/yeet/SKILL.md and ensures the repository remains tidy and searchable.

How should I format commit messages when contributing to the OpenAI skills repository?

Commit messages must be one-line imperative summaries limited to approximately 50 characters without a trailing period. For example, use Add PDF rotation script rather than Added PDF rotation script. or Adding PDF rotation script. This style keeps the git history clean and readable, as specified in the Yeet skill guidelines.

What checks must pass before an OpenAI skills pull request can be merged?

Before merging, a pull request must pass the Yeet skill's local validation via scripts/quick_validate.py, receive at least one approval from a domain-knowledgeable reviewer, and successfully complete the GitHub Actions workflow defined in skills/.curated/gh-fix-ci/SKILL.md. The reviewer must verify proper branch naming, shallow references in SKILL.md, executable scripts, and security compliance for any new dependencies.

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