CDX-101 · Module 3

Skill Engineering

5 min read

Skills are Codex's answer to reusable, task-specific instructions. A skill is a SKILL.md file that contains structured instructions for a specific workflow — deploying to production, running a migration, generating API documentation, processing data files. Skills live in your repo or in a shared skills directory, and Codex invokes them either explicitly (via slash command) or implicitly (when it detects a matching task from your prompt).

The anatomy of a skill file is straightforward: YAML front matter with metadata (name, description, trigger words), followed by markdown instructions. The description field is critical — it determines when Codex will implicitly invoke the skill. Poor descriptions mean your skill never fires. Good descriptions include specific trigger words and phrases that match how users naturally describe the task.

---
name: production-deploy
description: >
  Deploys the application to production. Use when user says
  "deploy", "ship it", "push to prod", or "release".
trigger: deploy
---

# Production Deployment

## Pre-flight checks
1. Run `npm test` — abort if any test fails
2. Run `npm run lint` — abort on errors
3. Check for uncommitted changes — abort if dirty

## Deploy steps
1. Build: `npm run build`
2. Deploy: `npx wrangler deploy`
3. Health check: `curl -f https://api.example.com/health`

## Post-deploy
- Report success or failure with the health check result
- If failed, suggest rollback: `npx wrangler rollback`

Do This

  • Write descriptions with 3-5 specific trigger phrases users would naturally say
  • Include pre-flight checks and validation steps in every skill
  • Use progressive disclosure — start with the happy path, handle errors at the end
  • Test skills with different prompt phrasings to verify implicit invocation

Avoid This

  • Write vague descriptions like "helps with deployment tasks"
  • Create monolithic skills that try to handle every possible scenario
  • Skip error handling — the skill should know what to do when steps fail
  • Forget to include the skill in your repo so other team members can use it

The $skill-installer is a meta-skill that helps you create new skills. You can also browse and install community skills from github.com/openai/skills — a growing repository of shared skill files for common workflows.

Skill metadata in agents/openai.yaml provides additional configuration: version, dependencies, required MCPs, and compatibility information. This is optional for simple skills but important when publishing to the community.