Claude Code Skills: Practical Examples for Builders

If you keep pasting the same instructions into a chat — a deploy checklist, a brand-voice guide, a "summarize what changed" prompt — you have already outgrown prompting. Claude Code skills are the fix. A skill is a folder with a SKILL.md file that packages a reusable workflow Claude loads on demand, so the AI does a repeatable job the same way every time, across sessions and across your team. This guide covers what skills are, how they differ from prompts, how Claude Code and Codex use them, and hands you a copy-paste library plus a safety checklist. It is written for two readers at once: the non-technical founder automating their own ops, and the builder shipping production code.

What Claude Code Skills Are

A skill is a directory with a SKILL.md file. The minimum viable version is YAML frontmatter with a description and some Markdown instructions:

---
description: Summarize what changed in the working tree as 2-3 plain-English bullets and flag anything risky.
---

Run `git diff HEAD`. Summarize the changes in 2-3 bullet points a non-technical
person could follow. Call out anything that could break the app or expose secrets.

Drop that in a folder, and Claude adds it to its toolkit. The official docs put it plainly: "Skills extend what Claude can do. Create a SKILL.md file with instructions, and Claude adds it to its toolkit." You write one "when you keep pasting the same instructions, checklist, or multi-step procedure into chat."

Skills bundle more than text: templates, example outputs, reference docs, and executable scripts in any language. Keep the SKILL.md itself under 500 lines and push the detail into separate files — that keeps the skill cheap to load.

Skills live at four scopes that decide who can use them:

Personal — ~/.claude/skills/<name>/SKILL.md, available across all your projects.
Project — .claude/skills/<name>/SKILL.md, committed to the repo so the whole team gets it.
Plugin — <plugin>/skills/<name>/, distributed via a plugin.
Enterprise — managed through settings.

Precedence runs enterprise > personal > project, and any level overrides a bundled skill of the same name.

How Claude Code Skills Differ From Prompts

A prompt is something you type once and lose. A skill is the same instructions, saved, named, and loaded automatically when relevant. Three differences matter in practice.

Progressive disclosure. Anthropic's engineering team frames a skill as "an onboarding guide for a new hire." Three layers load in sequence: (1) the skill's name and description are preloaded so Claude knows when to reach for it; (2) the full SKILL.md loads only when the request matches; (3) bundled reference files load only when actually needed. As the docs note, "long reference material costs almost nothing until you need it." A 5,000-word prompt pasted into chat costs tokens on every turn; a skill costs almost nothing until it fires.

Skills can run code and ship files. A prompt produces text. A skill can bundle a Python script — Anthropic's flagship example fills out PDF forms, a task plain text generation cannot do.

Two ways to invoke, with controls. Claude auto-loads a skill when your request matches its description, or you type /skill-name directly. Frontmatter gives you the steering wheel: disable-model-invocation: true means only a human can trigger it (use this for /deploy and /commit — you do not want Claude deciding to ship because the code looks ready), and user-invocable: false means only Claude triggers it (for background knowledge it should consult but you never call by hand).

How Claude Code Uses Skills

Claude Code ships with skills in the box — /code-review, /debug, /run, /verify, /loop, /batch, /claude-api — and the run/verify pair actually launches your app to confirm a change works against the running app, not just the test suite.

The frontmatter is where the reusable workflow comes together:

allowed-tools pre-approves specific tools (e.g., Bash(git add *)) so Claude stops asking permission mid-task.
context: fork runs the skill in an isolated subagent; agent: Explore picks the subagent type.
paths restricts a skill to matching files; model and effort override the model per skill.
Dynamic context injection: a line like !`git diff HEAD` runs the shell command and inlines its output before Claude reads the rest of the skill.

One detail worth knowing: custom commands and skills have merged. .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both produce /deploy. Old command files still work — skills just add the supporting-files directory, frontmatter controls, and automatic loading on top.

You can also check whether a skill is actually helping. The skill-creator plugin (install with /plugin install skill-creator@claude-plugins-official) runs A/B evals: it stores test cases, spawns a subagent per case, grades the output, and benchmarks with-skill versus without-skill on pass rate, tokens, and time. That stops you from mistaking "the skill triggered" for "the skill helped."

How Codex Uses Skills

Skills are no longer an Anthropic-only idea — the format is becoming a portable standard. It is published as an open standard at agentskills.io (released December 18, 2025), and the same SKILL.md works across Claude.ai, Claude Code, the Claude Agent SDK, and the Claude Developer Platform.

OpenAI Codex adopted the same SKILL.md directory format in December 2025. Its standout feature is record-and-replay: Codex watches you perform a workflow once, then drafts the skill for you — handy if you would rather demonstrate a process than write it up. Codex also ships its own $skill-creator and runs across its CLI (open-source, written in Rust), an IDE extension, and the cloud with subagents.

