Build a Claude Skill from Scratch

A skill is a Markdown file with frontmatter that becomes a slash command in Claude. Instead of typing the same long instructions every session, you type /your-skill-name and Claude loads the full context automatically. This tutorial walks through writing a skill, testing it, and packaging it for others to use.

---

What a skill file looks like

---
description: Review this code for bugs, performance issues, and style problems.
---

You are a senior software engineer conducting a code review.

When the user shares code, analyse it in this order:
1. **Bugs** — anything that will cause incorrect behaviour or crashes
2. **Performance** — inefficiencies, unnecessary allocations, slow algorithms
3. **Style** — readability, naming, structure

Label each finding with [BUG], [PERF], or [STYLE].
After the findings, write one sentence summarising the overall quality.

Do not praise the code unless the user asks for positive feedback.
Do not suggest changes that are purely subjective preferences.

That is the whole format. The frontmatter block (between the --- markers) holds metadata. Everything after it is the prompt that loads when the skill is invoked.

---

The frontmatter fields

The description field is the only required one. It serves two purposes: it is shown in the skill picker UI so the user knows what the skill does, and it is used by Claude to decide whether to invoke the skill automatically when it seems relevant.

Optional fields vary by client. Claude Desktop commonly supports:

---
description: One-line summary shown in the skill picker
author: your-name
version: 1.0
tags: [code-review, engineering]
---

Keep description to one sentence. It is not the place for detailed instructions — that is what the body is for.

---

Write the body

The body is a system prompt. Everything from the system prompt guide applies here: be specific about role and audience, use constraints rather than encouragements, show output format with examples rather than describing it.

A few patterns that work well in skills:

Set the operating mode clearly:

You are in refactoring mode. The user will paste code. Your job is to
suggest specific, concrete improvements — not rewrites, not explanations
of what the code does. One suggestion per paragraph. Stop after five suggestions.

Define what "done" looks like:

A complete response ends with a single line: "Next step: [one action the user should take]."
Do not write a summary. The next step line is the summary.

Handle missing input gracefully:

If the user invokes this skill without pasting any code, ask:
"Paste the code you want reviewed, and mention any specific concerns."
Do not attempt to review imaginary code.

---

Install a skill in Claude Desktop

Place the .md file in your skills directory:

# macOS / Linux
~/.claude/commands/code-review.md

# Windows
%APPDATA%\Claude\commands\code-review.md

In Claude Desktop, the skill becomes available as /code-review. Tab completion lists all installed skills.

For Claude Code (the CLI), the path is the same. Project-specific skills go in the project's .claude/commands/ directory instead of the global one — they are available only when working in that project.

---

Test your skill

Open Claude and type /your-skill-name. Then probe it:

• Give it a typical input — does it behave as expected?
• Give it an edge case — what happens with no input, very short input, or irrelevant input?
• Push back on its first answer — does the persona hold, or does it revert to generic behaviour?
• Ask it something outside its scope — does it stay focused or drift?

The push-back test is the most important. A skill that collapses under mild pressure was under-specified. Go back to the body and add a constraint that covers the failure case.

---

Share a skill

A skill is a single Markdown file. To share it:

1. Give it a clear filename that describes what it does (code-review.md, not skill1.md)
2. Include a description in the frontmatter
3. Add a comment at the top of the body explaining what it expects, if it is not obvious

---
description: Analyse a SQL query for correctness, performance, and index usage.
---

<!-- Paste a SQL query and optionally mention the database engine (Postgres, MySQL, SQLite). -->

You are a database engineer reviewing SQL queries...

The comment does not affect Claude's behaviour — it is documentation for whoever installs the skill.

SysEmperor's AI Skills section has ready-to-use skill files you can download and drop directly into your skills directory — no editing required.

---

Keep skills focused

A skill that tries to do ten things does none of them well. One skill per task is the right granularity. If you find yourself writing a skill with multiple modes ("if the user says X do this, if they say Y do that"), split it into two skills.

Focused skills are also easier to share — someone browsing a skills library understands exactly what sql-query-reviewer.md does without reading it.