Terms in this guide: Evaluation · Prompt · Skill
Turn a procedure you already understand into a focused skill with a precise trigger, inspectable files, and a useful evaluation record.
1. Choose a procedure worth preserving
Start with work you have repeated enough to understand: reviewing a WordPress layout, preparing a release note, or collecting evidence for a change handoff. Write the decisions that make the procedure successful and remove generic instructions Codex already handles.
Define the output. A review skill might promise prioritized findings with page locations and evidence. A content brief skill might produce intent, reader questions, source requirements, and an internal-link plan. A clear output keeps the instructions from becoming a bag of advice.
2. Write the discovery fields
Use a short lowercase hyphenated name. In the description, lead with what the skill does and when it applies. Add a boundary only when it prevents a likely wrong match. Discovery depends heavily on the description, so vague labels such as helper or assistant provide little signal.
---
name: wordpress-layout-review
description: Review a rendered WordPress page for hierarchy and responsive layout defects. Use when a user asks for a visual layout audit.
---3. Write the minimum useful workflow
Tell Codex what evidence to inspect, which distinctions matter, and what a successful result contains. Preserve user scope and authorization. If multiple approaches are reasonable, give decision criteria instead of forcing a sequence that fits only the example that inspired the skill.
Keep the main SKILL.md focused. Put a substantial checklist, schema, or domain policy in references and tell the skill when to read it. Add scripts only when deterministic execution materially improves repeated work, then test those scripts directly.
4. Add an example and limitations
Provide a realistic request that demonstrates the intended trigger. Explain what a useful output looks like without prescribing exact prose. Name important limitations: a screenshot review cannot prove interaction behavior, and a package validator cannot prove instruction quality.
Include a license or clear distribution permission before offering a public download. Keep source URLs and credits with assets that travel in the package.
5. Evaluate before publishing
Run the skill on a normal request, a request with missing input, and a nearby task where the skill should stay out of the way. Review the actual output rather than checking for copied headings. Fix only the decisions that produced a demonstrated problem.
Record the environment and date. Use Package structure checked for a file-layout review and Workflow tested only when you ran meaningful tasks and retained evidence.
Publish an inspectable package
Create a ZIP with one top-level folder and let visitors preview SKILL.md, requirements, files, license, version notes, and the review record before downloading. Link the package to a tutorial that shows it in use.
Primary source
OpenAI build-skills documentation. Source checked September 10, 2026.
Progress stays in this browser. No account needed.
Updates and upgrade guidance
- Learning context added
Added prerequisites, a suggested practice estimate, expected output, and connected definitions. The article procedure was not independently re-evaluated in this change.
What to do: Use the opening checklist to prepare. No software update is required for this editorial change.
This log starts with the first recorded review; it is not a reconstruction of earlier revisions.