Nobody warns you that prompts do not scale. You write the perfect one, it works once, and it evaporates the moment you close the tab. Agent skills fix that. A skill is a reusable, version-controlled folder your agent loads on demand: write it once, and both Claude Code and Codex run it. Rather than list fifty one-line ideas, this post builds eight skills worth having first, each with real SKILL.md syntax and the invocation that fires it. A short library you actually ship beats a long one you never write.
The reason this is worth learning as a standard, not a trick, is that skills are cross-vendor. Anthropic introduced Agent Skills and OpenAI added skills to Codex on the same format. Same folder, many agents, so a skill you write today outlives whichever harness you happen to use this week.
What a skill is, and how it differs from a prompt
A skill is a directory with one required file, SKILL.md. That file holds YAML frontmatter, at minimum a name and a description, then plain-English instructions. It can ship sibling folders: scripts/ for real code, references/ for deep docs, and assets/ for templates. A minimal one:
---
name: invoice-chaser
description: Draft polite payment-reminder emails for overdue invoices, escalating tone by days late. Trigger on "chase overdue invoices".
---
Read the overdue-invoice CSV. For each row, draft an email that names the
invoice, the amount, and the days overdue, with tone set by how late it is.
A prompt is something you type. A skill is something your agent owns. Three differences matter:
- Skills persist and version. They live in git, get reviewed, and travel with your repo. Your prompt history does not.
- Skills run code, not just text. A skill can bundle a script that fills a PDF form or reshapes a spreadsheet, something a model cannot do reliably by thinking about it.
- Skills load by progressive disclosure. The agent first sees only each skill's name and description, and reads the full body only when a task matches. So a shelf of skills does not bloat your context; that restraint is the point.
This is also why the description is load-bearing. It is the only text the agent reads when deciding whether to fire a skill. Vague description, skill never triggers.
How Claude Code and Codex use skills
Claude Code discovers skills on the filesystem: drop a folder in your skills directory and it is live, no upload step. Codex offers two invocation modes, explicit (/skills or $skill-name) and implicit, where it auto-selects based on your task. Because both read the same folder layout, a well-written skill moves between them with little change.
One framing worth internalizing: prefer skills over MCP for procedural knowledge. Skills are filesystem-based, git-versioned, and server-free, which is far less overhead than standing up an MCP server. MCP still wins for live data and system connections. Skills win for reusable workflows. Pick the right tool instead of cargo-culting either.
Eight skills to build first
Each is portable, and each shows the SKILL.md plus the line that invokes it. Start with the two or three closest to your actual week.
1. Conventional-commit writer.
---
name: commit-msg
description: Write a Conventional Commits message from the staged diff. Trigger on "write a commit message".
---
Read the staged diff. Output one line: type(scope): summary, then a short body
explaining why, not what. Types: feat, fix, chore, docs, refactor, test.
Invoke: $commit-msg after staging, or "write a commit message for these changes."
2. PR description from a diff. Turns a branch diff into a titled summary, a risk list, and a test-plan checklist. Invoke on "open a PR for this branch." The value is a consistent template your reviewers can trust.
3. Test scaffold from a signature. Given a function, it writes the happy path, one edge case, and one failure case, and stops rather than inventing behavior it cannot see. Invoke: "scaffold tests for this function."
4. Brand-voice enforcer.
---
name: brand-voice
description: Rewrite a draft to match our tone rules. Trigger on "make this on-brand".
---
Apply these rules: short sentences, concrete nouns, no hype words. Keep claims
that have a number or a source; cut claims that do not. Return the edit only.
Write the rules once and every draft complies without re-explaining yourself.
5. Changelog from commits. Reads commit history since the last tag and drafts release notes grouped Added, Fixed, Changed. Invoke: "draft the changelog since v1.2.0."
6. Screenshot to bug report. Takes an image plus a one-line complaint and produces reproduction steps, expected versus actual, and a first-error guess. Invoke by attaching the screenshot and saying "file this as a bug."
7. Customer-support macro responder. Classifies an incoming message, drafts a reply in your brand voice, and flags anything needing a human. All Markdown, no code required. Invoke: "triage and draft a reply to this ticket."
8. The meta-skill: skill-creator. A skill that interviews you about a workflow and scaffolds the folder for the next skill. This is how the library grows without you hand-writing YAML each time.
For non-technical founders, start with the brand-voice enforcer and the support responder. For developers, the commit writer, the PR description, and the test scaffold earn their keep the same week you write them.
Safety and review checklist
Skills execute code, so a bad one is a supply-chain risk. Treat it like a dependency:
- Audit anything from an untrusted source. Read the
SKILL.mdand every file inscripts/before you install. - Keep instructions lean. Overstuffing one
SKILL.mddefeats progressive disclosure; push deep material intoreferences/. - Write a sharp
description. It is the trigger; a weak one means the skill silently never fires. - Build with an eval. Start from a test of what "good" looks like, iterate with the agent, then trim.
- Design for portability. It is an open standard; hard-coding one vendor's assumptions throws away the main advantage.
Keep the library
Save the skills you build as a versioned set in Command Center, so your process is an asset you reuse instead of a prompt you retype.
Sources and further reading
- Anthropic: Equipping agents for the real world with Agent Skills
- OpenAI Codex: Agent Skills
- Anthropic: Claude Code documentation
FAQ
Will a shelf of skills overload my context window? No. Progressive disclosure means the agent sees only names and descriptions up front and loads a full skill on demand, so an idle skill costs almost nothing.
Do I need to be a programmer to write a skill?
No. The simplest skill is a SKILL.md with frontmatter and English instructions. Use a skill-creator or a record-and-replay flow to generate one from a demonstration.
Is a skill the same as an MCP server? No. Skills are filesystem-based procedural workflows in git. MCP connects to live systems and data. Use skills for repeatable how-to knowledge, MCP for real-time connections, and often both.
Where do I put a skill so my agent finds it?
In your agent's skills directory as a named folder containing SKILL.md. Claude Code and Codex both discover skills on the filesystem, which is why the same folder works across vendors.