How to master Claude skills for beginners

Full tutorial

Introduction

You’ve been using Claude. You’ve been watching people build entire businesses with Skills and orchestration layers and multi-agent pipelines, and you’re sitting there thinking... what am I missing?

I’ve combined every resource worth reading into a single course on Claude Skills. Not theory. Not “here’s what a Skill could do.” Actual, build-it-right-now, deploy-it-today instruction. In less than 10 minutes you’ll have your first custom Skill running. After you finish this, you will understand Skills better than 99% of the people talking about them online.

Yes, really.

Here’s how this is structured:

• Module 1: Foundations - what Skills actually are and how to build your first one

• Module 2: Architecture - scripts, orchestration, and what to do when you have more than three Skills fighting each other

• Module 3: Testing and Iteration - how to stop guessing and start proving your Skills work

• Module 4: Production Deployment - making Skills survive across sessions, at scale, over time

In every module I’m going to give you the foundations AND the prompts to get AI to do the heavy lifting for you. Because here’s the thing - you need to understand what’s happening, but you don’t need to suffer through building it manually if you don’t want to.

Let’s go.

---

Module 1: Foundations

Skills vs Projects vs MCP - Know What You’re Actually Building

Before you build anything, you need to understand where Skills sit inside Claude’s ecosystem. Three tools. Three completely different jobs. Most people conflate them. Don’t be most people.

Projects are your knowledge base. You upload a brand guideline PDF and you’re telling Claude: “Here’s what you need to know.” That’s it. It’s static. It’s reference material. It’s a library. The librarian doesn’t DO anything with the books - it just knows where they are.

Skills are your instruction manual. You’re telling Claude: “Here’s exactly how you perform this task, step by step.” This is procedural. This is automated. This isn’t a librarian - this is a trained employee who knows exactly how to process an invoice the way YOU want it processed, every single time.

MCP (Model Context Protocol) is your connection layer. This plugs Claude into live data sources - your calendar, your database, your inbox. Skills then tell Claude what to DO with that data. MCP is the plumbing. Skills are the instructions for what flows through the pipes.

So, how do you know if you need a Skill?

Simple. If you’ve typed the same instructions at the start of more than three conversations, that’s a Skill begging to be built. If you want Claude to stop being a generic chatbot and start being a professional operator in a specific domain, Skills are how you turn it into an employee.

The Anatomy Of A Skill

Here’s where every other guide on the internet decides to overcomplicate things and scare you off. Let me strip it down to what it actually is.

A Skill is a folder on your computer. Inside that folder is a text file. That’s it.

A folder with a text file called SKILL.md.

I know. Anticlimactic. But that’s the truth, and the truth is your friend here because it means you can build one in minutes, not days.

The folder follows three rules:

The Root Folder must use kebab-case naming. That means lowercase, words separated by hyphens. invoice-organiser. email-formatter. csv-cleaner. No spaces. No underscores. No capitals. If you’re the kind of person who names folders “My Cool Skill v2 FINAL (2)” - break that habit right now.

SKILL.md is the brain. This is case-sensitive. Not skill.md. Not README.md. Exactly SKILL.md. All your instructions live here.

references/ is optional. If your instructions need a massive brand guide or a long template, drop it in this subfolder instead of pasting it into SKILL.md. Think of it as the filing cabinet next to the employee’s desk.

Drop the whole folder into ~/.claude/skills/ on your machine.

Claude finds it automatically.

That’s the entire physical architecture. A folder, a markdown file, and optionally a subfolder for reference docs. I told you this was simple.

Where Do They Run?

This matters more than most guides tell you, and most guides don’t tell you at all.

Claude Code is the command-line tool for developers. Skills here live in your project directory under .claude/skills/ or globally at ~/.claude/skills/. They have access to the file system, bash commands, and can execute code. This is where you build Skills that manipulate files, run scripts, and interact with your codebase. If you’re a developer, this is your playground.

Claude Desktop (CoWork) is the desktop agent for non-developers. Skills here work through the desktop interface and can interact with your screen, applications, and files through the agent’s capabilities. Same SKILL.md format. Different execution environment.

The format is identical. The environment is different. Know which one you’re building for.

If you’re ever unsure whether you even NEED a Skill, or you just want Claude to help you figure it out, here’s a prompt that does the thinking for you:

I want you to help me identify whether I need a Claude Skill.

Here's how this works:

1. Ask me to describe the 3-5 tasks I repeat most often when
   using AI assistants. For each one, ask me:
   - What instructions do I typically give at the start?
   - How often do I repeat this task per week?
   - Does the output need to follow a specific format, tone,
     or structure every time?

2. After I describe each task, score it on a "Skill Readiness"
   scale of 1-10 based on:
   - Repetition frequency (higher = more ready)
   - Instruction complexity (more specific instructions =
     more ready)
   - Output consistency requirements (stricter format needs =
     more ready)

3. Rank my tasks from highest to lowest Skill Readiness score.

4. For my top-scoring task, tell me:
   - Why this is the best candidate for my first Skill
   - What the Skill would need to contain
   - An estimate of time saved per week if I automate it
   - Whether this is better suited for Claude Code or
     Claude Desktop (CoWork)

