Control when a skill is invoked

Understand the approach

Explicit invocation names the workflow you want; implicit invocation lets Codex select a matching description. Use explicit selection while learning or diagnosing a skill so you know which procedure was intended. Then test normal phrasing to evaluate discovery. Client affordances differ: the documented CLI and IDE options include /skills and dollar-name mentions. Use the selector actually available in the app rather than assuming Claude's slash-command syntax is portable.

Codex supports an optional agents/openai.yaml file for skill metadata and policy. Setting policy.allow_implicit_invocation to false prevents automatic selection while leaving explicit invocation available. This is different from a permission boundary. A user-invoked release-draft skill still needs an explicit task to publish, send or change a live system; choosing it does not authorize every action its text mentions. Conversely, disabling implicit invocation does not make a procedure harmless once someone selects it.

Build a two-column activation test rather than relying on one successful call. Put requests that name readme-evidence-review in the first column and ordinary readiness questions in the second. Add a nearby but wrong task such as rewriting an advertisement. Record what was selected and what was produced. If you add the explicit-only policy for a sensitive workflow, rerun both columns. Do not copy Claude's disable-model-invocation or user-invocable frontmatter and claim they have the same meaning in Codex.

Use --explicit-only to prepare a second fresh project. It places the policy at the actual agents/openai.yaml path inside the copied skill and creates activation-results.csv with unrun observations. In the first project test a direct selection, a plain readiness question and unrelated styling; repeat those exact requests in the explicit-only project. Require the same two grounded findings whenever the skill is actually invoked. This fixes input and procedure while changing only discovery policy. If a native result selects correctly but invents a third defect, score selection as correct and the report as incorrect.

Practice and acceptance

An explicit-only policy changes discovery behavior; it cannot make an incorrect report correct or authorize side effects.

Try it step by step

1. Read the linked lab guide, inputs and expected outputs before running the exercise.
2. Start with a working, narrowly described skill and write a direct request, a paraphrase and an unrelated request.
3. Run the direct request through the actual client selector. Confirm the intended procedure was read rather than inferring invocation from fluent output.
4. For the practice explicit-only variant, create agents/openai.yaml inside that skill folder using the policy shown below. Keep existing metadata if the file already exists.
5. Repeat direct and indirect cases in a fresh or refreshed client context as needed. Record activation separately from the accuracy of the report.
6. Review the procedure's side effects independently of its trigger. A draft-only exercise should still produce no external message or project edit.

A useful starting example

Illustration · adapt before use.

# .agents/skills/readme-evidence-review/agents/openai.yaml
interface:
  display_name: "README Evidence Review"
  short_description: "Inspect documented run and test claims"
policy:
  allow_implicit_invocation: false

node labs/skill-workflow/prepare-scratch.cjs ../readme-skill-explicit --explicit-only
# In its Codex composer explicitly select:
# $readme-evidence-review Review README.md and report grounded defects.

Check your result

• You can demonstrate the difference between naming a skill and having it matched automatically.
• The policy is in agents/openai.yaml rather than an invented Codex frontmatter field.
• The activation test does not confuse successful selection with permission to perform an external action.
• Helper results, actual host activation and unexecuted application commands remain distinguishable.

Common mistakes

• Using a Claude invocation-control field in Codex without checking support.
• Assuming an explicitly selected skill may perform every side effect described in its examples.