create-skill

Create Skill

Turn a skill idea into a complete, discoverable, and shippable skill folder. Treat the skill instructions, metadata, artwork, README wiring, and validation as one deliverable.

Workflow

1. Orient the repository. Read AGENTS.md, the root README.md, the nearest existing skill with a similar purpose, and any local lessons file. Inspect package.json, skills.sh.json, the installer, and the existing assets/skill-cards/ and assets/skill-banners/ conventions before editing.

1. Define the contract. Extract the skill slug, purpose, audience, trigger phrases, inputs, outputs, and acceptance checks from the request. Normalize the slug to lowercase hyphen-case. Preserve the user's terminology, but make the frontmatter description explicit about both the capability and the situations that should trigger it.

1. Choose the smallest useful structure. Create only the resources the skill needs:

• skills/<slug>/SKILL.md for the core workflow and routing rules.
• skills/<slug>/agents/openai.yaml for display metadata and an explicit $<slug> default prompt.
• skills/<slug>/references/ for detailed domain guidance that should load progressively.
• skills/<slug>/scripts/ only for deterministic, repeatable automation.
• skills/<slug>/assets/ only for files the skill will reuse in its outputs.
• skills/<slug>/README.md because this repository documents every published skill.

Keep SKILL.md under 500 lines. Put deep specifications and long examples in one-level-deep references and link them directly from the skill.

1. Write the skill. Use imperative instructions. State the decision points, required tools, file paths, invariants, failure handling, and verification commands another agent cannot safely infer. Prefer a short workflow in SKILL.md and conditional links such as references/artwork.md for specialized work.

1. Create the required artwork. In this repository, every new skill needs assets/skill-cards/<slug>.svg and a linked row in the root README's Pick a skill table. When the collection uses cinematic banners, also create assets/skill-banners/<slug>.webp and use the banner in the root and skill READMEs. Read references/artwork.md before creating either asset.

1. Wire every discovery surface. Update all surfaces that explicitly enumerate skills: the root README card table, the skill README, skills.sh.json groupings, and any registry or installer allowlist discovered during orientation. Do not invent a new registry file. Confirm that package.json already includes the skills/ and assets/ trees; change it only if the package would otherwise omit the new files.

1. Validate before handoff. Run the skill validator, parse the SVG, inspect the rendered card and banner, check every new README link, run the repository test suite, and run git diff --check. Review the diff for stale names, placeholder text, missing metadata, broken relative paths, untracked required assets, and accidental unrelated edits.

Skill content requirements

Include these sections when relevant:

• Scope and trigger behavior: what the skill handles and what it should not handle.
• Inputs and outputs: expected files, links, user decisions, and final artifacts.
• Workflow: the smallest reliable sequence, with explicit branch points.
• Resources: when to read each reference or run each script.
• Validation: concrete commands and visual or semantic acceptance checks.
• Failure handling: what to do when a tool, dependency, reference, or user choice is missing.

Never leave TODO markers, template prose, guessed tool names, or unsupported claims in a published skill. Avoid duplicating long reference material in SKILL.md.

Artwork routing

Use the built-in image-generation tool for a new raster banner. First inspect two or more existing banners and any user-provided reference images. Treat references as style and composition guidance, not as content to copy. Generate a wide cinematic scene with exact title text only when the tool can render it reliably; inspect the result and iterate on one targeted issue at a time. Save the final project asset as WebP and keep the SVG card deterministic and accessible.

For the detailed visual system, prompt template, composition rules, conversion commands, and review checklist, read references/artwork.md.

Validation commands

From the repository root, adapt these commands to the local toolchain:

python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" skills/<slug>
xmllint --noout assets/skill-cards/<slug>.svg
npm test
git diff --check

If a command is unavailable, use the repository's documented equivalent and report the substitution. Do not call the work complete while required files are untracked or a validation check is red.