1. What Is a Skill in Claude.ai?

If you have ever wished Claude could behave differently for specific tasks — following your exact process, using your terminology, or applying rules that are unique to your workflow — that is exactly what Skills are built for.

A Skill is a Markdown file called SKILL.md that lives in a designated folder on a connected filesystem. When Claude picks up a conversation, it scans available skills, decides which ones are relevant to the current request, reads those files, and uses the instructions inside them to shape its response.

Think of it like an onboarding document for a new hire. You do not reprogram the person — you just give them a clear, detailed brief for how to handle a particular type of work. Claude reads that brief and runs with it.

💡 KEY CONCEPT Skills are NOT system prompts, NOT fine-tuning, and NOT plugins. They are plain text instruction files that Claude reads at runtime. No code deployment required.

2. Why Skills Exist: The Problem They Solve

Claude is a generalist. Out of the box, it writes clean prose, debugs code, answers questions, and analyses data. But generalists make trade-offs. When you need Claude to:

• Always write in a specific tone or structure
• Follow a multi-phase research process before answering
• Apply industry-specific rules (legal, medical, financial)
• Use your company’s internal terminology consistently
• Output files in a specific format every single time

…you previously had two options: paste a long system prompt every session, or accept inconsistent results. Skills solve this permanently.

The skill system essentially gives you a library of specialisations that Claude loads on demand. You might have a skill for writing blog articles, another for creating landing pages, another for analysing spreadsheets — and Claude will pick the right one automatically based on what you ask.

3. How Claude Reads Skills (Under the Hood)

Understanding the mechanics helps you write better skills. Here is what happens when you send a message to Claude in an environment with skills configured:

1. Claude receives your message
2. It scans the available skill directories for SKILL.md files
3. It reads each skill’s description field from the YAML front-matter
4. It matches your message against those descriptions using semantic reasoning
5. If one or more skills match, it reads the full SKILL.md body
6. It executes your request using those instructions as its operating framework

This matching step is where most skill failures happen. If your description is vague, Claude will not trigger the skill when it should. If it is too broad, Claude will trigger it when it should not. Getting this right is the single most important skill-writing skill you can develop.

⚙️ HOW IT WORKS Claude uses semantic matching, not keyword matching. A description saying ‘Use when someone asks to write an article or blog post’ will also fire for ‘draft a guide’, ‘create a how-to’, or ‘write content for my website’.

4. Anatomy of a SKILL.md File

A SKILL.md file has two parts: a YAML front-matter block at the top, and the instruction body below it.

4.1 The YAML Front-Matter

Wrapped in triple dashes, this is the metadata Claude reads to decide whether to load the skill at all.

—

name: article-writer

description: >

  Use this skill whenever the user wants to write, draft, or improve

  an article, blog post, guide, or any long-form written content.

  Triggers on: ‘write an article’, ‘create content about’, ‘SEO article’,

  ‘blog content’, or requests to improve existing articles.

license: Proprietary

—

The three required fields are:

• name: — a short machine-readable identifier
• description: — the natural language trigger (most important field)
• license: — can be Proprietary, MIT, Apache, or any label you choose

4.2 The Instruction Body

Everything below the closing — is the skill’s actual instructions. This is pure Markdown. You can use any formatting: headings, bullet lists, numbered steps, tables, code blocks. Claude reads it all.

The body is where you define:

• Phases or steps Claude must follow
• Rules and constraints
• Output formats and templates
• Examples of good and bad outputs
• Edge cases and how to handle them

4.3 Quick Reference: Skill File Structure

What	Where	How
SKILL.md — the brain	/mnt/skills/public/ or /mnt/skills/user/	Plain Markdown + YAML front-matter
Trigger description	description: field in YAML	Natural language; be specific
Instructions	Body of SKILL.md	Phases, rules, examples
References folder	Same directory as SKILL.md	Optional extra .md files
Activation	Claude reads it before responding	Automatic — no code needed

5. Step-by-Step: Creating Your First Skill

Step 1 — Define the job

Before you open a text editor, answer these three questions:

• What specific task will this skill handle?
• When should it fire? (What phrases or contexts trigger it?)
• What should Claude do differently with this skill vs. without it?

Write the answers down. These become your description and your instruction body.

