If you have ever re-pasted the same style guide, the same deploy checklist, or the same "here's how I want this done" instructions into ChatGPT or Claude for the hundredth time, agent skills are the fix. An agent skill is an organized folder of instructions, scripts, and resources that an AI agent can discover and load on its own to do a specific task better. You write the workflow once; the agent reuses it whenever it's relevant. This guide covers what agent skills are, how they differ from prompts, how Claude Code and Codex use them, and how to build a small library that pays off in a week — whether you're a non-technical founder or a working developer.
What Agent Skills Are
Anthropic's definition is the one to keep: agent skills are "organized folders of instructions, scripts, and resources that agents can discover and load dynamically." At minimum, a skill is one directory containing one file: SKILL.md.
That file is plain Markdown with a short YAML header. The header requires exactly two fields — name and description — and the Markdown body holds the actual workflow:
---
name: pdf-form-filler
description: Fill out PDF forms when a user uploads a fillable PDF and asks to complete it. Do NOT use for scanned image PDFs.
---
1. Read the uploaded PDF and list every form field.
2. Map the user's answers to those fields.
3. Write the filled PDF and return it.
The description line does the heavy lifting. An agent decides whether to load a skill by matching the task in front of it against that description, so the description has to say plainly when the skill should fire — and when it shouldn't. A vague description is the single most common reason a skill never triggers, or triggers at the wrong moment.
Skills carry more than prose. A skill folder can bundle scripts/, references/, and assets/. Anthropic's standard example is a PDF skill that ships a Python script to read a form and pull out its fields. The agent runs the script through bash and gets back only the output — the script's source never enters the context window. That is the real gap between a skill and pasted instructions: a skill packages working tooling, not just text.
How Skills Differ From Prompts (and From Memory)
A prompt is a one-time instruction you type and retype. A skill is a reusable, version-controlled procedure the agent pulls in by itself when the moment calls for it. What makes that cheap is progressive disclosure — three levels of lazy loading:
- Level 1, startup. The agent loads only each skill's
nameanddescription. This is tiny, so a large library costs almost nothing. (Codex caps skill descriptions at roughly 2% of the context window.) - Level 2, relevant. If the agent judges a skill relevant, it reads the full
SKILL.mdbody. - Level 3, on demand. Linked reference files — a schema, a
reference.md— load only if the task actually reaches them.
One claim from Anthropic follows directly from this design: because detail loads only when used, "the amount of context that can be bundled into a skill is effectively unbounded." A skill you never trigger this session costs you next to nothing.
Here is the distinction readers conflate most: skills are not memory. The Hermes Agent docs put it cleanly — "memory stores small durable facts that should always be in context, while skills store longer procedures that should load only when relevant." Your company's legal name is a fact (memory, or a CLAUDE.md line). Your seven-step release process is a procedure (a skill). Keep the two apart.
How Claude Code Skills Work
In Claude Code, custom slash commands were folded into skills, so the two now run on the same machinery. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create a /deploy command.
Where you put the folder sets its scope:
- Personal skills:
~/.claude/skills/— available in every project, just for you. - Project skills:
.claude/skills/— committed to git and shared with the whole team.
You can run a Claude Code skill directly by typing /skill-name, or let Claude auto-trigger it by matching the task to the description. Claude Code follows the Agent Skills open standard and extends it with invocation control, subagent execution, and dynamic context injection. Anthropic keeps a public catalog of real examples at github.com/anthropics/skills if you want working SKILL.md files to study.
How Codex Skills Work
OpenAI's Codex added skills in late 2025; Simon Willison documented them showing up in both the Codex CLI and ChatGPT on December 12, 2025. In Codex you invoke a skill explicitly by typing $skill-name, or let Codex match one for you.
Codex scans several locations in priority order — roughly: the current directory's .agents/skills, then the repo root's .agents/skills, then your user-level $HOME/.agents/skills, then an admin path, then built-ins. One honest caveat: the path convention is still settling. Early Codex used ~/.codex/skills; current docs point to .agents/skills. Check the live Codex docs (developers.openai.com/codex/skills) for the exact path before you commit folders.
The headline for builders: Claude Code skills and Codex skills target the same open standard (agentskills.io). A skill is, in Willison's words, "just a folder with a Markdown file and some optional extra resources," so it's shareable, version-controllable, and reusable across tools and teammates instead of locked to one vendor. Be precise about the limit, though. The two implementations are close, but each tool adds its own extensions. Treat skills as largely portable on a shared standard, not as guaranteed byte-for-byte drop-ins.
An Example Skill Library
Here's a starter library that earns its keep fast. Each item is one folder with a SKILL.md.
brand-voice— captures your tone, banned words, and tagline rules once. Every landing page, email, or tweet draft comes out on-brand without re-pasting the style guide. This is the "define preferences once, reuse automatically" pitch made concrete.pdf-form-filler— Anthropic's own example: drop in a vendor contract or invoice and the agent fills every field through a bundled script. You see a finished document, never code.deploy— commit.claude/skills/deploy/SKILL.mdto the repo and any teammate (or the AI itself) runs the identical release checklist with/deploy. Tribal knowledge becomes a shared, versioned workflow.weekly-report— pulls your standard metrics, formats them your way, every Monday, the same each time.
Business Use Cases for Non-Technical Founders
You don't need to read code to get value here. Skills are where vibe coding — Merriam-Webster's 2025 term for building software by describing what you want and letting the AI produce it — grows up. Instead of re-describing the same workflow every session, you encode it once so the agent runs it reliably:
- On-brand content at scale. A
brand-voiceskill keeps every AI-written asset consistent, so you stop being the bottleneck who reviews tone. - Repeatable operations. Onboarding emails, investor updates, support macros — anything you do the same way each time becomes a skill the whole team (and the agent) runs the same way.
- Turning a contractor's know-how into an asset. When a developer or ops hire documents a process as a skill, that knowledge stays in the repo after they're gone.
Developer Use Cases
For builders, skills sit right inside the codebase:
- Codebase conventions on tap. A skill that encodes your testing pattern, commit-message format, or migration steps means the agent follows house style without re-prompting.
- Bundled tooling. Ship a
scripts/folder so the agent runs real code — a linter, a generator, a data check — and reads only the output, keeping the context window clean. - Self-improving agents. Nous Research's Hermes Agent (open-source, MIT, released 2026) writes its own skills through a
skill_managetool, treating them as "procedural memory." When it works out a non-trivial workflow or gets corrected by a user, it banks the approach as a reusable skill. (Call it "Hermes Agent" or "Nous Hermes" to avoid confusion with the luxury brand.) It's a preview of agents that learn and reuse workflows on their own.
Safety and Review Checklist
Skills make work repeatable, not infallible. Google's people-first guidance still rewards genuine experience and human judgment, and so should you. Before you trust a skill:
- Sharpen the
description. State when it triggers and when it must not. Front-load the trigger words so the agent picks it correctly. - Keep
SKILL.mdlean. Anthropic's rule of thumb is under 500 lines. Push detail into linked reference files so progressive disclosure still works — don't stuff everything into one giant file. - Separate skills from facts. Durable facts go in memory or
CLAUDE.md; multi-step procedures go in a skill that loads on demand. - Review bundled scripts. Any code a skill runs deserves the same scrutiny as code you wrote yourself.
- Don't assume cross-tool drop-in. Same standard, but verify a Claude Code skill behaves as expected in Codex, and vice versa, rather than assuming identical execution.
- Don't hardcode stale paths. Conventions are still shifting (Codex
~/.codex/skills→.agents/skills); point to current docs. - Keep a human in the loop. Skills remove repetition, not accountability.
FAQ
Do I need to know how to code to use agent skills?
No. A SKILL.md is plain Markdown — instructions in words. You can write a useful brand-voice or weekly-report skill without touching code. Scripts are optional and usually added by a developer.
Will a skill I write for Claude Code also work in Codex? Largely. Both target the same Agent Skills open standard, so the core is portable. But each tool adds extensions, so test it in the second tool rather than assuming a byte-for-byte match.
What's the difference between a skill and memory? Memory holds small durable facts that should always be in context, like your product name. A skill holds a longer procedure that loads only when it's relevant, like your deploy checklist. Facts stay on; skills load on demand.
How is this different from just writing a really good prompt? A prompt is one-time and manual. A skill is saved, version-controlled, auto-discovered by the agent, and able to bundle scripts and reference files — so the same workflow runs reliably every session without you retyping it.
Related on Boostor: building Claude Code skills, designing AI agents for business, and an intro to vibe coding for non-technical founders.