Create a small project skill

Understand the approach

Use a project skill when a workflow has already proved useful through ordinary prompting. For this exercise, a read-only README review is narrow enough to inspect completely. Create a folder under .agents/skills/readme-check in your disposable repository and put SKILL.md inside it. The required metadata is a name and description in YAML front matter, followed by plain instructions.

The description tells Codex when to select the skill; the body explains what to do after selection. Keep those roles distinct. The skill should identify setup claims, compare them with available files, and return a short list of findings. It should neither rewrite the README nor install dependencies merely to make a missing command pass. If evidence is incomplete, a useful finding describes the gap instead of guessing.

Codex detects skill changes automatically, although restarting the client can help when an update does not appear. In CLI or IDE, use /skills or a dollar-prefixed skill mention to select it. The desktop product also exposes a Skills area and selectors; use the invocation offered by that client. Saving a valid file is only a structural milestone. You still need a positive task, an out-of-scope task and a factual result check.

Judge the skill by findings, not its filename

A correct review identifies unsupported npm test, the raw case-sensitive implementation, and the absent deployment URL. It distinguishes a requirement from an observed capability: the brief requires trimmed, case-insensitive search; notes.cjs does not yet implement it. A table that simply repeats the README misses the planted defect.

The app’s skill selector is the primary path here; CLI and IDE can use the dollar mention. Valid metadata is not proof that the installed client discovered or used the skill. Record selection and output separately, then make a README correction through a new scoped edit request.

Keep the first version boring

No script is needed for this exercise. An instruction-only skill is easier to review and travels with the repository without extra runtime dependencies. When a workflow repeatedly needs deterministic parsing, add a small supporting script later and test that script separately. Preserve a clear boundary between the skill being available, being invoked, producing a file and passing a real user review.

Optional explicit-only selection

When a workflow must be selected deliberately, the documented Codex agents/openai.yaml policy can set allow_implicit_invocation: false. Create that optional file inside the skill directory only if you choose this behavior; explicit dollar invocation remains available. Keep it separate from Claude’s differently named front matter.

This metadata controls selection, not authorization for commits, messages or publication. The first skill remains instruction-only and read-only. Compare visibility and activation in the installed client rather than treating valid YAML as a successful invocation.

Try it step by step

1. Create only the project-local skill folder in the disposable repository; leave personal and global skill directories untouched.
2. Save the example as SKILL.md and adapt the description if your real workflow has a narrower trigger.
3. Invoke it for a README containing one deliberately missing setup instruction, then inspect every reported finding.
4. Try a request to redesign the UI and confirm this read-only README skill is not used as an implementation workflow.

A useful starting example

Illustration · adapt before use.

$readme-check Review README.md against notes.cjs and checks.cjs. Check the npm test claim against actual files. Return a Claim / Evidence / Finding / Suggested correction table. Do not edit files or claim a check ran unless it did.

---
name: readme-check
description: Review README setup claims against project files without edits. Use for README checks, not implementation or UI design.
---
Read README.md and relevant configuration files.
List unsupported setup claims and missing prerequisites with file evidence.
Do not edit files, install dependencies or contact services.
Return findings, evidence and unresolved questions.

policy:
  allow_implicit_invocation: false

Check your result

• The skill contains a valid name, description and readable instructions at the expected project-local path.
• A positive request finds the deliberately unsupported claim and cites actual project evidence.
• An unrelated UI request does not inherit the skill’s review-only workflow or gain additional execution permission.

Common mistakes

• Using an attractive name with a description so broad that almost every task matches.
• Treating discovery of the skill as proof that its instructions produce accurate results.