Step 2 — Create the file structure

Skills live in designated directories. The standard layout is:

/mnt/skills/

  public/          ← built-in skills (do not edit)

  user/            ← your custom skills (create here)

    my-skill-name/

      SKILL.md     ← the main file

      references/  ← optional supporting docs

📁 FILE PLACEMENT Always create a folder with your skill name, then put SKILL.md inside it. Do not put SKILL.md directly in the user/ root directory.

Step 3 — Write the front-matter

Open SKILL.md and start with the YAML block. Focus most of your energy on the description field. Be specific about:

• The exact types of requests that should trigger this skill
• Example phrases a user might say
• What NOT to trigger on (negative examples)

Step 4 — Write the instruction body

Structure your instructions as phases. Claude responds well to numbered phases because it creates a clear execution order. A typical skill body looks like this:

# My Skill Name

## PHASE 0: Information Gathering

Ask the user for X, Y, Z before proceeding.

## PHASE 1: Research

Search for [specific things] using these queries: [examples].

## PHASE 2: Execution

Follow these rules when creating the output: [rules].

## OUTPUT FORMAT

Deliver results in this exact structure: [template].

Step 5 — Test it

Start a new conversation (skills are loaded at conversation start) and ask a request that should trigger your skill. Check:

• Did Claude follow the phases you defined?
• Did it apply your rules correctly?
• Did the output format match your template?

If not, the issue is almost always in the description (wrong trigger) or in the instruction clarity (ambiguous rules). Iterate.

6. Writing Triggers That Actually Fire

The description field is the most technically sensitive part of a skill. Here is a proven formula:

✍️ TRIGGER FORMULA FORMULA: “Use this skill when [primary verb phrases]. Triggers on: [list of example phrases]. Also triggers when [broader contexts]. Do NOT trigger for [negative cases].”

Positive Triggers — Be Generous

List every variation of how someone might ask for this type of work. Users do not know your skill names — they will phrase requests in dozens of different ways.

Good example for an article-writing skill:

• ‘write an article’, ‘write a blog post’, ‘create content’
• ‘draft a guide’, ‘write a how-to’, ‘create a tutorial’
• ‘write about X’, ‘make content about X’
• ‘improve my article’, ‘rewrite this post’, ‘make it more SEO-friendly’

Negative Triggers — Be Specific

Tell Claude what should NOT trigger this skill. This prevents false positives.

Example negative triggers for an article-writing skill:

• Do NOT trigger for code documentation or technical README files
• Do NOT trigger for email drafting requests
• Do NOT trigger for social media posts under 280 characters

7. Structuring Skill Instructions Like a Pro

The Phase Architecture

The most effective skills use a phase-based structure. Each phase is a clear, numbered stage that Claude must complete before moving to the next. This creates predictable, auditable outputs.

The five universal phases that work across almost any skill type:

• PHASE 0: Information Gathering — What does Claude need to know before starting? What should it ask the user if missing?
• PHASE 1: Research / Analysis — What external work needs to happen first? (web search, reading files, analysing data)
• PHASE 2: Planning — What should Claude plan, outline, or decide before executing?
• PHASE 3: Execution — The main task. Detailed rules for the actual work.
• PHASE 4: Quality Check — What should Claude verify before delivering the result?

Rules vs. Guidelines

Be explicit about what is a hard rule (must always do) vs. a soft guideline (prefer when appropriate). Claude will follow hard rules strictly. Use this language:

• Hard rules: ‘ALWAYS’, ‘NEVER’, ‘MUST’, ‘DO NOT’
• Guidelines: ‘prefer’, ‘when relevant’, ‘if appropriate’, ‘generally’

Anti-Slop Safeguards

One of the most powerful things you can add to any skill is an explicit list of bad patterns to avoid. Example:

## ANTI-SLOP RULES

NEVER start responses with ‘Great question!’

NEVER use the phrase ‘delve into’

NEVER pad word count with repetitive summaries

ALWAYS use specific examples, never abstract generalisations

💡 PRO TIP The more concrete your rules, the better Claude follows them. ‘Write clearly’ is weak. ‘Sentences must average 15 words or fewer’ is strong.

8. The References Folder — Advanced Context

