Skill Builder

Skill Name: Skill-Builder

Description: Guide for creating new skills to extend agent capabilities, following the OpenAI Codex CLI skills standard.

Overview

Skills are modular, reusable packages of instructions that help AI agents perform specific tasks reliably. This skill documents how to create, structure, and add new skills to the Skills/ folder.

Skill Folder Structure

Based on OpenAI's Codex CLI skills framework:

Skills/ ├── README.md # Skill catalog + routing guide ├── my-skill/ # Skill folder (use kebab-case) │ ├── SKILL.md # Required: Main instructions + metadata │ ├── scripts/ # Optional: Executable code/automation │ ├── reference/ # Optional: Additional documentation │ └── assets/ # Optional: Templates, images, resources │ ├── skill-builder/SKILL.md # This skill — how to create new skills └── _internal/ # Platform dev docs (not discoverable skills)

Creating a New Skill

Option 1: Single-File Skill (Simple)

For straightforward skills, create a single .md file:

name: My Skill Name description: Brief description of what this skill does metadata: short-description: One-line summary

My Skill Name

Skill Name: My-Skill-Name
Description: Detailed description of the skill's purpose.

Overview

[What this skill does and when to use it]

Instructions

[Step-by-step guide]

Examples

[Code samples or usage examples]

References

[Links to relevant documentation]

Option 2: Folder-Based Skill (Complex)

For skills with scripts, assets, or extensive documentation:

Skills/ └── My-Complex-Skill/ ├── SKILL.md # Main skill file (required) ├── scripts/ │ └── setup.sh # Automation scripts ├── references/ │ └── api-docs.md # Supporting documentation └── assets/ └── template.json # Templates or resources

SKILL.md Template

name: [Skill Name] description: [What this skill helps accomplish - used for skill selection] metadata: short-description: [One-line summary for UI display] version: 1.0.0 author: [Your name or team] tags: [api, database, frontend, etc.]

[Skill Name]

Overview

[Comprehensive description of the skill's purpose and use cases]

Prerequisites

• [Required knowledge or setup]
• [Dependencies]

Instructions

Step 1: [First Action]

[Detailed instructions]

Step 2: [Second Action]

[Detailed instructions]

Verification

• [How to verify the skill worked correctly]

Troubleshooting

References

• [Link to relevant documentation]
• [Related skills or resources]

Skill Naming Conventions

Convention Example Usage

Kebab-case Add-Data-Type-CRUD.md

File names

Title Case Add Data Type CRUD

Skill display name

Descriptive How to add new data type...

Description field

Best Practices

• RFC 2119 Constraints: Use MUST/SHOULD/MAY with rationale clauses in all enforcement sections (see Writing Standard below)

• Progressive Disclosure: Put the most important info first; details later

• Actionable Steps: Use numbered lists for procedures

• Code Examples: Include working code snippets

• Verification: Always include a way to verify success

• Links: Reference source files with relative paths

Writing Standard: RFC 2119 Constraints

All skills use RFC 2119 keywords to express enforcement levels. This replaces informal patterns like "always", "never", "important", and "prefer" in rule sections.

Inspired by Amazon's Agent SOPs from the Strands SDK — natural language markdown with formal requirement keywords creates a middle ground between rigid code and freeform prompting.

Keywords

Keyword Meaning Agent Behavior When to Use

MUST / MUST NOT Absolute requirement Agent fails the task if violated Data integrity, security, user trust, API correctness

SHOULD / SHOULD NOT Strong default Follow unless you state explicit reasoning to deviate Best practices, performance, quality patterns

MAY Agent discretion Choose either way without justification Optimization hints, convenience, stylistic choices

Rationale Clauses

Every constraint gets a "because" rationale after an em dash. This gives the agent context to make good decisions in edge cases rather than blindly following rules.

Format:

• MUST [do X] -- because [consequence of not doing it].
• SHOULD [do Y] -- because [benefit, with acceptable override conditions].
• MAY [do Z] -- because [benefit when applicable].

Before/After examples:

Before: "ALWAYS show the admin what you're about to change before calling the API." After: "MUST show the admin the proposed change before calling any mutating API -- because silent modifications erode trust and prevent catching errors before they reach production."

Before: "Prefer section-level updates over full replace." After: "SHOULD use section-level updates over full replace -- because scoped edits reduce blast radius and allow concurrent editing; override only when structural reorganization requires full rewrite."

Before: "Optionally add an IF node to check success." After: "MAY add an IF node after the API call to check success -- because explicit success checks simplify debugging in complex workflows."

Section Naming

Use ## Constraints (H2) for top-level enforcement sections. Use ### Constraints (H3) for per-action constraints within a dispatch skill.

Do NOT use: "Critical Rules", "Key Rules", "Important Rules", "Guardrails". The three-tier MUST/SHOULD/MAY gradient replaces severity signaling.

Balance Check

Not everything should be MUST. A skill with zero SHOULD or MAY rules is probably over-constraining. The gradient exists so agents can exercise judgment on best practices while never violating safety-critical requirements.

SOP Files (.sop.md)

For procedural workflows (multi-step processes with sequenced actions, branching, and explicit success criteria), create a .sop.md file alongside or instead of a SKILL.md.

When to Use .sop.md vs SKILL.md

Signal Use SKILL.md

Use .sop.md

Multiple independent actions Yes No

Dispatch table ("jump to action") Yes No

Linear procedure with ordered steps No Yes

Steps have pre/post-conditions No Yes

Branching decision points Either Yes (preferred)

Measurable success criteria Either Yes (preferred)

Both formats use the same RFC 2119 keywords and rationale clauses.

SOP Template

name: [procedure-name] description: [what this SOP accomplishes] type: sop metadata: version: 1.0.0 author: [your name or team]

SOP: [Procedure Name]

Overview

[What this procedure does, when to use it, expected duration]

Parameters

Pre-conditions

• [What MUST be true before starting]

Steps

Step 1: [Action Name]

[Instructions]

Constraints:

• MUST [requirement] -- because [rationale].
• SHOULD [recommendation] -- because [rationale].

Step 2: [Action Name]

[Instructions]

Constraints:

• MUST [requirement] -- because [rationale].
• MAY [option] -- because [rationale].

Success Criteria

• [Measurable outcome 1]
• [Measurable outcome 2]

Artifacts

Skills Catalog & Routing

For the full skill catalog and routing guide, see the Skills README.

References

• OpenAI Codex CLI - Skills Documentation

• OpenAI Skills Repository

• OpenAI Agents SDK