Start by asking me about my first repeated task.

Building Your First Skill

Alright. Theory is over. Time to actually build something.

Step 1: Define the Job

Before you write a single word, answer three questions. And I mean actually answer them - not hand-wave your way through with vague intentions.

What does this Skill do? Be ruthlessly specific. “Help with data” is useless. You know what’s not useless? “Transform messy CSV files into clean spreadsheets with proper headers, enforce YYYY-MM-DD date formatting, and strip empty rows.” THAT is a Skill that works.

When should it fire? Think about what you’d actually type. “Clean up this CSV.” “Fix these headers.” “Format this data.” Those are your triggers. If you can’t list at least five phrases you might use to invoke this Skill, you haven’t thought about it hard enough.

What does “good” look like? You need a concrete example of the finished output. Not a description. An actual before-and-after. If you can’t show someone what “done” looks like, your Skill doesn’t know what “done” looks like either.

Listen closely. This step is where 90% of bad Skills are born. Vague instructions create vague outputs. Every. Single. Time. It’s not Claude’s fault your Skill produces garbage - it’s yours, because you told it to “handle things appropriately” instead of telling it EXACTLY what to do.

Don’t trust yourself to get specific enough? Good - that’s self-awareness. This prompt forces the precision out of you:

PROMPT: THE SKILL DEFINITION INTERVIEW

You are a Skill Definition Specialist. Your job is to interview 
me until we have a razor-sharp definition of the Claude Skill 
I want to build. You will not let me get away with vague answers.

Run this interview process:

PHASE 1 - THE TASK
Ask me: "What task do you want to automate?" 
After I answer, pressure-test my response:
- If my answer is vague (e.g., "help with emails"), push back 
  and ask me to describe EXACTLY what the Skill should do, 
  with a specific input and specific output.
- Keep asking "Can you be more specific?" until the task 
  description is concrete and actionable.
- Confirm the final task definition back to me in one sentence.

PHASE 2 - THE TRIGGERS
Ask me: "What would you actually type into Claude to activate 
this Skill? Give me 5 different ways you might phrase the request."
After I answer:
- Suggest 3-5 additional trigger phrases I probably missed.
- Ask me about negative boundaries: "What similar-sounding 
  requests should NOT trigger this Skill?"

PHASE 3 - THE QUALITY STANDARD
Ask me: "Show me or describe exactly what a PERFECT output 
looks like for this task."
After I answer:
- Ask me to describe what a FAILED output looks like 
  (so we know what to avoid).
- Ask me about edge cases: "What's the weirdest or most 
  broken input this Skill might receive? How should it handle it?"

PHASE 4 - THE SUMMARY
Compile everything into a structured "Skill Definition Brief" 
with these sections:
- Skill Name (in kebab-case)
- One-Sentence Purpose
- Trigger Phrases (positive)
- Negative Boundaries (when NOT to fire)
- Input Description
- Output Description
- Quality Standard (what "good" looks like)
- Edge Cases to Handle

Present this brief and ask me to confirm or revise before 
we proceed.

Start Phase 1 now.

Step 2: Write the YAML Triggers

At the top of your SKILL.md file, you write a block of metadata between --- lines. This is called YAML frontmatter. It tells Claude when to activate your Skill.

Here’s an example:

---
name: csv-cleaner
description: Transforms messy CSV files into clean spreadsheets. Use this skill whenever the user says 'clean up this CSV', 'fix the headers', 'format this data', or 'organise this spreadsheet'. Do NOT use for PDFs, Word documents, or image files.
---

Three rules that make or break your triggers:

Write in third person. “Processes files...” not “I can help you...” Claude isn’t talking about itself here. It’s reading a job description.

List exact trigger phrases. Claude is conservative about activation. CONSERVATIVE. You need to spell out what the user might say. Be pushy. Be embarrassingly explicit. If you’re not slightly cringing at how over-the-top your trigger phrases are, you haven’t written enough of them.

Set negative boundaries. Tell Claude when NOT to fire. This prevents your Skill from hijacking unrelated conversations. Without negative boundaries, your CSV cleaner will try to activate every time someone mentions a spreadsheet, even if they just want to talk about Excel formulas.

Here’s the thing most people miss. The description field is the single most important line in your entire Skill. Not the instructions. Not the examples. The description. If it’s weak, your Skill never fires. If it’s too broad, it fires when you don’t want it to. Everything downstream depends on getting this right.

PROMPT: THE YAML TRIGGER GENERATOR

You are a YAML Frontmatter Specialist for Claude Skills. 
Your job is to write the most effective possible YAML trigger 
block for the top of a SKILL.md file.

Here is my Skill definition:
[PASTE YOUR SKILL DEFINITION BRIEF HERE, OR DESCRIBE YOUR 
SKILL IN 2-3 SENTENCES]

Generate the YAML frontmatter following these strict rules:

1. The "name" field must be in kebab-case (lowercase, 
   hyphens only, no spaces or underscores).

