Practical Guide to Creating Claude Skills: Structure, Triggers, and Scripts

What Claude Skills Are and How They Work

Claude Skills are instruction manuals that automate specific tasks, distinct from Projects (knowledge bases) and Model Context Protocol (connection layer for live data). If you've typed the same instructions at the start of more than three conversations, that's a skill begging to be built.

Skill Structure and Setup

A skill is a folder containing one file called SKILL.md. The basic structure is:

your-skill-name/
├── SKILL.md
└── references/
    └── your-ref.md

Drop the folder into ~/.claude/skills/ on your machine. Claude finds it automatically.

YAML Triggers: The Activation Mechanism

At the top of SKILL.md, write metadata between --- lines to tell Claude when to activate. 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.
---

Follow three rules: write in third person, list exact trigger phrases, and set negative boundaries. The description field is the single most important line in the entire skill—weak description means the skill never fires.

When Instructions Aren't Enough: Scripts Directory

Plain English instructions handle judgement, language, formatting, and decisions. For tasks needing actual computation, add a scripts/ folder.

Use instructions for: "rewrite this in our brand voice" or "categorise these meeting notes."

Use scripts for: "calculate the running average of these numbers," "parse this XML and extract specific fields," or "resize all images in this folder to 800x600."

Folder structure for a skill using both:

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

Inside SKILL.md, reference 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.

Scripts handle computation; instructions handle judgement. One rule for scripts: one script, one job. parse-csv.py shouldn't also calculate statistics. Keep them focused, accept file paths as arguments, never hardcode paths, and always include error handling so Claude can read failures and communicate them cleanly.

References: The One Level Deep Rule

If a skill needs a brand guide or template, drop it into references/ and link to it from SKILL.md. Never have reference files linking to other reference files—Claude will truncate its reading and miss things. One level deep only.

your-skill-name/
├── SKILL.md
└── references/
    └── brand-voice-guide.md ← link to this from SKILL.md ← never link to another file from here

In SKILL.md: Before beginning the task, read the brand voice guide at references/brand-voice-guide.md

Multi-Skill Orchestration: Preventing Conflicts

Once you have five or more skills deployed, conflicts start—like the brand voice enforcer firing when you wanted the email drafter. Three rules stop this:

• Rule 1: Non-overlapping territories. Every skill owns a clearly defined domain (e.g., brand voice enforcer handles voice compliance, email drafter handles composition, content repurposer handles format transformation). No bleed.
• Rule 2: Aggressive negative boundaries.