Claude Agent Skills: How Claude Code Skills Work (with Examples)

What is a Claude Code skill?

A skill is a folder containing a SKILL.md file with instructions. Claude Code adds it to its toolkit: Claude uses the skill when your request matches its description, or you can run it directly by typing /skill-name.

Claude Code skills follow the open Agent Skills standard (agentskills.io), with extras such as control over who can invoke a skill, running a skill in a subagent, and injecting live command output. Custom commands have been merged into skills: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way.

How Claude loads skills (and why it saves context)

In a normal session, only the descriptions of your skills are loaded into context, so Claude knows what is available. The full body of a skill loads only when it is invoked. Long reference material therefore costs almost nothing until you need it.

• Default: you can invoke it, Claude can invoke it, description always in context
• disable-model-invocation: true — only you can run it; its description is not kept in context
• user-invocable: false — only Claude can use it; it is hidden from the / menu

Claude Code watches your skill folders, so edits take effect without a restart. A brand-new top-level skills directory needs /reload-skills.

Where skills live

• Personal: ~/.claude/skills/<skill-name>/SKILL.md — available in all your projects on this machine
• Project: .claude/skills/<skill-name>/SKILL.md — this repository; commit it so your team shares it
• Nested: <subfolder>/.claude/skills/<skill-name>/SKILL.md — loads when Claude works on files in that subfolder
• Plugin: <plugin>/skills/<skill-name>/SKILL.md — available as /plugin-name:skill-name wherever the plugin is enabled
• Enterprise: in the managed settings directory, for everyone in an organisation

If two skills share a name, enterprise wins over personal, and personal wins over project. Plugin skills are namespaced, so they do not clash.

What goes inside a skill folder

my-skill/
├── SKILL.md        (required: overview and steps)
├── reference.md    (detailed docs, loaded only when needed)
├── examples.md     (usage examples, loaded only when needed)
└── scripts/
    └── helper.py   (a script Claude can run)

Mention the extra files from SKILL.md so Claude knows when to open them. Anthropic's guidance is to keep SKILL.md under about 500 lines and move detailed reference material into separate files.

Create your first skill in three steps

1. Make a folder: mkdir -p ~/.claude/skills/summarize-changes
2. Create SKILL.md inside it (example below)
3. Test it: ask "What did I change?" and let Claude load it, or run /summarize-changes directly

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any
risks you notice such as missing error handling, hardcoded values, or tests
that need updating. If the diff is empty, say there are no uncommitted changes.

The line that starts with !` is dynamic context injection: Claude Code runs the command first and puts its output into the skill before Claude reads it.

The frontmatter fields that matter

Every field is optional, but description is strongly recommended. Field names must match exactly, and the opening --- must be the very first line of the file — otherwise no frontmatter is parsed, and unknown fields are ignored without an error.

• description — what the skill does and when to use it. Put the main use case first: the description plus when_to_use is cut off at 1,536 characters in the skill list
• when_to_use — extra trigger phrases or example requests
• name — the command name; defaults to the folder name
• argument-hint and arguments — autocomplete hint and named arguments
• disable-model-invocation / user-invocable — control who can run the skill
• allowed-tools — tools Claude can use without asking while the skill runs (it does not block other tools)
• context: fork and agent — run the skill in a forked subagent, for example the Explore agent
• paths — glob patterns so the skill only activates for matching files
• model and effort — override the model or effort for that turn
• hooks — hooks that are registered while the skill runs

Passing arguments to a skill

Anything you type after the skill name is available as $ARGUMENTS. You can also pick out individual values with $0, $1 and $2, or declare named arguments. Quote multi-word values.

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

Run /fix-issue 123 and Claude receives "Fix GitHub issue 123 following our coding standards." At the terminal prompt you can also stack skills in one message, such as /write-tests /fix-issue 123, and both load.

Skills vs CLAUDE.md vs subagents vs slash commands

• CLAUDE.md holds facts Claude should know every session. When a section has grown into a procedure, move it into a skill — a skill's body loads only when used
• Skills hold procedures and playbooks that load on demand
• Slash commands are now skills: the same files, triggered by typing /name
• Subagents are specialists that work in their own context window and report back; a skill can also run inside one with context: fork

For a full side-by-side, read our comparison of subagents, skills and slash commands.

9 skill examples to borrow ideas from

These are nine of the skills included in the claudeagents kit, each one a repeatable playbook of the kind that suits a skill. Use them as a model for your own.

• multi-agent-review — runs parallel reviews across security, performance, accessibility and type safety
• geo-seo-audit — checks site structure for search engines and AI answer engines such as Perplexity, ChatGPT search and Google's AI Overviews
• landing-page-conversion — audits layout friction, call-to-action placement and copy clarity
• nextjs-app-router-best-practices — enforces server vs client component scoping, streaming and caching
• type-safe-database-schema — scaffolds Prisma and Drizzle schemas with foreign keys, indexes and migrations
• component-design-system — builds CSS-variable design tokens for buttons, cards, modals and typography
• ci-cd-pipeline-setup — generates GitHub Actions workflows for tests and deployment
• performance-profiler — hunts re-render bottlenecks, bundle size and Core Web Vitals problems
• api-security-audit — audits JWT authentication, rate limiting, CORS and input sanitisation

Tips for skills that actually trigger

• Write the description as a trigger: say what the skill does and when to use it, with the phrases a person would actually type
• Keep each skill to one job; split large procedures into several skills
• Use /skills to list what is installed and /skill-doctor to see what each skill costs in context and how often it is used
• If a skill never fires, check the first line of the file is ---, then run claude --debug and search the log for [names] — invalid characters in a name can stop a skill loading
• Add disable-model-invocation: true to anything with side effects, like a deploy skill, so it only runs when you ask

Using the same skill outside Claude Code

Because skills follow an open standard, the same SKILL.md can work in other places too. Be careful with Claude Code-only frontmatter, though: when you upload a skill to claude.ai or use the Skills API, only name, description, license, compatibility, metadata and allowed-tools are accepted, and any other key — such as argument-hint — causes an error.

Skip the writing: ready-made skills

Writing and testing a good skill takes time. claudeagents ships 54 skill playbooks and 54 slash commands alongside 120+ subagents for coding, SEO and marketing, all reading from one CLAUDE.md, so you can start from tested material and edit it to suit your stack.