1.1 Anatomy of a skill

Info
⏱ Duration: ~25 min · 🎯 Goal: understand what a skill is, how a SKILL.md is built, and why the description decides when Claude invokes it.

A skill is, verbatim, a “folder of instructions, scripts, and resources that Claude loads dynamically” to improve at specialized tasks. They work everywhere —regular chats, Projects, and Cowork— and activate automatically when the work calls for them. When a task needs several areas of expertise, Claude combines multiple skills on its own.

Step 1 — Recognize the anatomy

Every skill is a folder containing, at minimum, a SKILL.md file (the core). That file starts with YAML frontmatter holding the metadata:

  • name — human-friendly name, 64 characters max (e.g. QBR Review).
  • description — what it does and when to use it, 200 characters max. This is the critical field: Claude uses it to decide when to invoke the skill.
  • dependencies (optional) — e.g. python>=3.8, pandas>=1.5.0.

Step 2 — Understand progressive disclosure

Claude doesn’t load everything at once; it works in levels:

  1. Level 1 — metadata: reads name + description to decide whether to load the skill.
  2. Level 2 — body: loads the SKILL.md Markdown if needed.
  3. Level 3 — files: opens additional resources only when they apply.
Tip
That’s why a precise description is gold: if it states the when poorly, Claude won’t invoke the skill at the right moment.

Step 3 — Add resources and scripts

Inside the skill folder you can include:

  • Assets / references: files like REFERENCE.md, brand guides, logos, palettes, templates, schemas, or data (CSV/JSON). Reference them from SKILL.md so Claude knows when to open them.
  • Scripts: executable code (Python with pandas/numpy/matplotlib, JavaScript/Node.js) Claude runs when needed. When loading the skill it can install packages from PyPI/npm.

Step 4 — Package it correctly

To share a skill:

  • The folder name must match the skill’s name.
  • ZIP the folder: the skill folder must be at the root of the ZIP (not loose files, not nested in a subfolder).
my-skill.zip
└── my-skill/
    ├── SKILL.md
    └── resources/

Step 5 — Know where they live

Your installed skills appear in Customize > Skills (equivalent to Settings > Capabilities > Skills). On Claude Desktop and in Cowork, skills you add yourself are saved locally on your computer.

Warning
Skills require “Code execution and file creation” to be enabled. On Enterprise, the Owner must turn on both: “Code execution and file creation” and “Skills” in Organization settings > Skills.

✅ Checkpoint

You can explain in your own words what a SKILL.md contains, why description (≤200 chars) is the field that triggers invocation, and how a skill is packaged into a ZIP with the folder at the root.

Got it? — 2 questions

1. Micro-exercise — write two descriptions for your QBR skill: a vague one and a precise one. Predict which one makes Claude invoke the skill at the right moment and explain why. Vague example: “Helps with reports”. Precise example: “Generate a QBR with executive summary, KPIs vs target, risks, and decisions when the user asks for a quarterly business review”. The precise one wins: Claude only has the name + description to decide when to load the skill, so naming the task and its concrete trigger is what drives invocation.

2. How must the folder sit inside the ZIP when packaging? The skill folder (matching the skill’s name) must be at the root of the ZIP, not loose files nor nested in a subfolder.

Workshop Claude Avanzado · Grupo Salinas · v1.0 · 2026