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

> Test your OpenAI skill locally before contributing. Use quick_validate.py and skill-installer to ensure schema compliance and runtime execution. Contribute confidently.

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

---

**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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/SKILL.md) follows the required schema using [`quick_validate.py`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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:

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

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

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

```

For example, testing the screenshot skill:

```bash
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`](https://github.com/openai/skills/blob/main/SKILL.md) or scripts)
2. Re-run [`quick_validate.py`](https://github.com/openai/skills/blob/main/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:

```bash
#!/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`](https://github.com/openai/skills/blob/main/test_skill.sh), make it executable, and run:

```bash
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`](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/SKILL.md) | Authoritative guide for skill structure and metadata requirements |
| [`skills/.system/skill-creator/scripts/quick_validate.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/scripts/quick_validate.py) | Lightweight validator for [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) front-matter and naming conventions |
| [`skills/.system/skill-installer/scripts/list-skills.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/scripts/list-skills.py) | Implements the `$skill-installer` command for local deployment |
| [`skills/.curated/screenshot/scripts/take_screenshot.py`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/quick_validate.py) to verify [`SKILL.md`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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.