Skill Creator

Skill Creator

Guide for creating effective Codex skills.

What Skills Are

Skills are modular packages that extend Codex's capabilities with specialized knowledge, workflows, and tools. They transform Codex from a general-purpose agent into a domain expert.

Default assumption: Codex is already smart. Only add context it doesn't have. Challenge each piece: "Does this justify its token cost?"

Skill Structure

skill-name/
├── SKILL.md           # Required - main instructions
├── agents/
│   └── openai.yaml    # Optional - UI metadata and MCP dependencies
├── references/        # Optional - detailed docs loaded on-demand
├── scripts/           # Optional - executable code
└── assets/            # Optional - templates, images, files for output

SKILL.md (Required)

---
name: my-skill
description: What it does AND when to use it. Include trigger keywords.
---

# My Skill

## Quick Start
[Essential workflow - what to do first]

## Patterns
[Show correct patterns with code examples]

## Anti-Patterns
[Show what to avoid with code examples]

## Reference
- See [detailed-ref.md](references/detailed-ref.md) for more

Key rules:

• Keep under 500 lines (use references/ for details)
• Description is the trigger - include all "when to use" info there
• Show examples over explanations
• Imperative form: "Use X" not "You should use X"

agents/openai.yaml (Optional)

UI metadata for skill discovery:

interface:
  display_name: "User-facing Name"
  short_description: "Brief description (25-64 chars)"
  default_prompt: "Use $skill-name to do X"

References (Optional)

For detailed docs loaded only when needed:

references/
├── patterns.md      # Detailed code patterns
├── api-docs.md      # API reference
└── examples.md      # More examples

Keep references one level deep. For large files (>100 lines), add a table of contents.

Skill Discovery

Codex scans these locations for skills at startup:

Skills activate when:

• You mention a skill by name (e.g., "use brainstorming")
• The task matches a skill's description field
• You invoke with $skill-name or /skills

Examples

Simple Skill

Just create the folder with SKILL.md:

~/.agents/skills/code-review/
└── SKILL.md

Skill with References

ddd-patterns/
├── SKILL.md              # Core workflow
└── references/
    ├── aggregates.md     # Aggregate patterns
    ├── repositories.md   # Repository patterns
    └── services.md       # Service patterns

SKILL.md references these only when relevant:

## Aggregates
See [references/aggregates.md](references/aggregates.md) for patterns.

Best Practices

Do:

• Keep SKILL.md under 500 lines
• Show concrete code examples
• Use references/ for detailed docs
• Make description specific to avoid false positives
• Test skill activation before deploying

Don't:

• Over-explain concepts (show patterns instead)
• Include README, CHANGELOG, or meta-docs
• Duplicate info between SKILL.md and references

Creating a New Skill

1. Create folder: mkdir -p ~/.agents/skills/my-skill
2. Create SKILL.md with frontmatter and instructions
3. Optionally add agents/openai.yaml for UI metadata
4. Test with $my-skill or trigger keywords
5. Iterate based on real usage