2 minute read

Summary

Writing the same long procedure into every Codex prompt is hard to maintain. If a workflow repeats, such as blog writing, release notes, code review, or migration checks, it is a good skill candidate.

A skill is not a place to dump unlimited background knowledge. It is a reusable unit for procedure, references, and optional scripts that should be loaded only when the task needs it.

Document Information

  • Written on: 2026-04-23
  • Verification date: 2026-04-23
  • Document type: analysis
  • Test environment: No execution test. This is a skill-design guideline based on official OpenAI Codex documentation.
  • Tested version: OpenAI Codex documentation checked on 2026-04-23

Problem Definition

Putting repeated procedures into AGENTS.md makes the instruction file grow. Pasting them into every request creates omissions and variation. A reusable workflow layer sits between those two extremes.

This post explains when a task should become a skill and what a skill should contain.

Verified Facts

According to official documentation, Codex skills extend Codex with task-specific capabilities and can package instructions, resources, and optional scripts. Source: OpenAI, Agent Skills

According to official documentation, a skill is a directory with a SKILL.md file and optional scripts, references, assets, and agents folders. SKILL.md requires name and description. Source: OpenAI, Agent Skills

According to official documentation, skills use progressive disclosure: Codex starts from metadata and loads the full SKILL.md only when it decides to use the skill. Source: OpenAI, Agent Skills

According to official documentation, skills can be activated explicitly or selected implicitly when the task matches the skill description. Source: OpenAI, Agent Skills

Directly Reproduced Results

No direct reproduction was performed. This post does not create a new skill and measure how often Codex selects it. It derives separation criteria from the documented skill structure.

Interpretation / Opinion

I treat a task as a skill candidate when:

  • The same procedure repeats.
  • The procedure is too long for AGENTS.md.
  • It needs references or templates.
  • Some steps can be scripted.
  • The input and output shape is stable.

Minimum skill shape:

---
name: blog-writing
description: Use when drafting or revising technical blog posts with a verifiable structure.
---

# Blog Writing

## When to use

- New technical posts
- Revisions that separate facts, reproduction, and opinion

## Workflow

1. Read repository guidance.
2. Check the post template.
3. Separate facts, direct reproduction, and interpretation.
4. Prefer official sources.
5. Record limits and exceptions.

Opinion: a good skill is less like a large knowledge document and more like a small operating unit. The description matters because it is the first clue Codex uses to decide when the skill applies.

Limits and Exceptions

Not every one-off task needs a skill. Too many skills create their own maintenance problem.

A skill also does not guarantee quality by itself. It should work together with tests, review, and CI.

References

댓글남기기

You may also enjoy