Cómo escribir una Claude skill (estructura del SKILL.md + ejemplos reales)

Así se escribe una Claude skill en una sola frase: crea una carpeta, mete dentro un archivo SKILL.md y escribe una descripción lo bastante buena como para que Claude sepa cuándo usarla. Ese es todo el mecanismo. La parte que de verdad decide si tu skill funciona tiene 1.024 caracteres, y es el campo description que Anthropic usa para elegir tu skill entre las más de 100 que podrían estar cargadas. Nosotros tenemos 25 skills en producción en la biblioteca de la comunidad de Techsy, y las que fallan casi nunca fallan por las instrucciones. Fallan en esa única línea.

Resumen rápido

Para escribir una Claude skill: (1) crea una carpeta con el nombre de la skill, (2) añade un SKILL.md con frontmatter YAML (name y description) más instrucciones en Markdown, (3) escribe la descripción en tercera persona con palabras clave de activación claras, (4) mantén el cuerpo por debajo de 500 líneas y traslada el detalle a archivos de referencia, y (5) pruébala con tareas reales antes de confiar en ella.

Qué es en realidad una Claude skill

Una skill es una carpeta con un archivo SKILL.md en la raíz. No hace falta nada más. Ese archivo contiene dos cosas: metadatos que le dicen a Claude cuándo usar la skill, e instrucciones que le dicen cómo hacer la tarea una vez activada.

La razón por la que esto sale barato es un modelo de carga que Anthropic llama progressive disclosure (divulgación progresiva). Al arrancar, Claude solo lee el name y la description de cada skill instalada, unos 100 tokens cada una. Lee el SKILL.md completo solo cuando tu descripción encaja con la tarea que tiene delante, y lee los archivos de referencia incluidos solo cuando las instrucciones apuntan a ellos. Así puedes publicar una skill grande y detallada sin pagar el coste en cada solicitud. Puedes ver un catálogo real de skills en nuestra biblioteca de Skills.

El esqueleto de SKILL.md que puedes copiar

Toda skill parte de la misma forma. Esta es la versión mínima que funciona:

---
name: reviewing-pull-requests
description: Reviews pull request diffs for bugs, security issues, and style. Use when the user asks for a code review, mentions a PR, or shares a diff.
---

# Reviewing Pull Requests

1. Read the diff and summarize what changed.
2. Flag likely bugs and edge cases, most severe first.
3. Check for hardcoded secrets and injection risks.
4. Note style issues only if they hurt readability.
5. End with a short verdict: approve, or request changes.

Dos marcadores --- envuelven el frontmatter. Debajo, el cuerpo es Markdown normal. En nuestras 25 skills, la estructura que ha sobrevivido al uso real es aburrida y consistente: un título de una línea, luego un procedimiento numerado o con viñetas, y después las plantillas o ejemplos que hagan falta. Cuando nos pusimos creativos con la prosa, Claude la leyó por encima. Cuando escribimos pasos, los siguió. Si quieres estudiar skills terminadas, las 25 skills del sitio de la comunidad de Techsy son archivos SKILL.md legibles que puedes abrir y copiar.

Reglas del frontmatter: name y description

El frontmatter tiene exactamente dos campos obligatorios, y ambos tienen límites estrictos que vale la pena memorizar porque las herramientas de Anthropic los validan.

Una convención útil de la guía de buenas prácticas de Anthropic: nombra las skills en gerundio, como processing-pdfs, writing-documentation o analyzing-spreadsheets. Se lee bien en una lista y describe la actividad en lugar de un sustantivo vago como helper o utils. Mantén el name igual al nombre de la carpeta para que nunca se desincronicen. Para las reglas de validación completas, la guía de buenas prácticas de Anthropic es la fuente definitiva.

Escribe una descripción que realmente active la skill

Esta es la sección que la mayoría de los tutoriales se saltan, y es la que decide si tu trabajo se llega a usar. La descripción se inyecta en el system prompt, y Claude la lee para decidir si carga tu skill o no. Un cuerpo perfecto detrás de una descripción vaga es una skill que nunca se ejecuta.

Tres reglas marcan la diferencia:

Escribe en tercera persona. La descripción describe la skill, no a ti ni al usuario. Escribirla en primera o segunda persona confunde la selección.

# Good
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDFs or when the user mentions forms or document extraction.

# Avoid
description: I can help you work with your PDF files whenever you need.

