Detailed content
📄 What exactly is a SKILL.md
An Agent Skill is, at its core, a Markdown text file called
SKILL.md. No compiled binary, no complex installation: it’s a
document you can open in a text editor and read from top to bottom. What makes it special isn’t the technology, but
the contract that it establishes—it teaches Claude to perform a specific task and says when that task applies.
🧬 The file’s two zones
Every SKILL.md is divided into two zones with very different roles:
- •Frontmatter (YAML): the business card —
nameedescription. This is what Claude reads to decide use the skill. - •Body (Markdown): the actual instructions — the “how to.” Only loaded then that the skill is chosen.
---
name: travel-itinerary
description: Generates an interactive HTML travel itinerary.
Use when the user wants to "plan a trip", "create an itinerary",
or types /travel.
---
# TravelWings — AI Travel Itinerary Generator
## Setup Flow
Before generating anything, ask the user the trip basics...
## Output Format
Generate a single self-contained HTML file...💡 Practical tip
If you know how to write a good README, you already know 80% of how to write a SKILL.md. The difference lies in two top fields — they aren't documentation; they're the trigger that makes Claude use the skill on its own.
🏷️ The name field: the identity
O name is the skill identifier. It seems like the silliest field in the file,
but it’s the stable key by which the skill is referenced — in commands, in
other skills, in logs. A good name is short, in kebab-case,
and says what the skill is at a glance.
✓ Names that work
- ✓
travel-itinerary— says exactly what it produces - ✓
vibe-coding— a memorable, specific term - ✓
n8n-workflow-reviewer— clear domain + action
✗ Names that get in the way
- ✗
helper— too generic; what does it help with? - ✗
my_skill_v2_final— noise, no meaning - ✗
SkillDeViagem— outside the kebab-case convention
📐 Conventions worth keeping
- kebab-case: all lowercase, words separated by hyphens.
- Stable: change the
namecan break references and commands — choose carefully and keep it. - Only: two
nameidentical ones create ambiguity about which one to load.
🎯 The description field: the trigger
If the name is the identity, the description é o
discovery brain. It’s the only part of the skill Claude reads when deciding whether
to use it. That’s why it can’t be a simple definition — it needs to say what
the skill does E when it should be used. This module only introduces the
idea; the entire Module 1.3 is dedicated to writing sharp descriptions.
⚖️ The “Does + When” formula
Compare the same skill described in two ways:
"Generates travel itineraries."
"Generates an interactive HTML travel itinerary. Use when the user wants to plan a trip, create an itinerary, or types /travel."
💡 Practical tip
Reread your description as if you were Claude seeing only this line, without the rest of the file. If you can't decide “does this skill apply to this request?”, Claude won't be able to either.
📝 The body: the "how to"
Below the frontmatter comes the skill body — Freeform Markdown where you write the execution steps. This is where the quality of the result is decided. A well-structured body usually has four recurring blocks, as we see in the real skills analyzed in this course.
Setup / discovery
"What to ask before producing"
The itinerary generator, for example, defines a Setup Flow required: before generating any HTML, Claude collects the destination, dates, source, and integrations. That’s what makes the output useful instead of generic.
Workflow / steps
"The execution sequence"
The order of actions. The frontend-fix skill, for example, defines steps with gates: confirm the workspace, create a branch, test live, and only then edit the code.
Hard rules / limits
"What never to do"
Nonnegotiable constraints—usually in uppercase or accompanied by warnings. They prevent Claude from skipping critical steps or taking destructive actions.
Output format
"How the result should be delivered"
The precise definition of the deliverable: a single self-contained HTML file, a report with fixed sections, or a JSON. Without this, each run produces a different format.
📊 What makes a good body
- Specific > generic: "generate a self-contained HTML file" takes precedence over "generate a good output".
- Principles at the end: good skills end with a list of principles that summarize the philosophy (“real data > placeholder”).
- Embedded examples: input/output snippets anchor behavior better than abstract prose.
🔍 How Claude Discovers the Skill
Here’s the detail that changes everything: Claude doesn’t read the body of every skill all
the time. Imagine 50 installed skills, each with hundreds of lines — loading everything with every message would be
impractical. Instead, it keeps a lightweight index: only the
name + a description for each skill. This is the index that
the user's request is matched against.
🗂️ The description index
Think of a library catalog: you don't read every book to find one—you read the cards. The description is the skill’s profile.
- •The user’s request is compared against the available descriptions.
- •The skill whose description best matches the intent is the candidate.
- •Only then does the full body of that skill enter the context.
travel-itinerary → "plan a trip, create an itinerary, /travel"
vibe-coding → "fix CSS/layout live in the browser before editing"
n8n-reviewer → "review an n8n automation as a senior engineer"
rag-architect → "design the right RAG before writing code"
... → (só name + description, nunca o corpo inteiro)💡 Practical tip
This mechanic explains a common frustration: "I created the perfect skill and Claude never uses it." Almost always, the body is great — but the description doesn’t say when to trigger. Claude never gets to read the brilliant body because the description didn’t convince it.
⚡ How Claude triggers the skill
Discovery means recognizing that the skill applies; trigger is effectively loading the body and following its instructions. There are two ways this can happen, and understanding the difference avoids a lot of confusion.
✓ Automatic trigger
Claude reads the request, sees that it matches a description, and uses the skill on its own.
- ✓Triggered by intent: "plan my trip to Tokyo"
- ✓The ideal: the user doesn’t even need to know the skill exists
- ✓Depends 100% on a good description
↳ Explicit invocation
The user calls the skill by name or with a slash command.
- →Triggered by the command:
/travel - →Useful when the user knows exactly what they want
- →Works even with a weak description
⚠️ The mistake to avoid
Relying only on explicit invocation wastes half the power of skills. If the skill never triggers on its own, it becomes a manual command—and the user has to remember it. The goal of a well-made skill is to disappear: activate at the right time without anyone asking.
💡 Practical tip
Always test both paths. Ask for the task in natural language (without mentioning the skill) and see if it triggers. Then invoke it by name. If only the second one works, your description needs work—and that's exactly what Module 1.3 teaches you to fix.
🧰 Copyable prompts
Use these prompts with Claude to put the module’s content into practice.
Abra um SKILL.md qualquer que você tenha acesso e me explique,
linha a linha: qual é o frontmatter, o que cada campo (name,
description) faz, e onde começa o corpo de instruções.Aqui está a description da minha skill: "<cole aqui>".
Lendo SÓ essa linha, sem o corpo, você saberia em quais pedidos
de usuário disparar esta skill? Liste 3 pedidos que disparariam
e 3 que NÃO disparariam.Vou descrever uma tarefa que faço sempre. Me ajude a separar:
(1) qual seria o name e a description (o gatilho), e
(2) o que vai no corpo (workflow, regras, formato de saída).
A tarefa é: <descreva>.📤 Sample Output
One SKILL.md minimal, but complete and valid — exactly the skeleton you'll expand in the next modules.
---
name: changelog-writer
description: Writes a clean CHANGELOG entry from a list of git
commits. Use when the user asks to "write a changelog",
"summarize these commits", or "prep release notes".
---
# Changelog Writer
## Workflow
1. Ask for the version number and the commit list (or read it).
2. Group commits into: Added, Changed, Fixed, Removed.
3. Rewrite each line in plain, user-facing language.
## Rules
- Never invent changes that aren't in the commits.
- Keep each entry to a single line.
## Output Format
Markdown under a `## [version] - YYYY-MM-DD` header,
one section per group, bullets per change.✏️ Practical exercises
1. Dissect a SKILL.md
Choose any skill you know and mark, with a color marker, where the frontmatter ends and the body begins. Identify the body's four sections (setup, workflow, rules, output)—note which one is missing.
2. Rewrite a weak description
Take the description "Generates reports." and rewrite it in the "Does + When" format, adding at least two specific triggers a user might say.
3. Create a runnable SKILL.md ⭐
Write, from scratch, a SKILL.md complete for a repetitive task of yours (e.g., "summarize meetings," "standardize commit names"). It should have: frontmatter with name + description in the “Does + When” format, with a body that includes a workflow, at least one hard rule, and an output format. Then ask Claude to run it with a test input and see whether the result follows the defined format.
🧬 Module summary
name (identity) and description (trigger) determine when it fires.Next module:
1.2 — Progressive disclosure & structure