For complex skills, a single SKILL.md file can get unwieldy. The references folder solves this. It sits next to your SKILL.md and contains supplementary Markdown files that Claude can read for deeper context.

my-skill/

  SKILL.md

  references/

    article-types.md      ← instructions by content format

    style-guide.md        ← brand voice and tone rules

    example-outputs.md    ← model outputs for few-shot learning

    compliance-rules.md   ← industry-specific constraints

In your SKILL.md, reference these files explicitly:

## PHASE 2: Writing

Read references/style-guide.md for tone and voice rules.

Read references/article-types.md for format-specific instructions.

Claude will load and apply these files when it reaches those phases. This keeps your main SKILL.md clean and readable while allowing deep, specialised instruction sets.

9. Real-World Skill Examples

Example A: Content Writing Skill

This skill fires for any article, blog post, or guide writing request. Its key phases are: keyword research, competitive analysis, article blueprint, writing with human voice, and SEO checks. Its signature feature is an explicit ‘anti-slop’ section that lists forbidden AI clichés by name.

Example B: Landing Page / Prelander Skill

This skill fires for marketing page creation. It mandates a research phase before any design work: competitor analysis, audience psychology research, regulatory compliance check. Every design decision must trace back to research findings. It explicitly forbids starting to code before completing the research phase — and lists this as a hard rule.

Example C: Spreadsheet (XLSX) Skill

This skill fires when a .xlsx file is involved. It instructs Claude on the exact npm packages to use, how to handle dual-width tables, how to structure formulas, and how to validate output. It includes code snippets that Claude copies directly — ensuring consistent, technically correct spreadsheet generation every time.

WHAT GREAT SKILLS HAVE IN COMMON Notice the pattern: the best skills are opinionated. They do not leave room for interpretation on the important things. They tell Claude exactly how to handle edge cases, not just the happy path.

10. Common Mistakes and How to Avoid Them

Mistake	What Happens	Fix
Vague description field	Skill never fires, or fires randomly	List specific trigger phrases with examples
No negative triggers	Skill fires for unrelated requests	Add explicit DO NOT trigger cases
Instructions too abstract	Claude interprets rules loosely	Use ALWAYS/NEVER, give concrete examples
No output template	Format varies every time	Define exact output structure in PHASE 4
No quality check phase	Errors slip through	Add a checklist Claude must run before delivery
Mixing phases and rules	Claude skips phases	Keep phases numbered and sequential
File in wrong location	Skill never loads	Use user/ subdirectory with skill name folder

11. Frequently Asked Questions

Can I have multiple skills active at once?

Yes. Claude can read and apply multiple skills in a single response if the request matches more than one. This is intentional — you might have a writing skill and a compliance skill that both apply to a legal article request.

Do skills persist across conversations?

Skills are loaded at conversation start from the filesystem. As long as the files exist and the filesystem is connected, they are always available. They do not expire or need to be re-activated.

Can I use skills to give Claude memory?

Not directly. Skills provide instructions, not user-specific memory. For persistent memory, use Claude’s built-in memory feature or maintain a separate context document that Claude reads via a skill instruction.

How long can a SKILL.md file be?

There is no hard limit on file size, but practical limits apply. Very long skill files can cause Claude to lose focus on specific rules as they get buried in volume. Keep your core SKILL.md under 500 lines and offload detail to references/ files. Aim for clarity over comprehensiveness.

Can skills call external APIs or run code?

Skills themselves are just text instructions. But within a skill, you can instruct Claude to use tools it already has access to — web search, code execution, file creation. The skill tells Claude when and how to use those tools.

What is the difference between user/ and public/ skills?

The public/ directory contains system-provided skills maintained by the platform. The user/ directory is yours to create, modify, and manage. User skills take precedence and can override or supplement public skills.

How do I debug a skill that is not triggering?

Ask Claude directly: ‘What skills do you have available, and which ones apply to this request?’ Claude will tell you what it sees and why it is or is not applying a skill. Adjust your description field based on what it reports.

The Bottom Line A skill is not a magic switch. It is a brief you write for Claude. The better your brief, the better Claude’s work. The best skill creators are not technical — they are precise thinkers who can articulate exactly what good work looks like, step by step, with no ambiguity.