Domain 3 · Task Statement 3.4

Creating Custom Skills

TL;DR

Build custom Skills using SKILL.md files with YAML frontmatter, store them correctly for discovery, write precise trigger conditions, and use the /skill-creator wizard to generate production-ready skill definitions.

What You Need to Know

Built-in Agent Skills handle generic file processing. Marketplace plugins cover common use cases across industries. But neither can encode your organisation's specific procedures — your 15-step NDA review checklist, your proprietary brand voice rules, your department's exact report format with the metrics your CFO wants in that particular order.

That is what custom Skills are for. They let you teach Claude your procedures, written in plain English, stored as Markdown files on your machine. No programming required. If you can write clear instructions for a colleague, you can write a custom Skill.

The SKILL.md file: your instruction manual for Claude

A custom Skill is a Markdown file with a specific name: SKILL.md (or a descriptive variant like meeting-summariser.md). It contains two parts:

  1. YAML frontmatter — metadata that tells Claude what the skill is, when to activate it, and how to find it
  2. Instruction body — the actual step-by-step procedure, written in natural language

The frontmatter lives between triple-dash markers (---) at the top of the file. It includes the skill's name, version, description, and — most critically — trigger conditions that tell Claude when to activate the skill. The instruction body follows the frontmatter and contains everything Claude needs to execute the task: steps, examples of good and bad output, edge cases, and the expected format of the result.

Here is what the structure looks like in practice:

---
name: legal-check
version: 1.0
description: Scans contracts for five critical clauses and flags risk
trigger: when the user uploads a contract or legal document
---

## Steps
1. Identify and extract these clauses: indemnity, termination,
   confidentiality, liability cap, governing law
2. For each clause, assess risk on a scale of Low / Medium / High
3. Flag any clause where liability exceeds £500K
...
[!]

Exam Trap: No YAML Frontmatter = Invisible Skill

A skill file without YAML frontmatter is completely invisible to Claude. It can't be discovered during progressive disclosure, it can't be triggered, and it can't be loaded. The frontmatter isn't optional decoration — it's the mechanism by which Claude knows the skill exists. Omit it and you have written a Markdown file that Claude will never find.

Where to store skills: the non-negotiable directory

Custom Skills must be saved to ~/.claude/skills/ on your machine. This is the directory Claude scans during progressive disclosure. Store a skill file on your Desktop, in Downloads, or in a random project folder and Claude won't find it — the skill simply doesn't exist as far as the system is concerned.

The path is absolute and non-configurable: ~/.claude/skills/. Every skill file in this directory is eligible for discovery. Every skill file outside this directory is invisible. The exam tests this directly.

Trigger conditions: the difference between useful and chaotic

The trigger condition in the YAML frontmatter determines when Claude activates the skill. Get this right and the skill fires exactly when needed. Get it wrong and you have two failure modes:

Too broad: A trigger like "when the user asks about writing" fires on nearly every conversation. Claude loads the skill's full instructions into context unnecessarily, wasting tokens and potentially producing irrelevant output.

Too narrow: A trigger like "when the user uploads a file named exactly Q4-NDA-Review-Draft-v3.docx" almost never fires. The skill exists but never activates because the condition is unrealistically specific.

Good triggers are specific but not brittle:

  • "When the user uploads a contract and asks for a legal review" — specific enough to avoid false positives, flexible enough to match real usage
  • "When the user types /respond" — a slash command trigger that fires only on explicit invocation
  • "When the user requests a meeting summary from uploaded notes" — combines a file type with an action
[~]

Test Your Triggers

After creating a skill, test the trigger by describing the task in three different ways. If the skill activates on all three phrasings, the trigger is robust. If it only fires on one exact phrasing, it's too narrow. If it fires when you're doing something completely unrelated, it's too broad.

You don't need to be a developer

This is worth stating explicitly because the misconception is widespread: custom Skills are written in plain-English Markdown, not code. The SKILL.md file contains natural language instructions — the same kind of instructions you would write for a capable colleague who has never done this particular task before.

You don't need Python, JavaScript, or any programming language. You don't need to understand APIs, data structures, or software engineering concepts. If you can articulate "do this, then this, then check for this, and format the result like this," you can write a custom Skill.

What makes a good Skill is the same thing that makes good delegation: clarity, specificity, and concrete examples of what the finished product should look like.

The /skill-creator wizard

If you prefer guided creation over writing from scratch, the /skill-creator command launches an interactive wizard inside Cowork. It walks you through:

  1. Naming your skill
  2. Writing a description
  3. Defining trigger conditions
  4. Specifying step-by-step instructions
  5. Providing examples of expected output

The wizard generates a complete, properly formatted SKILL.md file that you can review, edit, and save to ~/.claude/skills/. It handles the YAML frontmatter structure automatically, which eliminates the most common creation error (forgetting or malforming the frontmatter).

