TL;DR
- Claude Code skills are SKILL.md scripts inside the
.claude/skills/folder that Claude invokes on demand or automatically when a trigger condition is met. - A skill is at most a few hundred lines of Markdown: goal, steps, input and output examples.
- Building a skill makes sense when the same multi-step workflow repeats 3+ times per day or per week.
- A skill is not MCP: MCP gives Claude access to an external tool, a skill gives it a ready-made playbook for how to act.
- Time to build a basic skill: 30 to 60 minutes. Payback: first use.
What are Claude Code skills?
Claude Code skills are reusable instructions that steer Claude Code through a specific, repeatable task. A skill lives in a SKILL.md file inside your project's .claude/skills/ folder. When you type /skill-name in the Claude Code terminal, Claude loads that file and treats it as operating instructions for the duration of the task.
The mechanism is simple. The official documentation describes a skill as a set of natural language instructions with embedded bash commands, reference files, and decision rules. There is no code here in the traditional sense. SKILL.md is a Markdown file that Claude reads and interprets before each step.
The difference from a regular prompt: a skill is persistent, version-controlled in your repository, available to the whole team, and can have its own internal decision logic (if X then do Y, if Z then BLOCKED). A one-off prompt lives in the conversation context. A skill lives in the project.
Typical use cases:
- Daily processes: standup reports, status updates, data syncs
- Developer workflows: deploy, rollback, opening a PR with a checklist, lint and format pre-commit
- Content workflows: writing posts to defined rules, content audits, publishing to a CMS
- Onboarding: a skill that walks a new developer through environment setup step by step
How do you write your own Claude Code skill?
You write your own Claude Code skill in three steps: goal, steps, guardrails.
Step 1: define the goal in one sentence
The first sentence of SKILL.md answers the question "what does this skill do and when is it invoked?" Example: "Use this skill when deploying to production. Runs pre-deploy checks, creates a release branch and opens a PR with a checklist." Claude uses this sentence to decide whether the skill fits the situation.
Step 2: write the steps as a list
Each step is an imperative sentence with an optional condition. Style: "Run npm run lint. If exit code > 0: STOP and report failures. Do not proceed." Do not write "try running lint and see if it's ok". Write precisely what Claude is to do, with which tool, and what to do if something goes wrong.
Step 3: add guardrails and examples
The "What NOT to do" section is a list of things the skill should never do: do not delete production files, do not push directly to main, do not skip tests under ASAP flags. The "Example output" section shows what a correct result should look like. Claude compares its output to the example before declaring the task done.
File structure:
# Skill name (single-line goal)
**Trigger:** /skill-name [optional arguments]
**Steps:**
1. First step
2. Second step (if X: BLOCKED)
...
**What NOT to do:**
- List of prohibitions
**Example output:**
[Example of a correct result]
The file goes into .claude/skills/skill-name.md. Claude Code discovers it automatically.
Example: a skill for daily progress reporting
On one of our projects (a task management system for clients) we had a recurring workflow: check what was done earlier, fetch new tasks from the API, execute them sequentially, log the results to a document. I did it by hand each time: a dozen steps, copy-paste, status checks. After the third time I built a skill.
A simplified version of that skill's SKILL.md:
# Daily task runner (automated daily run for project task queue)
**Trigger:** /daily-run
**Context:**
- API base URL: read from .env
- My user ID: defined in .env CLAUDE_USER_ID
- Task list endpoint: /api/tasks?assignee=$CLAUDE_USER_ID&status=todo
**Steps:**
1. Get today's date: `date -Iseconds`
2. Fetch todo tasks: `curl -H "X-API-Key: $API_KEY" "$BASE_URL/api/tasks?assignee=$MY_ID&status=todo&limit=50"`
3. If 0 tasks: log "No tasks today" to daily-log document. DONE.
4. Sort tasks by priority (urgent > high > normal).
5. For each task:
a. Read task description fully.
b. If description has no GOAL or STEPS section: BLOCKED, add a comment "Unclear description" and skip.
c. Execute the steps from the description.
d. Post a completion comment: POST /api/tasks/{id}/updates with result.
e. Mark done: PUT /api/tasks/{id} body: {"status": "done"}.
f. Verify status change with GET /api/tasks/{id}.
g. Sleep 0.5 between writes to avoid race conditions.
6. Update the daily log document with done/blocked summary.
**What NOT to do:**
- Never execute multiple writes in parallel.
- Never delete tasks belonging to other users.
- Never mark a task done without posting a completion comment first.
**BLOCKED condition:** If a step requires access to a tool not available in this session:
post BLOCKED comment with exact tool name, do not attempt a workaround.
Building this skill took 45 minutes. It has been running daily for several months. More important than the time it saved: errors in task execution are now visible in the logs as comments inside the system, not hidden in a manual process where nobody knew what went wrong.
A key detail of that skill: the "What NOT to do" section forbids parallel writes. That is not obvious to Claude without the instruction. In the first version of the skill (without this rule) Claude tried to run two tasks at once and ran into a race condition with the API. One line in SKILL.md solved the problem permanently.
Are Claude Code skills different from MCP?
Claude Code skills and MCP servers are two different layers of extending Claude Code's capabilities, and they often get confused.
MCP (Model Context Protocol) gives Claude access to an external tool or system. An MCP server is a service Claude can call: a GitHub server, a database, a scraping tool, an external API. MCP extends what Claude can do. Configuration is technical: JSON, server, transport layer.
Skills give Claude a ready playbook for how to behave in a specific situation. A skill does not provide new tools, it uses the tools already available (bash, files, MCP servers that are configured). A skill is simple to create: a Markdown file.
When to pick which:
- You want Claude to access a new external system: MCP
- You want Claude to execute a known multi-step workflow under fixed rules: skill
- You want both layers combined: a skill whose steps call a configured MCP server
In practice: we build MCP once per project, we build skills continuously for every recurring process. The daily report skill uses an MCP for the database and an MCP for GitHub. The skill itself is just instructions.
A useful analogy: MCP is like installing a new program on a computer (gives new capabilities). A skill is like writing a job procedure for an employee using the installed programs (tells them how to use it in a specific process). You need both, but they do different things. Swapping one for the other does not work.
When is it worth building your own Claude Code skills?
Claude Code skills are worth building when the same multi-step workflow recurs regularly and errors in it are costly.
Three signals it is time to build a skill:
-
Repetition: you do the same thing more than 3 times per week. Every manual iteration costs time and risks an error. A skill eliminates both.
-
Complexity: the workflow has more than 5 steps, or branching conditions ("if API returns 404, do X, if 200, do Y"). Without structured instructions, Claude loses context on long tasks.
-
Quality requirements: the output must meet defined standards (report format, pre-deploy checklist, approved code patterns). A skill encodes these standards once and enforces them every time.
When a skill is not needed: a one-off task, a simple single-step workflow ("summarize this file"), a task that changes so much each run that generic instructions do not help.
One more signal: if every time you run some multi-step process you have to return to old notes to remind yourself of the step order, that is precisely the signal it is time to build a skill. Instead of "notes for myself how to do X", create a SKILL.md and let Claude enforce it. Your notes become a set of instructions you can use without rereading them every time.
Rolling out Claude Code skills across a project and a team
You roll out a skill in a project by placing SKILL.md in .claude/skills/. The whole team has access when the .claude/ folder is committed to the repository (typically yes; only .claude/settings.local.json which stores local environment data is globally ignored).
An important security note: skills can run arbitrary bash commands, create files, call APIs, delete data. Before you share a skill with the team, review it for irreversible operations. A good skill has a "checkpoint" at every irreversible operation: "Confirm: delete all entries in staging database? [yes/no]". Do not assume Claude will be cautious on its own initiative, if the instructions do not define stopping points.
A few practical rules:
- One file, one task. Do not create a skill that does 5 different things depending on arguments. Better to have 5 separate skills with readable names.
- Version with the code. A skill changes together with the project. If an API endpoint changed, the skill that uses it should be updated in the same commit.
- Test on a small scope. Before production use, run the skill on a test project or with a dry-run flag if it supports one. Claude has no "this sounds risky, let me ask" instinct under clear instructions.
- Document what is OUT of scope. The "What NOT to do" section is the most important part. It describes the skill's boundaries as precisely as the steps themselves.
If you want to see how an agentic workflow with Claude Code skills looks in production, contact us through the services page. AI agent implementations and n8n plus AI automations start at around $450 net.
A skill that works: one task, clear guardrails, a result verifiable at every step.