How to Test a Skill Before Submitting a Contribution to OpenAI Skills

Run python skills/.system/skill-creator/scripts/quick_validate.py <skill_path> to verify static schema compliance, then use $skill-installer <skill_path> to deploy locally and confirm runtime execution before opening a pull request.

Before submitting a contribution to the openai/skills repository, you must ensure your skill passes both static validation and runtime testing. This guide explains how to test a skill before submitting a contribution using the official validation tools and local installation methods provided in the repository.

Understanding Skill Structure and Testing Requirements

A skill is a self-contained folder that must include a SKILL.md file with YAML front-matter defining the name and description fields. According to the skill anatomy documented in skills/.system/skill-creator/SKILL.md, optional sub-folders include agents/, scripts/, references/, and assets/.

To verify your contribution works correctly, you must complete two validation phases:

1. Static validation – Verify SKILL.md follows the required schema using quick_validate.py
2. Runtime sanity check – Install the skill locally using $skill-installer and verify execution

Step-by-Step Guide to Test a Skill Before Submitting

Step 1: Validate SKILL.md Syntax with quick_validate.py

The skills/.system/skill-creator/scripts/quick_validate.py script performs lightweight validation of your skill's metadata. This tool checks for:

• Presence of SKILL.md in the skill folder
• Correct YAML delimiters (---)
• Required front-matter fields (name, description)
• Hyphen-case naming conventions
• Length limits (≤ 64 characters for names)
• Disallowed characters in the description

Run the validator from the repository root:

python skills/.system/skill-creator/scripts/quick_validate.py path/to/your/skill

If the script returns "Skill is valid!", proceed to runtime testing. If errors appear, fix the SKILL.md front-matter and re-run the validator.

Step 2: Install the Skill Locally Using skill-installer

After static validation, verify the skill functions correctly in a live environment. The $skill-installer command, implemented in skills/.system/skill-installer/scripts/list-skills.py, copies the skill into your local Codex skill directory and refreshes the skill index.

Install your skill locally:

$skill-installer path/to/your/skill

This command:

• Copies the skill folder to the Codex skills directory
• Updates the internal skill registry
• Makes the skill available for immediate invocation

Step 3: Execute Runtime Sanity Checks

Once installed, exercise the skill to confirm runtime integrity:

1. Restart Codex or reload the skill list to refresh the available skills
2. Invoke via UI – Type a prompt matching the skill's description field to trigger execution
3. Test bundled scripts directly – If the skill includes scripts, run them manually to verify outputs:

python path/to/your/skill/scripts/your_script.py <arguments>

For example, testing the screenshot skill:

python skills/.curated/screenshot/scripts/take_screenshot.py --platform macos --output /tmp/test.png

Watch for runtime errors, missing assets, permission issues, or traceback messages in the console output.

Step 4: Iterate and Fix Issues

If validation or runtime errors appear:

1. Edit the offending file (SKILL.md or scripts)
2. Re-run quick_validate.py to confirm static fixes
3. Re-install the skill using $skill-installer
4. Re-test execution

Repeat until both static validation passes and runtime behavior matches expectations.

Automated Testing Script

For convenience, combine both validation steps into a single bash script:

#!/usr/bin/env bash
SKILL_DIR=$1

python skills/.system/skill-creator/scripts/quick_validate.py "$SKILL_DIR" && \
  $skill-installer "$SKILL_DIR" && \
  echo "✅ Skill installed and validated. Now try it in Codex."

Save this as test_skill.sh, make it executable, and run:

chmod +x test_skill.sh
./test_skill.sh ./skills/.curated/gh-address-comments

This one-liner ensures you never submit a contribution that fails basic validation.

Key Files for Testing Skills

Understanding these repository files helps you debug issues when you test a skill before submitting a contribution:

File	Purpose
skills/.system/skill-creator/SKILL.md	Authoritative guide for skill structure and metadata requirements
skills/.system/skill-creator/scripts/quick_validate.py	Lightweight validator for SKILL.md front-matter and naming conventions
skills/.system/skill-installer/scripts/list-skills.py	Implements the $skill-installer command for local deployment
skills/.curated/screenshot/scripts/take_screenshot.py	Example script demonstrating test-mode helpers and runtime validation patterns

Summary

• Static validation is mandatory: always run quick_validate.py to verify SKILL.md schema compliance before submitting.
• Local installation via $skill-installer confirms the skill integrates correctly with the Codex runtime environment.
• Runtime testing requires exercising bundled scripts and verifying execution through the Codex UI.
• Iterative fixes follow the cycle: edit → validate → install → test until no errors remain.

Frequently Asked Questions

What does quick_validate.py check in my SKILL.md file?

The validator checks for the presence of SKILL.md, correct YAML front-matter delimiters (---), required fields (name and description), hyphen-case naming conventions, length limits of 64 characters for names, and disallowed characters in descriptions. It returns "Skill is valid!" only when all schema requirements pass.

Can I test a skill without installing it in Codex?

You can perform static validation without a full Codex environment by running python skills/.system/skill-creator/scripts/quick_validate.py <path>. However, runtime sanity checks require local installation via $skill-installer to verify the skill executes correctly within the Codex runtime and that bundled scripts function as intended.

How do I fix validation errors in my skill contribution?

Edit the SKILL.md file to correct YAML front-matter issues (such as invalid naming conventions or missing required fields) or fix script errors in the scripts/ directory. After editing, re-run quick_validate.py to confirm static fixes, then re-install the skill using $skill-installer and re-test execution to verify runtime behavior.

Where can I find example skills to reference for testing patterns?

The skills/.curated/ directory contains production-ready examples. Specifically, skills/.curated/screenshot/scripts/take_screenshot.py demonstrates how to implement test-mode helpers and runtime validation patterns, while skills/.curated/gh-address-comments provides a complete reference for skill structure and metadata configuration.

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