Indica el qué y el cuándo. "Procesa datos" no le dice nada a Claude sobre qué tarea encaja. Nombra la capacidad concreta y los disparadores concretos.

Incluye las palabras que un usuario realmente escribiría. Si la gente dice "PR", "diff" o "code review", pon esos términos en la descripción. Claude hace el match con ellos. Es el cambio de mayor impacto que puedes hacer en una skill, y cuesta una sola línea.

Divulgación progresiva y estructura de archivos

Cuando una skill crece más allá de una o dos pantallas, la estructura empieza a importar. La guía de Anthropic es concreta: mantén el cuerpo del SKILL.md por debajo de 500 líneas, y traslada todo lo demás a archivos de referencia independientes enlazados desde el cuerpo. Esos archivos no cuestan ni un token hasta que Claude los lee de verdad.

Una skill que ha madurado tiene este aspecto:

reviewing-pull-requests/
├── SKILL.md            # overview + the core procedure
├── security.md         # detailed security checklist (read when needed)
├── style-guide.md      # house style rules (read when needed)
└── scripts/
    └── diff_stats.py    # executed, never loaded into context

Dos reglas mantienen esto funcionando. Primero, mantén las referencias a un solo nivel de profundidad: enlaza cada archivo directamente desde SKILL.md, nunca de archivo a archivo a archivo, porque Claude puede previsualizar archivos muy anidados con una lectura parcial y perderse contenido. Segundo, dale a cualquier archivo de referencia de más de 100 líneas una tabla de contenidos al principio, para que una lectura parcial siga mostrando el alcance completo. El artículo técnico de Anthropic sobre Agent Skills explica la arquitectura detrás de esto si quieres el modelo más profundo. Cuando tu skill empieza a orquestar herramientas, nuestro catálogo de MCP es un buen complemento para conectar servidores.

Grados de libertad (y cuándo añadir scripts)

No todas las instrucciones deben ser igual de estrictas. Ajusta cuánto scripteas un paso al grado de fragilidad de ese paso.

Cuando un paso es determinista, publica un script en lugar de pedirle a Claude que genere código cada vez. Un script incluido es más fiable, ahorra tokens y se mantiene consistente entre ejecuciones. Dos hábitos mantienen los scripts honestos: gestiona los errores dentro del propio script en lugar de delegarlos a Claude, y justifica cada constante para que no queden números mágicos sin explicar. Aquí es también donde las skills se diferencian de los subagentes, que tienen su propia lista de herramientas permitidas y su propio system prompt; nuestra biblioteca de automatizaciones reúne ejemplos de subagentes, y puedes comparar los dos enfoques en la página de automatizaciones de IA de Techsy.

Pruébala: desarrollo de skills guiado por evaluaciones

Los mejores autores de skills escriben pruebas antes de escribir documentación. Anthropic recomienda construir primero las evaluaciones: ejecuta Claude en tres tareas representativas sin la skill, anota exactamente dónde falla, y luego escribe solo la instrucción necesaria para corregir esos fallos. Así resuelves problemas reales en lugar de documentar problemas imaginados.

Un ciclo práctico:

1. Elige tres tareas reales que la skill debería resolver.
2. Ejecútalas sin ninguna skill cargada y anota qué falla.
3. Escribe el SKILL.md mínimo que corrige esos fallos.
4. Vuelve a probar con la skill cargada, idealmente en Claude Haiku, Sonnet y Opus, porque una skill que guía bien a Opus puede quedarse corta con Haiku.
5. Observa cómo Claude navega por los archivos. Si ignora una referencia, tu enlace no es lo bastante visible. Si relee el mismo archivo constantemente, ese contenido debería estar en SKILL.md.

Para un tutorial práctico que construye una skill de principio a fin, nuestro sitio hermano tiene un tutorial completo de Claude Skills; combina bien con las reglas de autoría de aquí. También puedes comparar tu skill con nuestras listas de verificación para empresas.

Errores comunes que matan una skill

La mayoría de las skills rotas fallan por una lista corta de razones:

