Claude Skills: What They Are, When to Use Them, and How to Build Your Own

Before the formal definition, here is the concrete thing: a skill is a file.

Specifically, it is a Markdown file (conventionally named SKILL.md) inside a directory like .claude/skills/<skill-name>/. The file has a small YAML frontmatter block at the top — a name and a description — followed by plain prose that tells Claude exactly what to do when this capability is needed.

When a Claude agent (running via Claude Code, an MCP server, or an orchestrated pipeline) encounters a task that matches the skill’s description, it loads that file and follows its guidance. The skill does not execute code. It does not call an API. It is structured natural-language guidance — a very well-written system prompt, packaged so it can be loaded on demand instead of copy-pasted everywhere.

Click any line below to see what each part of a skill file does and why it is there.

The honest answer is: not every task warrants a skill. Skills have overhead — you need to create a file, maintain it, and wire it up. That overhead pays off only under specific conditions.

Reach for a skill when:

• The same capability will be invoked more than once — by the same agent, by multiple agents, or across different workflows.
• Output consistency matters: format, tone, level of detail, domain conventions.
• The guidance can be expressed in a focused, bounded document (roughly under 500 words of body text).
• Multiple people or systems will eventually share or extend it.

Skip the skill when:

• The task is genuinely one-off. A quick exploration or a throwaway script does not need a persisted skill.
• The guidance is so tightly coupled to one specific piece of context that it cannot be reused without heavy modification.
• The domain is so unstable that the skill would need rewriting weekly — in that case, use an inline system prompt until the requirements stabilise.

The benefit of a single skill is marginal. The benefit of a library of skills, each owned by one team and shared across many agents, is significant.

Consider a company running 12 Claude-powered agents: a customer-support bot, a code reviewer, a meeting summariser, a legal-document tagger, and so on. Without skills, each agent carries its own copy of the “write in our brand voice” instructions, the “output Markdown only” rule, and the “never include personally identifiable information” constraint. When legal updates the PII rule, someone has to find and patch 12 places.

With skills, those shared constraints live in brand-voice/SKILL.md, output-format/SKILL.md, and pii-redaction/SKILL.md. Each agent config file says use_skill: pii-redaction. Update the skill once; all agents pick up the change on their next run.

This is the same reason software engineers extracted shared libraries instead of copying code between files in the 1970s. The principle — don’t repeat yourself — applies equally to AI behavior specifications.

A skill is a text file. Here is the exact steps-to-ship procedure:

Step 1 — Identify one focused capability. Do not start with “everything my agent needs.” Pick one task: “classify customer emails by intent,” “generate Git commit messages from diffs,” “summarise Slack threads.” One skill, one job.

Step 2 — Create the directory and file.

mkdir -p .claude/skills/my-skill-name
touch .claude/skills/my-skill-name/SKILL.md

Step 3 — Write the frontmatter. The name field is the identifier other agents will reference. The description is what the orchestrating agent reads to decide when to load the skill — write it as a one-to-three sentence answer to “what does this skill do?”

---
name: git-commit-writer
description: >
  Writes a conventional Git commit message
  from a provided diff or change description.
  Follows the Conventional Commits spec.
---

Step 4 — Write the body. The body should include at minimum: a role line, an input format section, and an output format section. Optional but high-value: an example with a realistic input/output pair.

---
name: git-commit-writer
description: >
  Writes a conventional Git commit message
  from a provided diff or change description.
---

# Git Commit Writer

You are a senior engineer writing commit messages
for a collaborative open-source project.

## Input format

A plain-text description of the change, or a raw
`git diff` output.

## Output format

A single commit message following Conventional Commits:

  <type>(<scope>): <subject>

  [optional body — wrap at 72 chars]
  [optional footer — BREAKING CHANGE: …]

Types: feat | fix | docs | style | refactor | test | chore

## Rules

- Subject line ≤ 72 characters.
- Use imperative mood ("add", not "added").
- No period at the end of the subject line.
- If the change is a breaking change, include
  `BREAKING CHANGE:` in the footer.

## Example

**Input:** Added a --dry-run flag to the deploy script
that prints planned changes without executing them.

**Output:**
feat(deploy): add --dry-run flag for change preview

Step 5 — Reference the skill from your agent config. How exactly this works depends on your orchestration setup (Claude Code subagent YAML frontmatter, MCP config, or a custom pipeline). The key is pointing to the skill by its name value.

---
name: commit-message-agent
description: Generates commit messages on demand.
---
# Agent instructions

Use the `git-commit-writer` skill for all commit
message generation tasks. Do not deviate from the
skill's output format.

Step 6 — Test, then refine. Run the agent against 3–5 representative inputs. Where output drifts from expectation, update the skill’s rules or add a new example. Commit the skill file alongside your agent config so they version together.