La guía de Skills de 0 a 100 de Anthropic

Traducción al español de la guía oficial de Anthropic para construir Skills en Claude. Cubre desde los conceptos básicos hasta la combinación con MCP, con prompts y checklist incluidos.

Anthropic publicó "The Complete Guide to Building Skills for Claude": 32 páginas, 6 capítulos, la primera doc oficial que explica cómo pensar las skills como sistema y no como archivo suelto. Esta nota es la traducción al español, con las 10 secciones reorganizadas para flujo de lectura, los 8 prompts copy-paste para skill-creator y un checklist de 15 ítems para validar tu skill antes de publicarla.

Qué es una skill (la analogía del carpeta-con-instrucciones)

Anthropic abre la guía con la analogía más simple posible: una skill es una carpeta con instrucciones. Punto. No es código, no es un agente, no es un modelo fine-tuneado.

Cada skill vive en un directorio (.claude/skills/<nombre>/ o ~/.claude/skills/<nombre>/ para global). Dentro hay un archivo obligatorio — SKILL.md — y opcionalmente: scripts, templates, referencias, recursos. Claude lee el SKILL.md cuando detecta que la skill aplica al pedido del usuario, y ejecuta lo que ahí esté.

La analogía sirve para reseteár expectativas. Una skill no es magia; es texto que Claude lee. Si el texto está bien escrito, Claude actúa bien. Si está mal escrito, no hay modelo más grande que lo salve.

El frontmatter (lo que decide si tu skill se carga o no)

Cada SKILL.md arranca con un bloque YAML:

---
name: nombre-en-kebab-case
description: "Cuándo usar esta skill. Triggers, casos, exclusiones."
---

El description es lo más importante de toda la skill. Es el texto que Claude lee para decidir si la skill aplica al pedido del usuario o no. Si la description es vaga, Claude carga la skill cuando no toca o no la carga cuando sí toca.

Reglas de description que funcionan:

Empezar con "Use this skill when…" en inglés (o "Usa esta skill cuando…" en español).
Listar 3-5 triggers concretos (palabras o tipos de tarea que activan la skill).
Listar exclusiones explícitas ("Do NOT use for…").
Mantenerse bajo ~200 palabras.

Ejemplo malo:

description: "Skill para diseño web."

Ejemplo bueno:

description: "Usa esta skill cuando el usuario pida construir landing pages,
  hero sections, o sitios con animaciones premium. Triggers: 'landing',
  'hero', 'animado', 'magnético', 'shimmer'. NO usar para dashboards
  internos ni para emails."

Los 10 secciones de la guía (resumen accionable)

1. Por qué skills > prompts

Un prompt largo se diluye en contexto. Una skill se carga solo cuando aplica. Si vos siempre arrancás tus sesiones con "recordá que en este proyecto usamos X", convertí eso en skill. Liberás el contexto principal para la tarea real.

2. La estructura de archivos

.claude/skills/mi-skill/
  SKILL.md              ← obligatorio
  scripts/              ← opcional, código ejecutable
  references/           ← opcional, docs largas que Claude lee bajo demanda
  templates/            ← opcional, archivos base para copiar

Claude lee SKILL.md siempre que la skill se activa. Los otros directorios los lee solo cuando los necesita — vos los referenciás en el SKILL.md con instrucciones tipo "si el usuario quiere X, lee references/X.md".

3. La regla de oro: progressive disclosure

SKILL.md debe ser lo más corto posible. Todo detalle largo va a references/. Esto es porque cada vez que la skill se carga, el SKILL.md entero entra al contexto. Si pesa 8.000 tokens, te comiste 8.000 tokens incluso si la tarea solo necesitaba 800.

Regla práctica: SKILL.md < 2.000 palabras. Si crece más, fragmentalo.

4. Cuándo escribir código en la skill

Las skills pueden ejecutar scripts. Si tu skill hace algo determinista (parsear un archivo, validar JSON, correr tests), poné código en scripts/ y que la skill lo invoque. Es 10x más rápido y barato que pedirle a Claude que haga el mismo trabajo "razonando".

Ejemplo: una skill que valida links rotos en un sitio. La lógica de fetch + parse va en scripts/check-links.py. El SKILL.md solo dice "cuando el usuario pida verificar links, corre python scripts/check-links.py <url>".

5. Skills vs subagentes vs herramientas (la confusión común)

Las tres cosas suenan parecidas:

Skill — instrucciones que se cargan cuando aplican. Es texto.
Subagente — instancia de Claude separada que vos invocás para una sub-tarea. Es proceso.
Herramienta (tool/MCP) — función externa que Claude llama (web search, base de datos, API). Es interfaz.

