Skip to content

Author skills

A skill is a self-contained capability Codex can invoke. Each skill lives in its own directory under .agents/skills/<skill-name>/ with a SKILL.md plus optional bundled resources. Codex scans .agents/skills from the working directory up to the repository root.

A good SKILL.md is what reviewers actually evaluate. It must read like a contract — inputs, MCP dependencies, workflow, output, guardrails, validation — not a free-form note.

File Layout

<your-project-repo>/
└── .agents/
    └── skills/
        └── <skill-name>/
            ├── SKILL.md              # required
            ├── scripts/              # optional: deterministic helpers
            ├── references/           # optional: docs loaded into context
            └── assets/               # optional: templates, icons, outputs

Frontmatter

Every Codex skill must declare name and description in SKILL.md frontmatter. Keep runtime instructions in the body; optional Codex UI metadata belongs in agents/openai.yaml, not in custom frontmatter fields.

---
name: skill-name
description: |
  What this skill does AND when to trigger it.
  Include the phrases and contexts the model should pattern-match on,
  e.g. "alert mentions 'DB Space Utilization'", "user asks for a code review",
  or "question involves PCC question routing".
---

The description field is the primary signal Codex uses for implicit invocation. Users and project instructions can also invoke a skill explicitly. Describe both what the skill does and the contexts in which it should fire, and be explicit about trigger phrases.

Body Template

Keep these sections; reviewers look for them:

Size guideline: Keep SKILL.md under 300 lines. Files longer than that risk context overflow and memory loss mid-task. Move supplementary material — detailed examples, taxonomy tables, API reference snippets — into references/. The agent loads them on demand without bloating the base skill.

For a production example that follows this pattern, see cce-db-space-utilization in PCC-Agent-Team: the core SKILL.md stays concise while domain-specific reference material lives under references/.

# <Skill Name>

## Goal
What outcome this skill produces in one or two sentences.

## Inputs
- required_input_1
- required_input_2
- optional_input_3 (optional)

## MCP dependencies
- <mcp-name> (read)
- <mcp-name> (gated — approval required for ...)

## Workflow
1. Step one.
2. Step two.
3. Stop before any state-changing action unless approval policy allows it.

## Output
- normalized evidence
- decision summary
- recommended next action or executed action when approval allows
- reason the skill stopped, escalated, or asked for approval

## Guardrails
- never <forbidden action>
- never include raw secrets or PII in output

## Validation
- one smoke-test record linked in the PR

Bundled Resources

  • scripts/ — deterministic helpers (parsing, formatting, computation). Prefer scripts over LLM prose for anything that has a single correct answer.
  • references/ — Markdown loaded into the agent's context when the skill runs. Useful for stable domain knowledge, taxonomy tables, or example outputs. Use this to keep SKILL.md under 300 lines.
  • assets/ — templates, icons, or other static output material.

Authoring With skill-creator

Writing a good SKILL.md from scratch is iterative. Codex includes the skill-creator skill to generate, optimize, and evaluate skill files.

Invoke it directly from Codex:

$skill-creator

Once installed, provide it with relevant context (domain docs, API reference, process description) and ask it to:

  • Generate — "Use skill-creator to create a skill for [your use case]." It produces a structured SKILL.md following the body template above.
  • Optimize — "Optimize this skill" — improves trigger phrases, workflow steps, and guardrails.
  • Evaluate — "Evaluate this skill" — scores it against quality criteria and identifies gaps.

The quality of the output depends heavily on the context you supply. Paste in the relevant documentation or describe the exact workflow before prompting.

Example Skill (ems-alert-triage)

---
name: ems-alert-triage
description: Gather evidence and recommend the next step when a user asks to triage or investigate a PCC EMS alert.
---

# EMS Alert Triage

## Goal
Investigate an alert, collect the minimum evidence set, and return a decision summary.

## Inputs
- alert_id
- service_name
- severity (optional)

## MCP dependencies
- emsapi (read)
- service_info (read)
- servicenow (gated — approval required for ticket updates)

## Workflow
1. Fetch alert details from emsapi.
2. Pull service metadata and related incidents.
3. Summarize evidence.
4. Stop before any state-changing action unless approval policy allows it.

## Output
- evidence summary
- recommended next action
- escalation criteria

## Guardrails
- never write to ServiceNow without explicit approval
- never include raw secrets or PII in output

## Validation
- one smoke-test record linked in the PR

Local Testing Before EAP Deployment

Skills must be stable before they run in the EAP production runtime. Flaky skills cause agent failures that are hard to debug remotely.

  • Run at least 5 independent threads — start a fresh Codex thread each time instead of reusing the same context. Independent runs surface corner cases and non-deterministic behavior that one long thread hides.
  • Record the local model — select an appropriate model available to your local Codex account and record it with the result. Do not put model configuration in AGENTS.md. EAP staging is the authoritative test with the production model and Cisco LLM Proxy configuration. See LLM proxy and models.
  • Log failures — note every unexpected pause, guardrail trigger, or wrong output. Refine the skill and repeat until behaviour is consistent across all runs before opening a PR.

Common Mistakes

  • vague description that doesn't list trigger phrases or contexts, which makes implicit invocation unreliable
  • adding runtime or presentation settings as custom SKILL.md frontmatter instead of using the skill body or agents/openai.yaml
  • listing MCP dependencies in prose but not under a clear MCP dependencies heading
  • workflow steps that don't say where to stop — every skill needs an explicit pause point for risky actions
  • shipping a skill without a smoke-test record

Next