2. The "description" field must be "pushy" - meaning it 
   should aggressively list trigger scenarios because Claude 
   is conservative about skill activation. Include:
   - A clear one-sentence summary of what the skill does 
     (written in third person: "Processes..." not "I can...")
   - At least 5-7 explicit trigger phrases the user might say, 
     formatted as: "Use this skill whenever the user says 
     '[phrase 1]', '[phrase 2]', '[phrase 3]'..."
   - Negative boundaries: "Do NOT use this skill for [X], 
     [Y], or [Z]."
   - Context clues: "Also activate when the user uploads 
     [file type] and asks for [action]."

3. Keep the entire description under 300 words but make 
   every word count.

Output ONLY the YAML block (between --- markers), ready to 
paste directly into a SKILL.md file. No explanation needed.

Then, below the YAML block, provide a "Trigger Confidence 
Report" that rates:
- Activation likelihood on relevant requests: X/10
- False positive risk (firing when it shouldn't): X/10
- Coverage of common phrasings: X/10

If any score is below 7/10, suggest specific improvements.

Step 3: Write the Instructions

Below the --- marks, you write your workflow in plain English. Structured with headings. Sequential. Under 500 lines.

This is where a lot of people go wrong in the opposite direction from Step 1. They were too vague in the definition, and now they’re writing a novel in the instructions. You don’t need War and Peace. You need a recipe that a very smart, very literal employee can follow without asking you questions.

Two components make this work:

The Steps. Break the workflow into a logical sequence. Each step is one action. Not two actions smooshed together. Not a paragraph of explanation. One clear, imperative command.

1. Read the provided file to understand its structure
2. Identify the row containing the true column headers
3. Remove any empty rows or rows containing only commas
4. Enforce proper data types (dates must be YYYY-MM-DD)
5. Output the cleaned file with a summary of changes made

The Examples. This is where the magic actually lives. A single concrete example showing input and expected output is worth more than 50 lines of abstract description. I cannot stress this enough. Claude learns from examples the way humans learn from watching someone do the thing. Show it the thing.

PROMPT: THE SKILL INSTRUCTION ARCHITECT

You are a Claude Skill instruction writer. Your job is to 
generate the complete instruction body for a SKILL.md file 
that is clear, sequential, and under 500 lines.

Here is my Skill definition:
[PASTE YOUR SKILL DEFINITION BRIEF FROM STEP 1]

Here is the YAML frontmatter already written:
[PASTE YOUR YAML BLOCK FROM STEP 2]

Now generate the full instruction body that goes BELOW the 
closing --- of the YAML block. Follow these rules precisely:

STRUCTURE RULES:
1. Start with a one-paragraph "Overview" that states what 
   this skill does and when it activates, written for Claude 
   (not for a human reader).
2. Break the workflow into numbered steps under a 
   "## Workflow" heading. Each step must be:
   - One clear action
   - Written as an imperative command ("Read the file..." 
     not "The file should be read...")
   - Specific enough that there is only ONE way to 
     interpret it
3. Include a "## Output Format" section that specifies 
   exactly how the final output should be structured 
   (file type, formatting, sections, tone, etc.)
4. Include a "## Edge Cases" section that tells Claude 
   how to handle:
   - Missing or incomplete input
   - Ambiguous requests
   - Conflicting instructions
   - Unexpected file formats or data types

EXAMPLE RULES:
5. Include at least 2 concrete examples under a 
   "## Examples" heading:
   - Example 1: A straightforward "happy path" showing 
     normal input → expected output
   - Example 2: An edge case showing unusual input → 
     how Claude should handle it
   Each example must show ACTUAL input and ACTUAL expected 
   output, not abstract descriptions.

QUALITY RULES:
6. Total length: aim for 100-300 lines. Cut anything 
   that doesn't directly instruct Claude on how to 
   execute the task.
7. Never use vague language like "handle appropriately" 
   or "format nicely." Every instruction must be specific 
   and testable.
8. If the skill requires referencing external files 
   (brand guides, templates), add a "## References" 
   section with the instruction: "Read [filename] from 
   the references/ directory before beginning the task."

Output the complete instruction body as markdown, ready to 
paste directly below the YAML frontmatter in a SKILL.md file.

After the instructions, provide a "Quality Checklist" that 
confirms:
- [ ] Every step is a single, unambiguous action
- [ ] At least 2 concrete examples included
- [ ] Edge cases are covered
- [ ] Output format is explicitly defined
- [ ] Total length is under 500 lines
- [ ] No vague or interpretable language remains

Step 4: The One Level Deep Rule (References)

If your instructions reference a massive brand guideline or template, don’t paste the whole thing into SKILL.md. That’s context bloat, and context bloat is the silent killer of Skill performance.

Save it as a separate file inside the references/ folder. Then link to it directly from your instructions.

But here’s the critical constraint that most people learn the hard way: never have reference files linking to other reference files. Claude will truncate its reading and miss information. One level deep. That’s it. No rabbit holes. No “see also” chains. Your reference file is a dead end by design.

Think of it like giving an employee a binder. They can open the binder and read it. But if page 7 of the binder says “now go read the other binder on the third shelf,” you’ve lost them. One binder. One level. Done.

PROMPT: THE REFERENCE FILE ORGANISER

You are a Skill Reference File Organiser. I have documents 
that my Claude Skill needs to reference during execution. 
Your job is to prepare them for the references/ directory.

Here are my reference documents:
[PASTE OR UPLOAD YOUR BRAND GUIDE / TEMPLATE / SOP / 
STYLE SHEET / ANY REFERENCE MATERIAL]

For each document, do the following:

1. ASSESS: Is this document short enough to include 
   directly in the SKILL.md file (under 50 lines of 
   relevant content)? If yes, recommend inlining it 
   instead of creating a separate reference file.

2. COMPRESS: If it needs to be a separate reference file, 
   extract ONLY the sections that are directly relevant 
   to the Skill's task. Remove all preamble, background 
   context, and information the Skill will never need. 
   Aim to reduce the document by 50%+ while keeping all 
   actionable instructions.

3. FORMAT: Structure the compressed reference file with:
   - Clear markdown headings
   - Bullet points for rules and constraints
   - Bold text for critical requirements
   - A "Quick Reference" summary at the top (under 10 lines) 
     that captures the most important rules

4. NAME: Suggest a kebab-case filename for each reference 
   file (e.g., brand-voice-guide.md, email-template.md).

5. LINK: Write the exact line I should add to my SKILL.md 
   file to reference this document, e.g.:
   "Before beginning the task, read the brand voice guide 
   at references/brand-voice-guide.md"

6. VALIDATE: Check for the "One Level Deep" rule. Flag 
   any reference file that links to or depends on 
   ANOTHER reference file. If found, merge them into a 
   single file.

Output each prepared reference file in full, ready to save 
directly into the references/ directory.

Step 5: Assemble and Deploy

You’ve got every component. Time to put it together.

Your folder structure should look like this:

your-skill-name/
├── SKILL.md          (YAML header + instructions from Steps 2-3)
└── references/       (optional, from Step 4)
    └── your-ref.md

Drop the folder into ~/.claude/skills/ on your machine.

Done.

But wait. Before you declare victory, you want to make sure the whole thing is airtight. You wouldn’t ship code without running tests, and you shouldn’t deploy a Skill without an audit. This prompt does a final QA pass on your complete SKILL.md file:

PROMPT: THE SKILL QA AUDITOR

You are a Claude Skill Quality Assurance Auditor. I have 
built a complete SKILL.md file and I need you to audit it 
before I deploy it.

Here is my complete SKILL.md file:
[PASTE YOUR ENTIRE SKILL.MD FILE HERE]

Run the following audit checks and report results:

## 1. YAML FRONTMATTER AUDIT
- [ ] name field exists and is valid kebab-case
- [ ] description field exists and is over 50 words
- [ ] description is written in third person
- [ ] At least 5 trigger phrases are listed
- [ ] Negative boundaries are defined (when NOT to activate)
- [ ] Description is "pushy" enough (would Claude actually 
      fire this skill on a relevant request?)
SCORE: X/10

## 2. INSTRUCTION CLARITY AUDIT
- [ ] Every step is a single, unambiguous action
- [ ] No vague language ("handle appropriately", 
      "format nicely", "as needed")
- [ ] Instructions are in imperative voice ("Read the 
      file" not "The file should be read")
- [ ] Sequential logic is correct (no step depends on 
      information from a later step)
- [ ] Total instruction length is under 500 lines
SCORE: X/10

## 3. EXAMPLE QUALITY AUDIT
- [ ] At least 2 examples are included
- [ ] Examples show ACTUAL input and ACTUAL output 
      (not abstract descriptions)
- [ ] At least one edge case example is included
- [ ] Examples are realistic (represent real-world usage)
SCORE: X/10

## 4. EDGE CASE COVERAGE AUDIT
- [ ] Missing/incomplete input is handled
- [ ] Ambiguous requests are handled
- [ ] Unexpected file types or data formats are handled
- [ ] The skill knows when to ask for clarification 
      vs. make a reasonable assumption
SCORE: X/10

## 5. REFERENCE FILE AUDIT (if applicable)
- [ ] All referenced files are at one level deep only
- [ ] No circular references
- [ ] Reference instructions in SKILL.md are clear 
      ("Read X before beginning")
SCORE: X/10

## OVERALL DEPLOYMENT READINESS: X/50

If any section scores below 7/10, provide SPECIFIC 
rewrites for the failing sections. Output the corrected 
text ready to paste directly into the file.

If overall score is 40+/50, confirm: "READY TO DEPLOY."
If below 40, list the critical fixes needed before 
deployment, in priority order.

The Shortcut: Let Claude Build Your Skill For You

If everything above feels like too much effort - or you just want to see how fast this can actually go - there’s a shortcut.

Anthropic built a meta-skill called skill-creator that constructs Skills for you through conversation. It’s Skills building Skills. We’re living in the future.

Here’s how it works:

1. Open a new chat. Type: “Use the skill-creator to help me build a skill for [your task].”

2. Upload your assets. Templates you use. Examples of past work. Brand guidelines. Anything that shows Claude what “good” looks like.

3. Answer the interview. The skill-creator asks you clarifying questions about your process, your edge cases, and your quality standards.

4. It generates everything. The formatted SKILL.md. The pushy description. The folder structure. Packaged and ready.

5. Save the folder to ~/.claude/skills/. Done.

Next time you ask Claude to perform that task, your Skill fires automatically.

Module 1 complete. You now have a deployed Skill. In Module 2, you’re going to learn what happens when “just instructions” isn’t enough, and how to architect Skills that actually scale.

---

Module 2: Architecture

You’ll eventually have more than a couple Skills. That’s when things get interesting - and when things start breaking if you don’t understand architecture.

I’m going to teach you the manual version of all of this AND give you prompts to automate it. But understanding the WHY matters here. A prompt can build the thing for you, but only you can decide whether the thing should exist in the first place.

When Instructions Aren’t Enough

Everything you’ve built so far uses plain English instructions. Claude reads them, follows them, produces output. That works beautifully for tasks that are about language, judgement, tone, decisions.

But some tasks need computation. They need code that runs. Calculations that execute. Data transformations that are too precise for “hey Claude, figure out the average.” Natural language is great for “rewrite this email in our brand voice.” It is terrible for “calculate a 90-day rolling weighted average with exponential decay.”

That’s what the scripts/ directory is for.

Use instructions when: The task is about judgement, language, formatting, or decision-making. “Rewrite this in our brand voice.” “Categorise these meeting notes.” “Draft an email.” Claude’s language brain handles these perfectly.

Use scripts when: The task requires precise computation, file manipulation, data transformation, or integration with external tools. “Calculate the running average of these numbers.” “Parse this XML file and extract specific fields.” “Resize all images in this folder to 800x600.” You wouldn’t ask your copywriter to do your accounting. Same principle.

Use both when: The task requires computation AND judgement. “Process this CSV (script), then write a human-readable summary of the anomalies found (instructions).” The script does the math. The instructions do the thinking. Together, they’re unstoppable.

How Scripts Work Inside a Skill

Your Skill’s instructions tell Claude WHEN and HOW to execute the scripts. The scripts themselves live in the scripts/ folder and do the actual computation.

Here’s a complete example:

data-analyser/
├── SKILL.md
├── references/
│   └── analysis-template.md
└── scripts/
    ├── parse-csv.py
    └── calculate-stats.py

In your SKILL.md, you reference the scripts like this:

## Workflow

1. Read the uploaded CSV file to understand its structure.

2. Run scripts/parse-csv.py to clean the data:
   - Command: `python scripts/parse-csv.py [input_file] [output_file]`
   - This removes empty rows, normalises headers, and
     enforces data types.

3. Run scripts/calculate-stats.py on the cleaned data:
   - Command: `python scripts/calculate-stats.py [cleaned_file]`
   - This outputs: mean, median, standard deviation, and
     outliers for each numeric column.

4. Read the statistical output and write a human-readable
   summary following the template in references/analysis-template.md.
   Highlight any anomalies or outliers that would concern
   a non-technical reader.

The key insight here - and it’s one of those things that seems obvious once you see it but isn’t obvious until you do: the scripts handle the computation, the instructions handle the judgement. They work together. Neither one is trying to do the other’s job.

Script Best Practices

Keep scripts focused. One script, one job. parse-csv.py doesn’t also calculate statistics. That’s a separate script. If you find yourself naming a script do-everything.py, you’ve gone wrong somewhere.

Make scripts accept arguments. Your script should take input/output file paths as command-line arguments, not hardcode them. This makes the Skill flexible instead of brittle.

Include error handling. Your script should exit with a clear error message if the input is malformed, missing, or the wrong format. Claude can then read the error and communicate it to the user instead of silently producing garbage.

Document the interface. At the top of each script, include a comment block explaining: what the script does, what arguments it expects, what it outputs, and what errors it might throw. Future you will thank present you.

PROMPT: THE SKILL SCRIPT BUILDER

I have a Claude Skill that needs executable scripts for
tasks that require computation rather than language processing.

Here is my current SKILL.md:
[PASTE YOUR SKILL.MD]

Here are the computational tasks that can't be handled by
instructions alone:
[DESCRIBE EACH TASK THAT NEEDS A SCRIPT, e.g.:
- "Parse XML files and extract specific fields"
- "Calculate statistical summaries of numeric data"
- "Resize and compress images in a folder"]

For each task, build a script that follows these rules:

1. Language: Use Python unless the task specifically requires
   another language. Python is available in both Claude Code
   and CoWork environments.

2. Interface: Accept all inputs as command-line arguments.
   No hardcoded file paths. Print output to stdout or write
   to a specified output file.

3. Error handling: Catch all common failure modes (missing
   files, malformed data, wrong types) and exit with a clear
   error message that Claude can parse.

4. Documentation: Include a comment block at the top with:
   - What the script does
   - Required arguments
   - Expected output format
   - Possible error conditions

5. Dependencies: Use only Python standard library where
   possible. If external packages are required, list them
   in a requirements.txt.

After generating the scripts:

6. Update the SKILL.md workflow to reference each script
   with the exact command syntax Claude should use.

7. Add error handling instructions to SKILL.md: what should
   Claude tell the user if a script fails?

Output:
- Each script file ready to save to scripts/
- Updated SKILL.md with script references
- requirements.txt (if external packages needed)

Multi-Skill Orchestration: When Your Skills Start Fighting Each Other

Here’s what happens after you build your fifth Skill. You start noticing conflicts. And they will drive you absolutely insane until you understand why they’re happening.

Your Brand Voice Enforcer fires when you wanted the Email Drafter. Your Code Review Assistant activates on a code snippet you just wanted formatted, not reviewed. Two Skills both think they should handle the same request and Claude picks the wrong one.

This is the multi-skill orchestration problem. And it gets worse - MUCH worse - the more Skills you build.

Here’s what’s happening under the hood. When you make a request, Claude scans all available Skills and evaluates their YAML descriptions against your prompt. It reads all the descriptions, scores each one for relevance against what you typed, and the highest-scoring Skill fires. If nothing scores above the activation threshold, none fires.

The problem is straightforward: if two Skills have overlapping trigger phrases, the wrong one might win. If descriptions are too vague, Skills fire on irrelevant requests. If descriptions are too narrow, Skills never fire at all. You’re walking a tightrope, and the tightrope gets thinner with every new Skill you add.

So, what do you do?

Three rules for multi-skill harmony:

Rule 1: Non-overlapping territories. Every Skill must have a clearly defined domain that doesn’t bleed into another Skill’s domain. The Brand Voice Enforcer handles voice compliance. The Email Drafter handles email composition. The Content Repurposer handles format transformation. No overlap. Period. Think of it like departments in a company. Accounting doesn’t do marketing’s job. Marketing doesn’t do engineering’s job. If two departments are fighting over the same task, you have an org chart problem.

Rule 2: Aggressive negative boundaries. Every Skill’s YAML description must explicitly list the other Skills’ territories as exclusions. Your Email Drafter should say “Do NOT use for brand voice checks or content repurposing.” Your Brand Voice Enforcer should say “Do NOT use for drafting emails from scratch or repurposing content.” Yes, this is redundant. Yes, redundancy is the point. You’re building fences, and fences need to be visible from both sides.

Rule 3: Distinctive trigger language. Each Skill should have trigger phrases that are unique to its function. “Check the voice” should only match the Brand Voice Enforcer. “Draft an email” should only match the Email Drafter. If you find yourself using the same trigger phrase for two Skills, one of them has a scope problem that needs fixing.

When the wrong Skill fires, the problem is almost always in the YAML description. Almost always. Here’s a prompt that audits your entire library for conflicts:

PROMPT: SKILL CONFLICT AUDITOR

I have multiple Claude Skills deployed and I'm experiencing
conflicts (wrong Skills firing, Skills not firing when they
should, or overlapping functionality).

Here are the YAML descriptions for ALL of my deployed Skills:

SKILL 1:
[PASTE THE FULL YAML DESCRIPTION FROM SKILL 1]

SKILL 2:
[PASTE THE FULL YAML DESCRIPTION FROM SKILL 2]

SKILL 3:
[PASTE THE FULL YAML DESCRIPTION FROM SKILL 3]

[ADD MORE AS NEEDED]

Run the following conflict analysis:

## 1. TERRITORY MAP
For each Skill, define its territory in one sentence.
Visualise the territories as a list and identify any overlaps.

## 2. TRIGGER PHRASE COLLISION TEST
List every trigger phrase from every Skill.
Flag any phrase that could match more than one Skill.
For each collision, recommend which Skill should own
the phrase and suggest an alternative for the other.

## 3. NEGATIVE BOUNDARY AUDIT
For each Skill, check whether its negative boundaries
explicitly exclude the territories of ALL other Skills.
Flag any missing exclusions.

## 4. AMBIGUOUS REQUEST TEST
Generate 10 realistic user requests that are ambiguous
(could potentially match multiple Skills).
For each, predict which Skill would fire and whether
that's the correct choice.

## 5. DEAD ZONE CHECK
Identify any common user requests that would NOT trigger
any of the deployed Skills but probably should.

## 6. RECOMMENDED FIXES
For each issue found, provide the corrected YAML description
ready to paste directly into the SKILL.md file.

Present findings as a structured report with priority-ranked
fixes.

Reference Strategies That Actually Scale

Module 1 covered the basics: one reference file, one level deep, keep it compressed.

But what happens when your Skill needs to reference a 50-page brand guide, a 30-page style manual, AND a library of templates? If you load all of that every time the Skill fires, you’re burning Claude’s context window on references it doesn’t need for the current task. That’s like making the employee read the entire company handbook every time they need to send a single email.

You need conditional loading. Load only what’s relevant to what the Skill is actually doing RIGHT NOW.

PROMPT: REFERENCE ARCHITECTURE DESIGNER

I have a Claude Skill that needs to reference multiple large
documents. I need help designing the reference file architecture
so Claude loads only what it needs for each request.

Here are the documents my Skill needs access to:
[LIST EACH DOCUMENT WITH ITS APPROXIMATE LENGTH AND PURPOSE,
e.g.:
- Brand voice guide (50 pages, covers tone, vocabulary,
  formatting)
- Email templates (10 templates for different situations)
- Client list with preferences (200 entries)
- Style manual (30 pages, covers visual and written style)]

Here is my SKILL.md:
[PASTE YOUR CURRENT SKILL.MD]

Design a reference architecture that:

1. Splits large documents into focused sub-files that can
   be loaded independently.

2. Creates a "quick reference" version of each major
   document (under 30 lines) that covers 80% of use cases.

3. Writes conditional loading instructions for the SKILL.md
   that tell Claude which references to read based on the
   type of request.

4. Ensures the "one level deep" rule is maintained (no
   reference file links to another reference file).

5. Estimates the token savings vs. loading everything
   every time.

Output:
- Complete folder structure diagram
- Each reference file (compressed and formatted)
- Updated SKILL.md with conditional loading instructions
- Token efficiency estimate

Module 2 complete. You now understand scripts for computation, multi-skill orchestration for conflict-free deployment, and reference strategies that scale without torching your context window.

In Module 3, you’re going to learn how to stop guessing and start PROVING your Skills work. Not “try it and see.” Prove it with data.

---

Module 3: Testing + Iteration

Here’s the difference between a Skill that “kind of works” and a Skill that runs like a trained employee. It’s this module. Testing, debugging, iterating until the failure modes are eliminated.

Most people build a Skill, try it twice, it looks “fine,” and they move on. Then it fails spectacularly on the third edge case they didn’t anticipate. And they blame Claude. And Claude didn’t do anything wrong - it followed their half-baked instructions perfectly.

The Five Failure Modes

Before you test anything, you need to know what you’re testing FOR. Every Skill failure falls into one of five categories. Learn to diagnose the category and the fix becomes obvious.

Failure Mode 1: The Silent Skill (Never Fires)

Your Skill is sitting there like an employee who showed up to work but nobody told them they had a job to do. You type a request that should trigger it. Claude responds normally. No indication the Skill was even considered.

Root cause? Your YAML description is too weak. Claude’s activation threshold requires a strong match between what you typed and the description. If your description is vague, generic, or missing key trigger phrases, it never crosses the threshold.

Look at your description. Does it explicitly list the words and phrases you just typed? If you said “clean up this spreadsheet” but your description only mentions “CSV files,” there’s your gap.

Fix: Make your description more pushy. Add more trigger phrases. Add context clues. The description should be almost embarrassingly explicit about when to activate. If it doesn’t feel a little over-the-top, it’s not pushy enough.

Failure Mode 2: The Hijacker (Fires on Wrong Requests)

The opposite problem. You ask Claude something completely unrelated and your Skill activates like an overeager golden retriever. You wanted to draft an email but the Content Repurposer decided it was its moment to shine.

Root cause: Your YAML description is too broad, or your negative boundaries are missing.

Look at what you typed and find which words matched the Skill’s description. Then check whether those words should have been excluded.

Fix: Add negative boundaries. “Do NOT use for [list every similar-but-different task].” Tighten your trigger phrases to be more specific.

Failure Mode 3: The Drifter (Fires But Produces Wrong Output)

The Skill activates correctly. Good. But the output doesn’t match what you expected. It’s close but not right. Formatting is off, tone is wrong, it skips steps.

Root cause: Your instructions are ambiguous. There’s more than one way to interpret what you wrote, and Claude chose a different interpretation than you intended. This is always YOUR fault, not Claude’s. Claude followed your instructions. Your instructions were just ambiguous enough to allow multiple valid interpretations.

Read your instructions as if you’ve never seen them before. Find the sentences that could mean two different things. That’s where the drift happens.

Fix: Replace ambiguous language with specific, testable instructions. “Format nicely” becomes “Use H2 headings for each section, bold the first sentence of each paragraph, keep paragraphs to 3 lines max.” Leave zero room for interpretation.

Failure Mode 4: The Fragile Skill (Works Sometimes, Breaks on Edge Cases)

Works perfectly on clean, well-formed inputs. Then you give it something slightly weird - incomplete data, unusual formatting, missing fields - and it collapses like a house of cards.

Root cause: Your edge case handling is incomplete. You built the Skill for the happy path and forgot that real-world inputs are messy, broken, and sometimes actively hostile.

Feed your Skill the worst-case version of every input. Missing fields. Extra fields. Wrong data types. Partially corrupted files. Mixed languages. See where it breaks.

Fix: Add explicit edge case instructions. For every scenario where it breaks, add a specific instruction: “If [condition], then [specific action].” No ambiguity. No “handle appropriately.”

Failure Mode 5: The Overachiever (Adds Things You Didn’t Ask For)

The Skill produces the requested output but ALSO adds unsolicited commentary, extra sections, creative embellishments you didn’t want. It answered the question, and then kept going. And going.

Root cause: Your instructions tell Claude what TO do but not what NOT to do. Without constraints, Claude defaults to being maximally helpful - which sometimes means doing way more than you asked for. Sound familiar? It’s sycophancy by design. Claude wants to please, and “doing more” feels like pleasing.

Fix: Add explicit scope constraints. “Do NOT add explanatory text, commentary, or suggestions unless the user asks for them. Output ONLY the [specified format] and nothing else.”

PROMPT: THE FAILURE MODE DIAGNOSTIC

My Claude Skill is not working as expected. I need help
diagnosing and fixing the problem.

Here is my complete SKILL.md:
[PASTE YOUR SKILL.MD]

Here is what happened:
- What I typed: [PASTE THE EXACT REQUEST YOU MADE]
- What I expected: [DESCRIBE EXPECTED BEHAVIOUR]
- What actually happened: [DESCRIBE ACTUAL BEHAVIOUR]

Diagnose this against the 5 Failure Modes:

1. Silent Skill (never fired) — Is the YAML description
   strong enough to match my request?
2. Hijacker (fired on wrong request) — Is the description
   too broad? Missing negative boundaries?
3. Drifter (wrong output) — Are instructions ambiguous?
4. Fragile Skill (broke on edge case) — Was my input
   an edge case not covered?
5. Overachiever (added unrequested content) — Are scope
   constraints missing?

For the identified failure mode:
- Explain exactly what caused the failure
- Provide the specific fix (corrected YAML, instruction,
  or edge case handling)
- Show the corrected section of SKILL.md ready to paste
- Suggest a test prompt to verify the fix works

Testing Your Skill (For Real This Time)

Here’s the thing. The Skills 2.0 update killed the guesswork. You now have professional-grade testing built in to Claude. Stop eyeballing your results and pretending that counts as testing. Go use the actual tools.

Evals: Write test prompts. Define exactly what the expected behaviour should be. The system runs your Skill against those prompts and returns a Pass/Fail grade. Not “looks okay.” Pass. Or Fail. Binary. Deterministic. Beautiful.

Benchmarks: Track your Skill’s pass rate, token consumption (cost), and execution speed over time. You can see whether your version 3 rewrite actually made things better or just felt like it did. Feelings are not data. Data is data.

A/B Comparator: Run a blind test between two versions of your Skill’s instructions. Hard data on which one wins. No more “I think version B is better.” You KNOW version B is better because the numbers say so.

Description Optimiser: Tells you definitively whether your YAML triggers will fire correctly when users ask for the task. No more guessing about trigger reliability.

Keep iterating until two consecutive evaluation runs show no significant improvement. That’s your signal. Your Skill is production-ready. Not “feels done.” Measurably done.

Module 3 complete. You now have a production-grade Skill backed by data, not vibes.

Module 4 is the final piece: deploying Skills that work across sessions, at scale, over time.

---

Module 4: Production Deployment

Your Skills work. They’re tested. They’re deployed.

Now the question shifts from “does it work?” to “does it work at scale, over time, across sessions?” Because here’s the thing about Claude’s context window - it fills up. And when it fills up, Claude forgets what happened yesterday. Your beautifully tested Skill doesn’t mean much if it can’t remember what it did in the last session.

State Management: The Shift Handover

When you’re running a Skill across multiple sessions - writing a book, building a complex app, managing a multi-week project - Claude’s context window eventually hits its limit.

It forgets what happened yesterday.

Expert Skill builders solve this with a “shift handover” system. Inside your SKILL.md, you add one instruction:

“At the start of every session, read context-log.md to see what we completed last time. At the end of every session, write a summary of what you finished and what’s still pending.”

That’s it. That’s the entire system.

Think of it like a hospital shift change. The incoming doctor reads the chart. They know exactly what happened, what’s pending, and what to watch for. They don’t need the outgoing doctor to stand there and re-explain everything from scratch. The chart IS the memory.

Your AI works the same way. The context log is the chart. Claude reads its own notes from the previous session and picks up exactly where it left off.

The End Game

You can keep opening Claude every morning and typing the same instructions you typed yesterday. And the day before. And the day before that. Burning through minutes that compound into hours that compound into weeks of lost output.

Or you can spend 10 minutes right now, build one Skill, and never type those instructions again.

The people who build Skills are operating Claude like a custom-built system tuned to their exact specifications. They’ve got an employee that knows their preferences, follows their processes, and improves over time.

Everyone else is using it like a chatbox.

Build your first Skill today. Pick the one task you repeat most often. Follow the steps above. Deploy it. Time how much faster your next session runs.

Then build another one.

And then...

You will see performance start to deteriorate. Your Skills will start contradicting each other. Claude will have too much to read before it starts working. Context bloat creeps back in.

So, what do you do?

You clean up. You consolidate rules and remove contradictions. You trim the fat. And it will feel like magic again.

That’s really the secret. Keep it simple, iterate on what works, be religiously mindful about context, and own the outcome. No Skill today is perfect. But a good Skill is a thousand times better than typing the same instructions into a chatbox every single morning.

Go build something.

If you want to be in the action of actually surrounded by builders then join my private club: joinopusclub.com