Codex SKILL.md Template

Skill structure

my-skill/
├── SKILL.md          (required)
├── scripts/          (optional)
├── references/       (optional)
├── assets/           (optional)
└── agents/
    └── openai.yaml   (optional)

Copy the SKILL.md

---
name: ci-failure-fix
description: Use when CI is red and the failure is a concrete, reproducible check. Do not use for flaky infrastructure or product decisions.
---
 
# CI Failure Fix
 
## When to Use This Skill
Use when CI is red and the failure is a concrete, reproducible check.
 
## When Not to Use This Skill
Do not use for flaky infrastructure, secrets issues, or product decisions.
 
## Workflow
1. Read the CI logs and identify the failing check.
2. Reproduce the failure locally.
3. Apply the smallest fix.
4. Re-run the full relevant suite.
5. Summarize the root cause.
 
## Validation
- The CI command passes locally.
- The same failing test now passes.
- No unrelated tests are skipped or deleted.
 
## Safety Rules
- Do not remove failing tests.
- Do not disable lint or type checks.
- Stop and escalate if blocked.

Use it in a real task

Use a deliberately small CI repair with a known failing test. Ask Codex to apply the skill and preserve the original test. A valid trial records the baseline failure, limits the edit to the responsible files, reruns the focused and broader checks, and leaves commit or merge approval with a person. This tests both the workflow and the exit boundary without exposing a large production change.

1. 01

   Create .agents/skills/ci-failure-fix/SKILL.md in the repository so the workflow travels with the code and can be reviewed in the same change history.

2. 02

   Replace the example command and boundaries with the repository's real checks, keeping long reference material outside the main SKILL.md so the trigger remains easy to understand.

3. 03

   Open Codex from the repository, list or mention the skill explicitly for the first trial, and use a failure whose baseline can be reproduced before any edit is made.

Verify before relying on it

• Codex discovers the repository skill and reports the expected workflow before changing files.
• The final evidence includes the original failing command, the passing rerun, and a scoped diff with no skipped checks.
• When the failure is infrastructure-related or unreproducible, the skill stops and reports the blocker instead of inventing a code fix.

Common mistakes and recovery

Good skill checklist

• Front-load the key use case and trigger words in the description
• Say clearly when the skill should and should not trigger
• Keep the SKILL.md body short; move long material to references/
• Make validation machine-checkable
• Include explicit safety rules and an escalation condition

Sources