How to Include Scripts and Documentation in Custom Skills for Codex

Include scripts and documentation in custom skills by placing executable files and a README.md in the same directory under skills/.system, skills/.curated, or skills/.experimental, then installing with $skill-installer.

The openai/skills repository provides a standardized framework for extending Codex with custom capabilities. When building these extensions, you must organize scripts (the executable logic) and documentation (the human-readable interface) according to specific conventions that the $skill-installer recognizes. This guide explains the exact file structure, placement rules, and formatting requirements derived from the repository's source layout.

Understanding the Custom Skill Structure

Codex discovers skills as self-contained folders within the top-level skills/ directory. The repository categorizes skills into three subdirectories based on maturity and support level.

Directory Organization

Place your custom skill inside one of these three locations:

• skills/.system/ – Core skills maintained by OpenAI with full support
• skills/.curated/ – Community-contributed skills that meet quality standards
• skills/.experimental/ – Prototype skills for testing new ideas

Each skill resides in its own folder within these directories. For example, the reference implementation gh-address-comments lives at skills/.system/gh-address-comments/.

Required vs Optional Files

A functional skill requires at minimum an executable script and documentation. The complete file layout looks like this:

skills/.experimental/your-skill/
├── README.md          # Required: documentation visible to users

├── my-script.sh       # Required: executable logic (Bash, Python, or JS)

├── skill.yaml         # Optional: structured metadata for validation

└── LICENSE.txt        # Optional: legal terms for reuse

How to Include Scripts in Custom Skills

Scripts provide the executable logic that Codex agents invoke. The $skill-installer treats the entire skill folder as the runtime environment, making scripts available on the agent's path.

Script Placement and Permissions

Place your script files in the skill's root directory alongside README.md. The installer automatically makes these files executable by preserving permission bits, but you should set the executable flag before committing:

chmod +x my-script.sh

Scripts can be written in any interpreted language (Bash, Python, JavaScript) provided the agent's environment has the appropriate runtime. Reference the script using relative paths (e.g., ./my-script.sh) or ensure the shebang line is correct:

#!/usr/bin/env bash
set -euo pipefail

while [[ $# -gt 0 ]]; do

  case "$1" in
    --name)
      NAME="$2"
      shift 2
      ;;
    *)
      echo "Unknown option: $1"
      exit 1
      ;;
  esac
done

echo "Hello, ${NAME:-World}!"

How to Include Documentation in Custom Skills

Documentation lives in a README.md file at the skill's root. Codex parses this file to display help text when users query the skill.

README Structure and Content

Your README.md should include:

1. H1 Title – The skill name and brief purpose
2. Usage Section – Command-line examples in fenced code blocks
3. Installation – The $skill-installer command
4. Parameters – Explanation of inputs and outputs
5. License – Reference to LICENSE.txt

Example README.md:

# My Script Skill

A tiny skill that greets the user.

## Usage

```bash
./my-script.sh --name Alice

# → Hello, Alice!

Installation

$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/your-skill

License

MIT – see LICENSE.txt.

## Optional Metadata and Licensing

While not required for basic functionality, metadata files improve the user experience by enabling parameter validation and autocomplete.

### The skill.yaml File

Create a [`skill.yaml`](https://github.com/openai/skills/blob/main/skill.yaml) file to declare inputs, outputs, and runtime requirements:

```yaml
name: your-skill
description: Performs XYZ on a repository.
inputs:
  - name: input
    type: string
    required: true
outputs:
  - name: result
    type: string

Codex uses this manifest to validate calls and provide autocomplete hints in the interface.

License Files

Include a LICENSE.txt file to clarify reuse rights. The $skill-installer copies this file unchanged during installation, ensuring compliance information travels with the skill.

Installation and Usage Workflow

Once your skill contains scripts and documentation in the correct layout, users install it via the $skill-installer CLI:

$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/your-skill

The installer performs these actions:

1. Copies the entire skill directory to Codex's skill store
2. Preserves executable permissions on script files
3. Registers the README.md documentation for the codex help your-skill command

After installation, agents invoke the skill by name, and users view documentation using the help system.

Summary

• Place scripts and README.md at the same level in a folder under skills/.system, skills/.curated, or skills/.experimental
• Make scripts executable with chmod +x before committing to ensure the $skill-installer preserves permissions
• Document the CLI interface in README.md using fenced code blocks for usage examples
• Optionally add skill.yaml to enable parameter validation and autocomplete hints
• Include LICENSE.txt to clarify legal terms for reuse

Frequently Asked Questions

Do scripts need specific file extensions to work with the skill installer?

No, the $skill-installer does not require specific file extensions. It treats all files in the skill directory as part of the package and preserves their executable permissions regardless of extension. However, using standard extensions (.sh, .py, .js) helps users identify the runtime environment required to execute the script.

What happens if I don't include a skill.yaml file?

The skill will still function normally. The skill.yaml file is optional and serves only to enhance the user experience by providing structured metadata for parameter validation and autocomplete functionality. Without it, Codex relies solely on the README.md documentation to understand how to invoke the skill.

Can I nest scripts in subdirectories within my skill folder?

While the $skill-installer copies the entire skill directory recursively, placing scripts in subdirectories requires users to reference them with relative paths (e.g., ./subfolder/script.sh). For simplicity and compatibility with Codex's default invocation patterns, OpenAI recommends keeping primary executable scripts at the root level of the skill folder alongside the README.md.

How does Codex display the README.md content to users?

When a user runs codex help your-skill, Codex reads the README.md file from the installed skill directory and renders the markdown content in the terminal interface. The system parses fenced code blocks, headers, and lists to format the help text, making the Usage section particularly important for teaching users how to invoke your script correctly.

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