For your first few skills, the wizard is the recommended path. As you become comfortable with the format, writing SKILL.md files directly becomes faster.

What custom Skills can't do

Custom Skills have deliberate constraints:

  • No network access — a Skill can't call an API, query a database, or reach any external service. External data access requires an MCP Connector.
  • No persistent state — a Skill doesn't remember previous invocations. Each activation starts fresh with the instructions and whatever data is in the current context.
  • No system-level access — a Skill can't install software, modify system settings, or access files outside the granted working folder.

These constraints are features, not bugs. They are what make Skills safe to run on sensitive data and what allow progressive disclosure to work efficiently. If a Skill could make arbitrary network calls, the entire security model would be undermined.

Common Mistakes

Common Mistake

Writing a skill with a vague trigger like 'when the user asks about writing' — causing it to fire on nearly every conversation and pollute the context with irrelevant instructions.

Instead: Write specific trigger conditions that combine an action with a context: 'when the user uploads a contract and asks for a legal review' or 'when the user types /brand-check'. Test with three different phrasings to verify the trigger is neither too broad nor too narrow.

Common Mistake

Saving the SKILL.md file to your Desktop, Documents folder, or a project directory — then wondering why Claude never activates it.

Instead: Always save custom Skills to ~/.claude/skills/. This is the only directory Claude scans for skill discovery. Files stored anywhere else are invisible to the system.

Common Mistake

Writing a SKILL.md file with detailed instructions but forgetting the YAML frontmatter block at the top — creating a file that Claude can never discover or activate.

Instead: Every SKILL.md file must start with YAML frontmatter between --- markers, including at minimum: name, description, and trigger conditions. Use the /skill-creator wizard if you're unsure about the format.

Creating a reusable review process

Before

Create a skill that makes me a better writer.

After

Create a skill called 'Legal-Check' that triggers when I upload a contract. It should scan for these 5 specific clauses: indemnity, termination, confidentiality, liability cap, and governing law. For each, extract the relevant text and flag any clause where the liability exceeds £500K.

Building an email response template

Before

Make a skill for emails.

After

Create a skill called 'Client-Response' that triggers when I type '/respond'. It should use our company's formal tone (no contractions, British English, sign off with 'Kind regards'), acknowledge the client's specific concern, propose a next step with a date, and keep the response under 200 words.

Hands-On Activity

Hands-On Activity

Create Your First Custom Skill

15 min

Use the /skill-creator wizard to build a Meeting Summariser skill, verify the YAML frontmatter structure, save it to the correct directory, and test it with real meeting notes. By the end, you'll have a working custom Skill that activates automatically when you upload meeting notes.

What you will learn

  • Use the /skill-creator wizard to generate a properly structured SKILL.md file
  • Verify that YAML frontmatter includes name, version, description, and trigger conditions
  • Save the skill to ~/.claude/skills/ and confirm Claude discovers it
  • Test the skill with sample input and verify it produces the expected output format
  1. 01

    In Claude Cowork, type /skill-creator to launch the skill creation wizard.

    Why: The wizard guides you through the structure of a SKILL.md file without needing to know the format from memory. It is the recommended starting point for first-time skill creators.

    Expected: Claude presents a series of prompts asking for your skill's name, description, trigger conditions, and step-by-step instructions.

  2. 02

    Follow the prompts to define a Meeting Summariser skill: it should trigger when you upload meeting notes, extract action items with owners and deadlines, and output a structured summary using bullet points.

    Why: A Meeting Summariser is practical (you'll actually use it) and simple enough to complete in one session whilst demonstrating all key skill components: trigger, instructions, and output format.

    Expected: Claude generates a complete SKILL.md file with YAML frontmatter, trigger conditions, step-by-step instructions, and example output.

  3. 03

    Review the generated SKILL.md file. Check that the YAML frontmatter includes a name, version, and description. Verify the trigger conditions are specific enough to avoid false activations.

    Why: Reviewing the output builds your understanding of skill structure and catches overly broad triggers before they cause problems in production use.

    Expected: A properly formatted Markdown file with --- delimited YAML frontmatter at the top, followed by natural-language instructions and example outputs.

  4. 04

    Save the SKILL.md file to your ~/.claude/skills/ directory. Then test it by uploading sample meeting notes and observing whether the skill activates correctly.

    Why: Placing the file in the correct directory and testing activation confirms the full skill lifecycle: creation, storage, discovery, and execution.

    Expected: Claude detects the new skill, activates it when you upload meeting notes, and produces a structured summary with action items, owners, and deadlines.

Practice Question

Practice Question

A legal firm wants Claude to follow their proprietary 15-step process for reviewing Non-Disclosure Agreements. The process includes specific clause checks, risk scoring criteria, and a mandatory output template. What is the best approach?

Sources