Skills, Not Prompts: The Definitive Playbook for Codex + Claude Code
A practical blueprint to design, package, trigger, test, and govern reusable Skills for Codex and Claude Code.
If you’re still prompting your coding agent like it’s a chatbox, you’re paying the same tax every week: re-explaining standards, re-teaching workflows, re-losing hard-won context.
Skills are how you turn agent behavior into infrastructure.
Not vibes. Not remember what I said. Reusable, reviewable packages your agent can load on demand.
What you’ll get in this article:
A precise mental model of Skills (Codex + Claude).
The minimal package structure that actually scales.
How to make Skills trigger reliably (and avoid collisions).
How to test and govern Skills like software.
A production checklist you can adopt immediately.
1) What a Skill is (and why it scales)
Codex: on-disk instructions, loaded only when needed
In Codex, a Skill is a directory containing
with YAML front matter (name, description) plus an optional Markdown body.
The key architectural point:
The Skill body stays on disk and isn’t injected into runtime context unless explicitly invoked.
That design gives you scale. You can install many Skills without flooding context because only the metadata is always present, and the full content loads when the Skill is actually used.
Codex explicitly encourages bundling scripts, templates/schemas, reference data, and documentation alongside
.
Claude: progressive disclosure, filesystem + VM
Anthropic’s Agent Skills follow the same core principle: filesystem-based Skills with progressive disclosure, metadata always loaded; instructions loaded when triggered; extra resources loaded only if needed.
Claude’s docs are explicit that Skills leverage a VM environment with filesystem access, and that Skills are loaded in staged levels (metadata → instructions → resources/code).
Bottom line: Skills are not long prompts. They are modular packages designed for on-demand loading and reuse.
2) The Skill package: the only structure that scales
The non-negotiable file:
Codex requirements:
name: non-empty, single line, max 100 characters
description: non-empty, single line, max 500 characters
extra YAML keys are ignored
Claude requirements (key constraints):
name: max 64 characters; lowercase letters/numbers/hyphens; cannot include reserved words like Anthropic or Claude
description: non-empty; should describe what it does and when to use it
Critical insight: your description is not marketing copy.
It’s routing. If the description is vague, the Skill won’t trigger at the right time.
A minimal, production-friendly folder layout
Codex’s recommended components map cleanly to a simple, scalable layout:
markdown
my-skill/
SKILL.md # required
scripts/ # optional: deterministic code
references/ # optional: docs, schemas, examples
assets/ # optional: templates, static filesKeep executable content clearly separated from instructional content. It makes audits and reviews dramatically easier.
3) Activation: why most Skills don’t trigger reliably
People treat triggering like magic.
It’s not.
The agent decides relevance based on metadata. And both Codex and Claude intentionally load full instructions only when a Skill is relevant/triggered.
So your first job is not write a great Skill body.
Your first job is:
Write a description that matches what users actually type.
Description rules that work in practice
Bad:
Improves productivity and workflow quality.
Good:
Draft a conventional commit message when the user asks for help writing a commit message.
Better:
Add multiple natural phrases users will actually write (synonyms + common prompts).
Include when-to-use language (Claude’s docs explicitly recommend this pattern).
Collision avoidance (the silent failure mode)
If you have 20+ Skills, collisions become your biggest reliability risk.
Prevent collisions by:
avoiding generic verbs without objects (help, manage, improve),
using differentiators (for iOS SwiftUI, for Next.js, for incident triage),
keeping Skills narrow (modular beats monolithic).
4) Policy vs procedure:
and Skills should coexist
If you want consistent output across repos, Skills alone are not enough.
Codex reads
before doing any work and builds an instruction chain (global → project → subdirectories).
Codex even documents precedence and merging behavior, and it enforces a maximum size cap for project instructions (32 KiB by default).
Use the split deliberately:
= policy (your default working agreements, repo-specific rules)
Skills = procedures (repeatable workflows like write release notes, generate a migration plan, run a debugging playbook)
This division is a scaling hack. It prevents every Skill from becoming a dumping ground for global standards.
5) Build and test Skills like software (because they are)
Step 1: write the one-page Skill brief
Before writing
, answer:
What outcome should the reader/user get?
What inputs does the Skill require?
What’s explicitly out of scope?
What are the top failure modes?
If you can’t write this brief crisply, your Skill is too broad.
Step 2: decide instructions vs scripts
Codex explicitly calls out scripts for deterministic processing, validation, or external tool calls.
Use scripts when:
the step must be deterministic (validation, formatting, conversions),
you need stable outputs across runs,
you’re interacting with tools/APIs.
Use instructions when:
the task is judgment-heavy (review, planning, tradeoffs),
multiple correct answers exist.
Step 3: test triggering and outcomes
At minimum, create:
3 prompts that must trigger,
3 prompts that must not trigger,
2 edge cases (missing input, conflicting constraints).
Codex also provides guidance on using Evals to improve Skills reliability.
Precision note (non-ASCII descriptions): there is at least one reported case where a Codex Skill description under 500 characters still fails due to byte-length behavior in certain languages. Treat this as an implementation quirk that requires testing (not a guaranteed spec).
6) Claude: where Skills run, and what on-demand loading really means
Anthropic’s documentation is unusually explicit:
Skills run in a VM environment with filesystem access.
Claude loads Skills in three levels:
1. metadata (always),
2.instructions (when triggered),
3. bundled resources and executable scripts (as needed).
For API usage, Anthropic lists required beta headers and explains that you specify Skills via the container parameter, alongside code execution and files capabilities.
For Claude Code specifically, Anthropic states it supports custom filesystem-based Skills discovered automatically.
7) Security: treat Skills as production surface area
This is where teams get complacent.
Skills can include executable scripts. That means they can create real consequences.
Anthropic’s Skills documentation includes a dedicated security section and positions Skills as powerful modular capabilities so the governance model matters.
Your baseline controls should be boring and strict:
code review for every Skill change,
script audits (especially anything that can write files or call external tools),
allowlisting of tool usage where possible,
a kill switch (disable/remove Skills quickly).
8) The production readiness checklist
Use this as your ship gate.
Trigger quality
Description uses real user phrases, not abstractions.
Clear when to use language.
No collisions with other Skills.
Correctness
Steps are ordered, unambiguous, and testable.
Failure paths are defined (if X fails, do Y).
Expected output format is explicit.
Maintainability
Scope is narrow and documented.
References and templates live outside the main body when large.
An owner is accountable for updates.
Safety
Scripts are reviewed and minimal.
No secrets in Skill files.
External calls are intentional and auditable.
Close: your next step
Skills aren’t a gimmick. They’re a way to stop re-explaining your engineering standards to a machine that doesn’t owe you memory.
Pick one workflow you repeat every week. Turn it into a Skill.