• Una descripción escrita para humanos. El texto de marketing se lee bien y no activa nada. Escribe para el modelo: capacidades y disparadores.
• Demasiadas opciones. "Usa pypdf, o pdfplumber, o PyMuPDF, o..." hace que Claude dude. Da una opción por defecto con una única vía de escape.
• Referencias muy anidadas. Los archivos que enlazan a archivos que enlazan a otros archivos se leen solo parcialmente. Mantén todo a un salto de SKILL.md.
• Instrucciones sensibles al tiempo. "Antes de agosto, haz X" caduca año tras año. Pon las indicaciones obsoletas en una nota plegada de "patrones antiguos" en su lugar.
• Rutas al estilo Windows. Usa siempre barras diagonales; las barras invertidas fallan en entornos Unix.
• Terminología inconsistente. Elige una palabra para cada cosa ("campo", no "campo/casilla/elemento/control") y úsala en todo el documento.

El patrón detrás de estos seis errores: una skill es un conjunto de instrucciones para un lector muy capaz que no tiene paciencia con la ambigüedad. Di la cosa específica, una sola vez.

Sobre el autor

Mert Batur Gurbuz es cofundador de Techsy, University of Birmingham. Junto con el equipo de Techsy, construye agentes de IA, sistemas de automatización y pipelines de voz y SDR para clientes B2B, y mantiene la biblioteca de 25 skills que se menciona a lo largo de esta guía. Conecta en LinkedIn. Más guías para builders en el blog de TECHSY.community.

Preguntas frecuentes

¿Dónde viven los archivos de las Claude skills?

Una skill es una carpeta que contiene un archivo SKILL.md. En Claude Code, las skills personales van en ~/.claude/skills/{skill-name}/ y las skills de proyecto en .claude/skills/{skill-name}/. En la API y en claude.ai, subes la carpeta de la skill directamente. El nombre de la carpeta debería coincidir con el campo name del frontmatter.

¿El nombre de la skill tiene que coincidir con el nombre de la carpeta?

Sí, mantenlos idénticos. El campo name debe tener 64 caracteres o menos, usar solo minúsculas, números y guiones, y evitar las palabras reservadas "anthropic" y "claude". Que coincida con el nombre de la carpeta evita desincronizaciones y hace que la skill sea fácil de referenciar en conversaciones y documentación.

¿Cuánto puede ocupar un SKILL.md?

Mantén el cuerpo del SKILL.md por debajo de 500 líneas para un rendimiento fiable. No hay un límite estricto de tokens, porque los archivos de referencia y los scripts no cuestan nada hasta que se leen, pero un archivo principal sobrecargado compite con todo lo demás en la ventana de contexto. Cuando te acerques a las 500 líneas, divide el detalle en archivos de referencia enlazados directamente desde SKILL.md.

¿Por qué mi skill no se activa?

Casi siempre es la descripción. Claude selecciona skills haciendo match entre la tarea y el campo description, así que si la tuya es vaga o está escrita en primera persona, nunca se activa. Reescríbela en tercera persona, indica qué hace la skill y cuándo usarla, e incluye las palabras exactas que un usuario escribiría para esa tarea.

¿Cuál es la diferencia entre una skill, un subagente y un servidor MCP?

Una skill son instrucciones empaquetadas que Claude carga cuando son relevantes. Un subagente es un agente independiente con su propia lista de herramientas permitidas y su propio system prompt, que gestiona una tarea delegada. Un servidor MCP expone herramientas y datos externos a través del Model Context Protocol. Las skills describen cómo hacer el trabajo; los servidores MCP proporcionan sobre qué actuar.

¿Una Claude skill puede ejecutar código?

Sí. Las skills pueden incluir scripts ejecutables que Claude ejecuta como herramientas en lugar de leerlos en el contexto, lo cual es más barato y más fiable para trabajo determinista como validación o conversión de archivos. Deja la intención explícita en tus instrucciones: di "ejecuta este script" para ejecución, o "consulta este script" cuando sea material de referencia.

¿Las skills funcionan tanto en la API como en claude.ai?

Sí, aunque el runtime es distinto. En claude.ai, el entorno de ejecución de código puede instalar paquetes de npm y PyPI, mientras que la API de Claude no tiene acceso a red ni instalación de paquetes en tiempo de ejecución. Enumera los paquetes necesarios en tu SKILL.md y confirma que están disponibles en el entorno de destino antes de depender de ellos.

¿Cuántas skills puede tener Claude cargadas a la vez?

Muchas, porque al arrancar solo el name y la description de cada skill ocupan contexto, unos 100 tokens cada una. Por eso la descripción importa tanto: Claude puede estar eligiendo entre más de 100 skills, y una descripción precisa es lo que le permite elegir la tuya correctamente. El cuerpo completo solo se carga una vez que la skill ha sido seleccionada.