Skills pueden referenciar herramientas y disparar subagentes. No al revés.

6. Skills globales vs por proyecto

Skills globales (~/.claude/skills/) están siempre disponibles. Skills por proyecto (<repo>/.claude/skills/) solo cuando abrís ese repo. Regla:

Skills generales (humanizar texto, escribir commits, formatear código) → global.
Skills específicas del proyecto (deploy a infra X, parsear logs propietarios) → proyecto.

7. Cómo distribuir tu skill

Tres caminos:

GitHub público — el usuario corre npx skills@latest add <usuario>/<repo>.
Anthropic Marketplace — submitís y queda listado oficial.
Manual — el usuario copia los archivos a su .claude/skills/.

El primero es el estándar de facto. La sintaxis de la CLI skills resuelve dependencias y versiones.

8. Versionado de skills

Tag con SemVer en tu repo. El CLI skills permite pinear versión:

npx skills@latest add usuario/skill@1.2.0

Si publicás breaking changes sin bump de mayor, vas a romper proyectos ajenos. SemVer no es opcional.

9. Combinar skills con MCP

Las skills le dan a Claude conocimiento (cómo hacer algo). MCP le da acceso (a qué herramientas). Una skill bien hecha referencia los servers MCP que necesita.

Ejemplo: una skill de "analizar dueño de un dominio" puede pedir como prerequisito tener el MCP de [WHOIS-tool] conectado.

10. El skill-creator (meta-skill)

Anthropic publica skill-creator, una skill que escribe skills. Le explicás qué querés que haga la skill, te entrevista, escribe el SKILL.md, sugiere scripts, valida frontmatter. Es la forma recomendada de arrancar.

8 prompts copy-paste para skill-creator

Pegá estos en Claude Code después de instalar skill-creator:

1. Brief inicial

Quiero una skill que [X]. Hacé las preguntas que necesites para entender 
triggers, exclusiones y formato de output.

2. Frontmatter

Generá el frontmatter YAML con name kebab-case y description que liste 
3 triggers y 2 exclusiones explícitas.

3. Estructura

Decidí si esto debería ser un SKILL.md plano o necesita scripts/ y 
references/. Justificá la decisión.

4. Scripts

Si la skill ejecuta lógica determinista, escribime los scripts en Python 
mínimos. Sin dependencias externas si se puede.

5. Testing

Listame 5 inputs de ejemplo y el output esperado de la skill para cada uno.

6. Edge cases

¿Qué pasa si el usuario invoca esta skill con input vacío, input enorme, 
o input de otro idioma? Definí comportamiento.

7. Distribución

Generá el README.md del repo con instrucciones de instalación, ejemplos 
y notas de versionado.

8. Validación final

Auditá la skill contra el checklist de 15 ítems (que voy a pegar abajo) y 
listame qué falta.

Checklist de 15 ítems pre-publicación

Antes de publicar tu skill, validá uno por uno:

☐ Frontmatter tiene name (kebab-case) y description clara.
☐ Description menciona 3+ triggers concretos.
☐ Description menciona al menos 1 exclusión explícita.
☐ SKILL.md < 2.000 palabras.
☐ Contenido largo movido a references/.
☐ Scripts (si hay) tienen shebang y permisos correctos.
☐ Scripts no tienen dependencias no documentadas.
☐ La skill no asume MCPs sin chequear primero.
☐ Hay al menos 3 ejemplos de uso en el README.
☐ El nombre no choca con skills oficiales de Anthropic.
☐ Versionado con SemVer en git tags.
☐ Licencia explícita (MIT recomendada).
☐ Probada en sesión nueva (no solo en la sesión donde la escribiste).
☐ Probada contra un trigger negativo (verificar que NO se carga cuando no toca).
☐ Documentadas las versiones de Claude Code/Claude Code SDK contra las que se probó.

Conclusión

Las skills no son tecnología compleja. Son la forma estándar de empaquetar conocimiento para que Claude lo aplique cuando corresponde, sin contaminar el contexto principal. La guía de Anthropic existe porque la mayoría de las skills de la comunidad están mal escritas — descriptions vagas, SKILL.md de 10.000 palabras, scripts hardcodeados.

Leé la guía completa una vez. Después usá este checklist como referencia rápida cada vez que vayas a publicar una skill. Vas a evitar el 80% de los errores que la comunidad sigue cometiendo.

Tags: skills, guia-oficial, anthropic, traduccion, claude-ai, skill-creator, frontmatter, principiante