Package a workflow as a skill when it recurs across tasks, contains several
steps, requires some agent judgment, and benefits from shared instructions,
references, scripts, templates, and a consistent output. Use ordinary code for
deterministic operations and AGENTS.md for durable repository rules.
OpenAI’s current
Codex Build skills documentation
defines an agent skill as a directory with a required SKILL.md. That file
supplies a name, a description that helps ChatGPT or Codex decide when to use
the skill, and the workflow instructions. The directory can also include
scripts, references, and assets. Follow the validation tools in the Codex
environment where the skill will run; other products may package or distribute
the same workflow differently.
Confirm that the workflow is repeated
Write evidence from at least two completed examples:
- common objective;
- steps that remained stable;
- choices that required judgment;
- sources or templates repeatedly opened;
- deterministic operations repeated; and
- expected output and verification.
Do not create a skill from one long conversation merely because it was expensive.
Separate the components
Use:
- instructions for sequence, decision rules, safety, and validation;
- references for stable domain or project knowledge;
- scripts for deterministic parsing, conversion, and checks;
- templates or assets for reusable output structure; and
- output requirements for what the agent must deliver and report.
A skill should point to primary sources when current facts matter. It should not embed secrets, private course content, credentials, or unsupported claims.
Keep judgment visible
State which decisions the agent may make and which require a person:
Agent may: select relevant references, run read-only checks, draft output.
Agent must ask: scope changes, publication, destructive cleanup, private-data use.
Agent must report: sources, commands, validation, unresolved uncertainty.
Do not convert an authorization boundary into an instruction to proceed.
Move deterministic work into scripts
If the same inputs should always produce the same transformation, implement and test a script. Let the skill decide when the script applies, prepare inputs, run it within permission boundaries, interpret clear failures, and verify output.
This division makes code testable and agent judgment reviewable.
Test without the original conversation
Start a fresh task with only the skill and safe test inputs. Include:
- a normal case;
- a boundary case;
- an invalid or insufficient-input case;
- a case that requires asking for permission or clarification; and
- a case outside the skill’s declared scope.
Check whether the correct instructions triggered, references were sufficient, scripts behaved deterministically, output matched the template, and uncertainty was reported honestly.
Record the Codex surface, version or review date, test inputs, observed output, failures, and revisions. Pending live validation should remain explicit rather than being marked complete.
Common mistakes
- Packaging a single deterministic command as an agent skill.
- Copying the original chat into instructions.
- Making every reference mandatory context.
- Hiding permission decisions in workflow prose.
- Testing only the happy path in the original thread.
- Treating a skill as permanent after product or project changes.
Do this now
Choose a workflow repeated at least twice. Map instructions, references, scripts, templates, output, judgment, and permission boundaries. Create a small skill only if the current Codex documentation supports the format, then test it in a fresh task.
Log what you learned
Record only:
- Result: What did the action produce?
- Evidence: What observation, test, or source supports that result?
- Next action or unresolved question: What should happen next?
Next, learn why scheduling or event automation should come only after the underlying workflow is stable.