Claude Skills in Practice

The Complete Guide to Building Skills for Claude

A step-by-step handbook for developers and teams:
how to turn an SOP and expert knowledge into an automated workflow.

What a Skill actually is

A Skill is a folder holding instructions and a workflow. It lets Claude follow your process exactly, without you re-explaining the background in every conversation.

A standard Skill folder contains:

  • SKILL.md (required): the core instructions, with the YAML front matter that decides when it fires.
  • scripts/ (optional): executable scripts — Python, Bash.
  • references/ (optional): reference material Claude reads only when it needs to.

Why bother: teach it once and it holds, and everyone on the team produces the same shape of output.

The staircase

Step 1. Scope it

Define the use case, decide what triggers it and what done looks like, and work out whether it needs external tools (MCP).

Step 2. Build the structure

Create the folder, write the required SKILL.md, and follow kebab-case naming exactly.

Step 3. Write the instructions

Precise YAML triggers, and Markdown instructions written with progressive disclosure in mind.

Step 4. Test and ship

Start with one task by hand. Once the API calls and behaviour check out, zip it and release it to the team.

MCP and Skills together

The Connectivity
MCP
Connectivity to the outside
(What Claude can do)

The part that knows how to use the tools

If MCP gives Claude limbs — read Notion, create a Linear issue — Skills are what tell it how to use those limbs properly.

MCP without a Skill: a toolbox and no instructions. Every task starts with a complicated prompt written from scratch.

MCP with one: the workflow starts itself, with the good practice already baked into every interaction.

Three things people build

1. Documents and assets

Consistent output at a known quality. Brand guidelines, template structure and a pre-publication checklist can all live inside it. No external tools needed.

2. Workflow automation

Multi-step processes run in order, with verification built in. Usually coordinates several MCP servers.

3. Hardening an MCP server

Built to strengthen a server you already have: inject domain knowledge (Sentry triaging a bug automatically), supply context, and head off the API mistakes people keep making.

The YAML rules — where most Skills die

Naming, strictly

Claude is unforgiving about folder and file names. A small mistake means the Skill simply does not load.

  • The file must be named exactly SKILL.md — case-sensitive, and skill.md will not do.
  • The folder and the name: field must both be kebab-case.
  • No spaces, capitals or underscores (Notion_Setup is wrong).
  • No README.md in the Skill root.

The description, and what triggers it

The description is the only thing Claude uses to decide whether to invoke the Skill. Under 1024 characters.

  • It has to say both what it does and when to use it, with concrete trigger phrases.
  • For example: "Analyses design files. Use when the user uploads a .fig file or asks for design specifications."
  • Security rule: never put XML tags < > in the YAML — that is a prompt-injection vector.

Writing the instructions

Concrete and executable

Avoid vague direction. Not "validate the data properly" but "run scripts/validate.py; if it errors, check for a missing required field." Code is more definite than prose.

Progressive disclosure

To keep token cost down, keep SKILL.md lean — the core steps only. Move detailed API specs and large templates into references/, for Claude to read when it needs them.

Handle the failures up front

Anticipate what breaks and say what to do. A short troubleshooting section — "if the connection is refused, ask the user to reconnect under Settings > Extensions" — removes most of the occasions a human has to step in.

Worked example 1: a code review assistant

The standard shape for a single task

A standard SKILL.md that needs no external MCP tools. What matters is stating the preconditions and the guardrails.

  • The YAML block: defines exactly when it fires.
  • Role: gives Claude a point of view to answer from.
  • Workflow: numbered, so the order is not optional.
  • Rules: says what not to do, so it does not overreach.
---
name: strict-pr-reviewer
description: Fires when the user pastes code or asks for a code review .
---

# Role
You are a strict, senior backend architect.

# Workflow
When invoked, work through these in order:
1. **Security scan** — look for SQL injection and hard-coded credentials.
2. **Performance** — flag anything worse than O(N^2).
3. **Report** — present the suggested changes as a Markdown table.

# Rules
- Do **not** hand back a full rewrite.
- Give specific changes and the reasoning behind them.

Worked example 2: automation across MCP

---
name: linear-bug-reporter
description: Turns an error log in the conversation into a Linear issue.
---

# Objective
Analyse the error log and create a bug ticket via the `linear` MCP.

# Instructions
1. Extract from the log: the code, the timestamp, the likely cause.
2. Call the `linear_create_issue` tool.
3. Set the title to `[Bug] {error code}` .

# Error Handling (Fallbacks)
- If `linear` is missing or the connection fails, **do not apologise**.
- Fall back: produce the bug report as Markdown for the user to paste in.

Multiple steps, and what to do when one fails

This is Claude calling external APIs the way an RPA bot would, with a recovery path of its own.

  • Objective: one sentence saying what this is ultimately for.
  • Naming the tool: name the tool explicitly (linear_create_issue).
  • Fallback: this is the important one. Assume the MCP connection can drop. Tell Claude what to produce in plain text when the tool is unavailable, so the process does not simply stop.

Testing

"Get Claude doing one task perfectly first. Then extract that pattern and wrap it as a Skill."

Three dimensions to test

Dimension What you are checking How you know
Triggering It loads when it should, and stays quiet when the subject is unrelated. 90% of relevant requests invoke it without being asked to; unrelated ones do not.
Functional The workflow produces the right result and handles the edge cases. Zero unhandled API errors; every tool call completes; the output keeps its shape.
Performance The Skill beats the baseline of a person steering it by hand. Fewer turns, fewer tokens, and no corrections needed mid-run.

Five patterns worth knowing

  • Sequential workflow: steps 1 through N, strictly. For work with real dependencies — create the customer, set up payment, send the welcome mail.
  • Multi-MCP: orchestration across services. Export from Figma (one server), file it in Google Drive (a second), open a task in Linear (a third).
  • Iterative refinement: draft, validate with a script, correct, repeat — a closed loop that only exits when the output is good enough.
  • Context-aware: give Claude a decision tree. "Over 10MB, use the cloud storage server; if it is code, use GitHub."
  • Domain knowledge: before the API call, run the compliance or risk checks a senior practitioner would run without being asked.

Packaging and release

Packaging: once tested, zip the folder as .zip. Individuals upload it on Claude.ai; an administrator can deploy it across a whole workspace, where it updates itself.

Open source and API: host it on GitHub with a clear README.md covering installation. Application developers can invoke it programmatically through the API's container.skills parameter.

How to pitch it: lead with the outcome, not the mechanism. "This configures the project in seconds" lands; an architecture diagram does not.

Ready to build one?

"Knowledge drives the tools, and automation becomes the team default."

Use the built-in skill-creator to get moving.