A third example rounds out the trend: Nous Research's Hermes Agent (open-source, MIT-licensed — the AI agent, not the fashion house) bills itself as "the agent that grows with you." It "learns your projects, auto-generates skills, and never forgets how it solved a problem," with persistent memory and isolated subagents. The takeaway: SKILL.md is converging into a cross-tool standard, so a workflow you encode today travels with you.

An Example Skill Library

Four skills worth stealing, each drawn from primary docs:

summarize-changes — injects the live git diff HEAD, then has Claude produce 2-3 plain-English bullets and flag risks. A non-technical founder asks "what did I change?" and gets a readable review without learning git. This is the docs' own first tutorial.
fill-pdf — bundles a Python script so Claude fills out PDF forms (contracts, applications, intake forms). Anthropic's flagship example, and the clearest proof that a skill can do something a chat prompt cannot.
deploy — set disable-model-invocation: true so the test-suite → build → push → verify sequence runs only when a human types /deploy. Your release runbook, encoded, with the AI unable to ship on its own initiative.
visualize-codebase — bundles a Python script that generates an interactive HTML tree of the repo. "Visualize this codebase" produces a browsable map — useful when a founder inherits unfamiliar code.

Business Use Cases for Non-Technical Founders

You do not need to write code to get value here. "Vibe coding" — now a Merriam-Webster-recognized term for building apps by telling an AI what you want — describes exactly this audience. Skills turn your repeated ad-hoc prompts into one reliable /command, encoding "how we do it here" so the AI stays consistent across sessions and teammates.

Founder skills worth building:

Brand voice (user-invocable: false) — your tone, banned phrases, and positioning, loaded automatically whenever Claude writes customer-facing copy.
Weekly investor update — a template plus the metrics to pull, so the draft is consistent every week.
Customer-intake / contract PDF — the fill-pdf pattern applied to the forms your ops actually touch.
Release notes from diffs — summarize-changes, repointed at producing a changelog your customers can read.

The principle: when a section of your CLAUDE.md grows from a fact into a multi-step procedure, move it into a skill so it loads on demand instead of taxing every conversation.

Developer Use Cases

Code review with your house rules — extend /code-review with the patterns your team actually enforces.
One-command release — the /deploy runbook above, with allowed-tools pre-approving the safe git steps.
Isolated investigations — context: fork plus agent: Explore to research a bug in a subagent without polluting your main context.
Path-scoped conventions — paths so a migrations skill only activates inside your migrations directory.
Eval-driven iteration — skill-creator to confirm a skill actually moves the pass rate before you commit it to the repo.

Safety and Review Checklist

Skills run with real tools, so review them like code:

Audit project skills before trusting a workspace. A checked-in skill can grant itself broad allowed-tools. Review it before you accept the workspace-trust dialog.
Gate side effects. Anything that deploys, sends Slack, or touches money gets disable-model-invocation: true.
Write the description for triggering. A weak description means the skill never fires. Use the words people actually say, and verify with "What skills are available?" or /doctor.
Keep SKILL.md lean. Once invoked, its content stays in context all session and is not re-read — bloat is a recurring token cost. Push detail to supporting files.
Mind the skill budget. Descriptions are capped (1,536 characters each; the whole set budgets to roughly 1% of the context window). Too many verbose skills get truncated and the least-used dropped. Reclaim space with skillOverrides: "name-only".
Do not confuse "triggered" with "worked." Run baseline A/B evals with skill-creator.

FAQ

Do I need to know how to code to use Claude Code skills? No. A skill is a Markdown file with plain-English instructions. Founders use them to standardize copy, reports, and form-filling. Complexity only enters if you bundle scripts — and you can lean on the official open-source skills for those.

What is the difference between a skill and a custom command? They merged. .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy, and old command files still work. Skills add a supporting-files directory, frontmatter controls, and automatic loading.

Will Claude run my skills without asking? Only if you let it. Claude auto-loads a skill when your request matches its description. Set disable-model-invocation: true to require a human to type the command — essential for deploy, commit, or anything that sends or spends.

Do Claude Code skills work in other AI tools? Increasingly, yes. SKILL.md is an open standard (agentskills.io, December 2025). OpenAI Codex uses the same format with a record-and-replay mode, and Nous Research's Hermes Agent auto-generates skills in the same shape.

How is a skill different from just editing CLAUDE.md? CLAUDE.md is always-on context — every fact in it costs tokens on every turn. A skill loads only when its description matches, so it is the right home for a multi-step procedure you do not need in every conversation.