How to Write a Codex SKILL.md and Require Explicit Invocation

Do you rewrite the same long instructions whenever you ask Codex to perform a recurring task? Workflows such as article production, code review, and document checks can be packaged as skills and reused. However, you may not want a specialized or expensive workflow to activate automatically for a loosely related request.

The practical answer is to put the workflow in SKILL.md and put the explicit-invocation policy in agents/openai.yaml. Writing “use only when explicitly invoked” in the description is useful guidance, but the setting that disables implicit activation is allow_implicit_invocation: false.

Based on OpenAI's official guidance and the Agent Skills specification available on July 22, 2026, this guide explains the minimum repository structure, effective metadata, explicit invocation, and a simple way to test the result.

Create a Dedicated Skill Folder and SKILL.md

A skill intended for an entire repository belongs in its own folder under .agents/skills at the project root. For example, the markdown-blog-writer skill used for Imidef Blog has this basic structure:

.agents/
└── skills/
    └── markdown-blog-writer/
        ├── SKILL.md
        └── agents/
            └── openai.yaml

OpenAI's guidance says Codex scans .agents/skills locations from the current working directory up to the repository root. A user-level location is also available for skills that should work across repositories. A repository location is usually the better choice when a workflow depends on one project's folders, content format, or validation commands.

The skill name should match its parent directory. The Agent Skills specification limits names to lowercase letters, numbers, and hyphens, with no leading, trailing, or consecutive hyphens.

Separate SKILL.md Metadata from Its Instructions

SKILL.md contains YAML front matter followed by a Markdown body. The required metadata fields are name and description.

---
name: markdown-blog-writer
description: Create paired Japanese and English Markdown articles for Imidef Blog. Use only when the user explicitly invokes $markdown-blog-writer for an article-generation task.
---

# Markdown Blog Writer

Research the requested topic using official sources.
Create Japanese and English articles with one shared OGP image.
Validate the Markdown and project after saving the files.

name is the identifier used when invoking the skill. The description should say what the skill produces, when it applies, and when it should not be used. “Helps with blogging” is too broad. Naming the deliverables, project, and invocation boundary makes an incorrect selection less likely.

Use the body for imperative instructions: required inputs, execution order, output locations, stop conditions, prohibited actions, and validation. Detailed reference material can be moved to references, while deterministic utilities can be placed in scripts when the workflow needs them.

The Description Helps Codex Discover the Skill

Codex does not load every skill's complete instructions at the beginning of a session. It initially receives a small amount of metadata, including the name, description, and file location. It reads the full SKILL.md only after selecting the skill. This is called progressive disclosure.

When implicit invocation is enabled, the description has a major effect on selection. A description that is too broad can activate for unrelated requests, while one that is too narrow may hide the skill when it would help. Put the concrete deliverable and trigger conditions near the beginning and remove vague wording.

There is still an important distinction: saying “explicit invocation only” in the description is guidance, not the policy control that disables implicit activation. The formal invocation setting belongs in openai.yaml.

Add openai.yaml to Require Explicit Invocation

Create agents/openai.yaml inside the skill folder and set policy.allow_implicit_invocation to false. Its default value is true when the policy is not specified.

interface:
  display_name: "Markdown Blog Writer"
  short_description: "Create paired Imidef Blog articles and one OGP image"
  default_prompt: "Use $markdown-blog-writer to create an article for the specified topic."

policy:
  allow_implicit_invocation: false

With this policy, Codex will not implicitly activate the skill simply because a request resembles its description. A user can still activate it explicitly with $markdown-blog-writer.

The optional interface section supplies a display name, concise UI description, and default prompt for surfaces such as the desktop app. The policy section is the part that enforces explicit invocation. Keeping a clear boundary in the SKILL.md description remains useful because it explains the skill in selectors and guides behavior after activation.

Invoke the Skill Explicitly

In Codex CLI and the IDE, type $ followed by the skill name. You can also use /skills when you want to browse and select an available skill.

$markdown-blog-writer How to write SKILL.md and configure explicit invocation

In the desktop app, find and select the skill from Skills, then add the input it needs. A skill name alone rarely defines the entire task, so include the topic, target artifact, or other required parameters in the same request.

Explicit invocation is a useful default for workflows that create several files, consume substantial resources, conduct external research, generate images, or apply only to a narrow situation. Implicit invocation can be convenient for lightweight routines, but its convenience should be weighed against the consequences of an unintended run.

Test Both Explicit and Implicit Paths

After saving the files, confirm that the skill appears in the available skills list. Codex detects skill changes automatically, but OpenAI recommends restarting Codex if a new or updated skill does not appear.

Start a new chat and explicitly invoke the skill to verify that Codex loads and follows the SKILL.md workflow. Then send a similar request without the skill name. With allow_implicit_invocation: false, the second request should not activate the skill automatically.

If the behavior is unexpected, check these points in order:

• The folder name matches the front matter name
• The YAML front matter has valid opening and closing --- delimiters
• The description is non-empty and states a specific job and boundary
• agents/openai.yaml is in the correct folder and uses valid indentation
• allow_implicit_invocation is the Boolean false, not a quoted string
• The behavior remains the same in a new chat after restarting Codex

If explicit invocation works while an ordinary request does not activate the skill, the policy is working as intended. If implicit activation continues, also check whether another discovered location contains a skill with the same name.

Summary

A Codex skill begins with .agents/skills/<skill-name>/SKILL.md, where you define the required metadata and reusable workflow. The description is essential for discovery and selection, but disabling implicit invocation requires allow_implicit_invocation: false in agents/openai.yaml.

Start with one small workflow, test it with $skill-name, and then repeat the request without mentioning the skill. Once it runs only when intended, you can expand the automation without losing control over when it starts.

The most dependable skills define not only what to do, but also when to stay inactive.