Skill Creator

Skills are modular packages that extend AI agent capabilities with specialized knowledge, workflows, and tools. They follow the open Agent Skills specification and work across Codex and other compatible agents.

Core Principles

Concise is Key

The context window is shared. Only add information Codex does not already have. Prefer concise examples over verbose explanations.

Degrees of Freedom

Match specificity to task fragility:

• High freedom (text instructions): Multiple approaches valid, context-dependent
• Medium freedom (pseudocode/parameterized scripts): Preferred pattern exists, some variation acceptable
• Low freedom (specific scripts): Operations fragile, consistency critical

Skill Anatomy

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/      - Executable code
    ├── references/   - Documentation loaded as needed
    └── assets/       - Files used in output (templates, images)

SKILL.md Structure

Frontmatter (YAML):

• name: Skill identifier (kebab-case, max 64 chars, must match directory name)
• description: What it does AND when to trigger it (max 1024 chars). This is the primary trigger mechanism; include all "when to use" info here, not in the body.
• metadata (optional): Key-value pairs like author, version
• compatibility (optional): Environment requirements (max 500 chars)
• license (optional): License name or reference to LICENSE file

Body (Markdown): Instructions loaded after skill triggers. Keep under 500 lines.

Bundled Resources

scripts/: Executable code for deterministic, repeatable tasks. Token-efficient; may execute without loading into context.

references/: Documentation Codex reads as needed. Keeps SKILL.md lean. For files >10k words, include grep patterns in SKILL.md.

assets/: Files used in output (templates, logos, fonts). Not loaded into context, copied or modified in final output.

Do NOT Include

• README.md, CHANGELOG.md, INSTALLATION_GUIDE.md
• User-facing documentation
• Setup/testing procedures

Progressive Disclosure

Three-level loading system:

1. Metadata (~100 words) - Always in context
2. SKILL.md body (<5k words) - When triggered
3. Bundled resources (unlimited) - As needed

When approaching 500 lines, split into reference files. Reference all split files from SKILL.md with clear guidance on when to read them.

Pattern examples:

## Advanced features
- **Form filling**: See [FORMS.md](references/FORMS.md)
- **API reference**: See [REFERENCE.md](references/REFERENCE.md)

For multi-domain skills, organize by domain so Codex only loads relevant context.

Creation Process

Step 1: Understand with Examples

Gather concrete usage examples. Ask:

• What functionality should this skill support?
• What would a user say to trigger this skill?
• Can you give example requests?

Step 2: Plan Reusable Contents

For each example, identify:

• What scripts would help (repeated code)?
• What references would help (schemas, docs)?
• What assets would help (templates, boilerplate)?

Step 3: Initialize

Run the initialization script:

python3 skills/skill-creator/scripts/init_skill.py <skill-name> --path <output-directory>

Creates skill directory with SKILL.md template and example resource directories.

Step 4: Edit

Frontmatter:

• Write clear, comprehensive description with all trigger scenarios
• Example: "Comprehensive document creation and editing. Use when working with .docx files for: (1) Creating documents, (2) Editing content, (3) Tracked changes, (4) Adding comments"

Body:

• Write for another Codex instance to use
• Include non-obvious procedural knowledge
• Use imperative/infinitive form
• See references/workflows.md for workflow patterns
• See references/output-patterns.md for output templates

Resources:

• Implement scripts, references, assets identified in Step 2
• Test scripts by running them
• Delete unused example files

Step 5: Package

python3 skills/skill-creator/scripts/package_skill.py <path/to/skill-folder>

Validates and creates .skill file for distribution.

Step 6: Iterate

Use the skill on real tasks, identify struggles, update accordingly.