📁 Anatomy: folder + SKILL.md
A skill is fundamentally a folder — not just one file. The folder name is the skill identifier; the file SKILL.md is the brain. Everything inside this folder serves the skill.
✓ Correct structure
- ✓
~/.claude/skills/minha-skill/SKILL.md - ✓kebab-case folder, SKILL.md at the root
- ✓Optional scripts/ and references/ subfolders
- ✓Each file has a clear responsibility
✗ Common errors
- ✗SKILL.md loose in ~/.claude/ without a folder
- ✗Folder with spaces or camelCase in its name
- ✗Everything mixed together in one giant SKILL.md
- ✗Scripts inline in markdown instead of in files
📄 YAML frontmatter
The frontmatter is the YAML block between the delimiters --- at the top of SKILL.md. This is where you declare the skill’s identity and how it should be activated.
---
name: formato-curso
description: |-
Template e padrões de design para criar páginas HTML
de cursos no formato INEMA.CLUB.
Use esta skill SEMPRE que o usuário pedir para criar,
editar ou revisar páginas HTML de curso — incluindo
index de trilhas, páginas de módulos, componentes.
SKIP: páginas web genéricas sem contexto de curso INEMA.CLUB.
---
# Formato Curso - INEMA.CLUB
# (corpo do SKILL.md começa aqui)💡 Tip: the name field = identifier
O name in the frontmatter must be identical to the folder name. This creates consistency: the folder formato-curso/ contains an SKILL.md with name: formato-curso. The agent uses this name to refer to it in logs and to invoke it via /formato-curso.
✓ Valid frontmatter
- ✓Delimiters
---at the beginning and end - ✓Indentation with 2 spaces (never tabs)
- ✓Fields
nameedescriptionpresent - ✓Clear, natural-language description
✗ Invalid frontmatter
- ✗YAML with tabs instead of spaces
- ✗Lack of
---of closing - ✗Empty or one-word description
- ✗Unrecognized extra fields (no effect)
📝 Markdown body
After the frontmatter, the body of SKILL.md is plain Markdown. This is where you define the skill's actual behavior: what to do, in what order, and what never to do.
# Nome da Skill
Parágrafo de contexto curto — o que esta skill faz.
## Referências
Sempre leia estes arquivos antes de agir:
1. **`references/MASTER.md`** — Templates completos
2. **`references/CHECKLIST.md`** — Verificação final
## Fluxo de Trabalho
1. Entender o que será criado
2. Ler referências relevantes
3. Criar seguindo os templates
4. Verificar com o checklist
## Hard Rules
- **NUNCA** usar seta ▶ em tópicos (usar número em círculo)
- **SEMPRE** incluir INEMA.CLUB em todas as páginas
- **JAMAIS** simplificar o nav para páginas internasRecommended sections in the body
Context / References
List of files the agent should read before acting. Pointer to the detailed documentation in references/.
Workflow
Numbered steps the agent executes in order. Includes confirmation gates before costly actions.
Critical Errors / Hard Rules
Unbreakable rules in ALL CAPS. What to NEVER do. Protects against the most costly and irreversible mistakes.
Quick reference tables
Decision tables, color mappings, component lists. Dense information in a scannable format.
💡 Ideal SKILL.md size
The SKILL.md is read in full each time it is activated. 50–150 lines is the sweet spot: dense enough to program behavior, concise enough to avoid wasting tokens. Larger content goes in references/.
🗂️ Where Skills Are Located
Skills can exist at two scopes: global (available in all projects) or local (restricted to the current project). The choice depends on how specific the skill is.
🗺️ Location map
Global (~/.claude/skills/)
Reusable utility skills for any project. Examples: formato-curso, n8n-code-python, claude-api.
└── skills/
├── formato-curso/
├── n8n-code-python/
└── ads-skill/
Local (.claude/skills/)
Skills specific to the current project. They don’t appear in other repositories. Example: a skill with the client’s business logic.
└── .claude/
└── skills/
└── projeto-especifico/
📊 Precedence rule
When a skill with the same name exists in both scopes, the local overrides global. This lets specific projects customize a global skill’s behavior without changing the original.
✓ Use global when
- ✓The skill is useful across multiple projects
- ✓Contains no sensitive customer data
- ✓It's a generic utility (formatter, analyzer)
✓ Use local when
- ✓Contains specific business logic
- ✓References the project’s private APIs
- ✓Must be versioned along with the code
🔍 How the Agent Discovers and Activates
The discovery and activation process happens in two phases: passive discovery (at startup) and active activation (when the message is relevant).
💡 Lazy loading: saving tokens
The agent does NOT read the full body of every skill in each session. Only the metadata (name + description) is injected. The full body is loaded only when the skill is activated. This keeps the context lightweight even with dozens of skills installed.
⚖️ Skill vs prompt vs command
Three tools, three purposes. Choosing the wrong one won’t break anything — but choosing the right one saves hours.
Comparison table
| Criterion | Skill | Prompt | Command |
|---|---|---|---|
| Persistence | Persistent (file) | Stateless | Saved in config |
| Complexity | Multi-step, scripts | One-off instruction | Prompt shortcut |
| Strict rules | Yes (hard rules) | No | No |
| Auxiliary files | Yes (scripts/, refs/) | No | No |
| Best for | Complex workflows | One-off tasks | Quick shortcuts |
💡 Golden rule
If you’re going to repeat the same set of steps more than 3 times, create a skill. If it’s a one-off and specific, use an inline prompt. If it’s a shortcut for a prompt you type frequently, create a slash command.
🧩 Module Summary
Next Module:
3.2 — Description and triggers: how to write the description field that makes the skill activate at the right time