| name | create-skill |
| description | Single entry for authoring, auditing, and optimizing Codex skills under .codex/skills/NAME. Three lanes: Create scaffolds a folder and SKILL.md template; Audit runs deterministic checks over frontmatter, naming, body size, description quality, and reference integrity; Optimize fixes audit findings such as description rewrites, body to references split, frontmatter repair, and name normalization. Use when the operator says create a skill, scaffold a skill, add SKILL.md, audit a skill, check skills, validate skill conformance, optimize a skill, fix a skill description, shrink a skill, or why is this skill not activating. |
| allowed-tools | Read, Write, Edit, Bash, AskUserQuestion |
create-skill — author, audit, optimize
Self-validate after edits. Any change to this skill's files (SKILL.md, scripts/, references/, templates/, assets/) must be followed by ./scripts/validate.sh from the skill directory. Hard findings → create-skill Optimize lane.
Router skill. Body holds only what's needed at every activation: lane selection, universal invariants, and pointers. Lane procedure loads on demand from references/.
Entry — pick a lane
First action is AskUserQuestion:
Skip the question when the typed prompt names a lane unambiguously:
| Phrase pattern | Lane |
|---|
| "create / scaffold / add a skill for X" | Create |
| "audit / check / validate skill(s)" | Audit |
| "optimize / shrink / fix / repair / why isn't X activating" | Optimize |
| anything ambiguous ("work on a skill", "review skills") | Ask. |
Spec at a glance
| Field | Required | Constraint |
|---|
name | yes | kebab-case ^[a-z][a-z0-9]*(-[a-z0-9]+)*$, equals directory name |
description | yes | ≤ 1024 chars (spec); local style permits longer for activation precision |
allowed-tools | no | space-separated string or list; minimize |
Full spec + name validation rules + progressive-disclosure budgets: references/spec.md.
Description authoring guide + trigger brainstorming: references/description.md.
Per-check rationale + finding→fix mapping: references/checklist.md.
Audit at a glance
python3 .codex/skills/create-skill/scripts/audit.py --all
python3 .codex/skills/create-skill/scripts/audit.py <skill> --strict
python3 .codex/skills/create-skill/scripts/audit.py <skill> --json
Exit 0 = clean or soft-only. Exit 1 = hard findings → switch to Optimize lane.
Hard rules (universal — apply to every lane)
- Audit before edit. Never modify a SKILL.md without running
scripts/audit.py first. Audit output IS the input to Optimize lane.
- Name == directory. Renaming is coordinated: dir + frontmatter + every cross-reference in one commit.
- Body is a router, not a content dump. Bulk →
references/. ≤ 5000 tokens (soft warn), ≤ 15000 (hard fail). This skill is the canonical demonstration.
- Trigger words are operator words. Descriptions activate on the vocabulary operators actually type, not internal jargon. See references/description.md.
scripts/ is deterministic. No model-in-the-loop. If the operation needs judgment, it belongs in the body or a reference, not a script.- No skills outside
.codex/skills/. AGENTS.md § Surface Ownership names this directory as the canonical home for executable governance.
Cross-references
