Tutorial oficial de Agent Skills de Anthropic: Notas completas del curso de 6 lecciones

Anthropic finalmente ha lanzado un video tutorial oficial sobre Agent Skills, compuesto por 6 lecciones con una duración total de 22 minutos. Cubre todo el ciclo de vida de las Skills, desde qué son hasta cómo crearlas, configurar archivos múltiples, distinguirlas de otras funciones, compartirlas y solucionar problemas.

El mayor valor de este tutorial no es solo enseñarte cómo escribir una Skill, sino explicar la filosofía de diseño y los mecanismos subyacentes de las Skills. Muchos de los problemas que la gente encuentra al usar Skills provienen de una comprensión insuficiente de estos mecanismos.

¿Qué Problemas Resuelven las Skills?

Cada vez que le explicas los estándares de codificación de tu equipo a Claude, te estás repitiendo. En cada revisión de PR, tienes que volver a describir cómo quieres que se organice la retroalimentación. En cada mensaje de commit, tienes que recordarle a Claude tu formato preferido.

Las Skills están diseñadas para eliminar esta repetición. Una Skill es un archivo Markdown que le enseña a Claude cómo hacer algo una vez, y Claude aplica automáticamente ese conocimiento en situaciones relevantes.

Más precisamente, una Agent Skill es una carpeta que contiene instrucciones, scripts y recursos. Claude puede descubrir y utilizar automáticamente estos elementos para completar el trabajo de manera más precisa y eficiente.

El mecanismo central es el campo description. Cuando Claude se inicia, carga los nombres y descripciones de todas las Skills. Cuando haces una solicitud, Claude realiza una coincidencia semántica entre tu solicitud y las descripciones de todas las Skills disponibles para encontrar y activar la que coincide. Solo al activarse se carga el contenido completo de la Skill en la ventana de contexto.

Esto es fundamentalmente diferente de claude.md. El contenido de claude.md se carga en cada conversación, sin importar lo que estés haciendo. Una Skill solo se carga cuando es necesaria; tu lista de verificación de revisión de PR no necesita estar en el contexto mientras depuras, apareciendo solo cuando realmente solicitas una revisión.

¿Cuándo deberías usar una Skill? Si te encuentras explicando repetidamente lo mismo a Claude, esa es una Skill que está esperando ser desarrollada.

Creando tu Primera Skill desde Cero

Crear una Skill solo requiere dos pasos: crear un directorio y escribir un archivo.

Paso uno: Crea un directorio con el nombre de la Skill en ~/.claude/skills/. Colocarlo aquí significa que es una Skill a nivel personal, disponible en todos los proyectos.

Paso dos: Crea un archivo SKILL.md en el directorio. El archivo se divide en dos partes, separadas por tres guiones. La parte superior son metadatos YAML que contienen name y description. La parte inferior contiene las instrucciones específicas para que Claude las siga.

Cuando Claude Code se inicia, escanea cuatro ubicaciones en busca de Skills: rutas empresariales, directorio de Skills personales, directorio de Skills del proyecto y plugins instalados. Solo carga el nombre y la descripción de cada Skill, no el contenido completo.

Cuando envías una solicitud, Claude compara la solicitud con todas las descripciones de Skills. Si la intención coincide, primero te pedirá confirmación para cargar la Skill. Solo después de la confirmación lee el archivo completo y ejecuta las instrucciones. Este paso de confirmación te mantiene al tanto del contexto que Claude está utilizando.

Si existen Skills con el mismo nombre, la prioridad de mayor a menor es: Nivel empresarial (managed-settings.json), Nivel personal (~/.claude/skills), Nivel de proyecto (project/.claude/skills) y Nivel de plugin (project/.claude-plugins/skills).

Esto significa que una empresa puede imponer estándares a través de Skills de nivel empresarial, mientras permite que las personas personalicen mediante Skills con nombres diferentes. Si tu empresa tiene una Skill de revisión de código empresarial, puedes crear una Skill personal llamada front-end-pr-review para complementarla, no sobrescribirla.

Configuración Avanzada: Campos de Metadatos y Divulgación Progresiva

Las Skills básicas solo necesitan name y description, pero varias configuraciones avanzadas pueden hacer que las Skills sean más potentes.

El campo allowed-tools puede limitar qué herramientas puede usar Claude cuando la Skill está activa. Por ejemplo, si tienes una Skill de análisis de solo lectura, puedes prohibir la edición, escritura y comandos Bash. Si se omite este campo, la Skill no impone restricciones y Claude usa el modelo de permisos normal.

El campo model puede especificar qué versión del modelo Claude usar.

La forma en que se escribe la description determina directamente si una Skill se puede activar correctamente. Una buena descripción debe responder dos preguntas: ¿Qué hace esta Skill? ¿Cuándo debería Claude usarla? Si una Skill no se activa, agrega más palabras clave que coincidan con la redacción de tus solicitudes.

El concepto avanzado más importante es la divulgación progresiva. Las Skills comparten la ventana de contexto con tu conversación. Si metes todo en un SKILL.md de 20,000 líneas, consumirá un espacio de contexto masivo.

El enfoque correcto es: coloca las instrucciones esenciales en SKILL.md y los materiales de referencia detallados en archivos separados, que Claude lee solo cuando es necesario. La estructura de directorios recomendada para estándares abiertos es: una carpeta scripts para código ejecutable, references para documentos de referencia y resources para archivos de datos como imágenes y plantillas. Usa enlaces en SKILL.md para hacer referencia a estos archivos.

Regla clave: SKILL.md no debe exceder las 500 líneas. Si lo hace, debe dividirse. Los scripts se pueden ejecutar directamente sin cargar su contenido en el contexto; solo la salida consume tokens. Por lo tanto, dile a Claude que ejecute el script en lugar de leerlo. Esto es particularmente útil para la validación del entorno y la transformación de datos, ya que el código de script probado es más confiable que la generación sobre la marcha.

Diferencias entre Skills y Otras Funciones de Claude Code

Skills vs. claude.md: claude.md siempre se carga en cada conversación para estándares y reglas del proyecto que siempre aplican, como "Este proyecto usa el modo estricto de TypeScript". Las Skills se cargan bajo demanda, activándose solo cuando Claude coincide con una solicitud.

Skills vs. Sub Agents: Las Skills agregan conocimiento a la conversación actual; una vez activadas, las instrucciones se agregan al contexto existente. Los Sub Agents se ejecutan en un contexto independiente, completando tareas y enviando resultados por separado, completamente aislados de la conversación principal.

Skills vs. Hooks: Los Hooks están impulsados por eventos, activándose cuando ocurren eventos específicos, como que Claude ejecute un Linter cada vez que se guarda un archivo. Las Skills están impulsadas por solicitudes, activándose según las preguntas que hagas.

Skills vs. MCP: MCP proporciona conexiones a herramientas externas, permitiendo que Claude llame a servicios como Gmail o Notion. Las Skills proporcionan conocimiento y flujos de trabajo, diciéndole a Claude cómo usar esas herramientas para completar tareas específicas.

Resumen en una frase: claude.md contiene instrucciones siempre activas, las Skills contienen experiencia de coincidencia automática, los Sub Agents ejecutan tareas delegadas en contextos aislados, los Hooks responden a eventos y MCP se conecta a herramientas externas. Se pueden usar en combinación.

Compartiendo Skills: De Individuos a Equipos y Organizaciones

El valor de las Skills radica en compartirlas. Una Skill de revisión de PR que solo usas tú es útil, pero una Skill compartida por el equipo puede estandarizar las revisiones de código y proporcionar una experiencia consistente.

Tres formas de compartir:

La primera es el directorio del proyecto. Confirma la Skill en el directorio .claude/skills del repositorio de código. Cualquiera que clone el repositorio obtiene automáticamente estas Skills sin instalación adicional. Las actualizaciones se reciben en el próximo pull. Esto es adecuado para estándares de codificación del equipo y flujos de trabajo específicos del proyecto.

La segunda son los plugins. Piensa en los plugins como una forma de distribuir Skills entre proyectos. Una vez subidos a una tienda de aplicaciones, otros usuarios pueden descargarlos e instalarlos. Si tu Skill es genérica y no específica de un proyecto, esta es la mejor opción para los miembros de la comunidad.

La tercera es la implementación empresarial. Los administradores envían Skills a toda la organización a través de configuraciones gestionadas. Las Skills de nivel empresarial tienen la prioridad más alta y sobrescribirán las Skills personales y del proyecto con el mismo nombre. Esto se utiliza para estándares obligatorios, requisitos de seguridad y flujos de trabajo de cumplimiento.

Una nota importante: Los Sub Agents no heredan automáticamente tus Skills. Cuando delegas una tarea a un sub-agente, comienza con un contexto nuevo. Los agentes integrados (Explorer, Plan, Verify) no pueden acceder a las Skills en absoluto; solo los sub-agentes personalizados que defines pueden usarlas, y deben estar listados explícitamente en agent.md.

Para crear un sub-agente personalizado con Skills, crea un archivo agent.md en el directorio .claude/agents y agrega un campo skills que liste los nombres de las Skills requeridas. Solo lista las Skills que sean siempre relevantes para el objetivo del sub-agente, ya que estas Skills se cargarán cuando el sub-agente se inicie.

Guía de Solución de Problemas: Seis Razones por las que Fallan las Skills y sus Soluciones

Los problemas con las Skills generalmente se dividen en seis categorías:

1. La Skill no se activa: La razón es casi siempre una description mal escrita. Claude usa coincidencia semántica; tu solicitud debe alinearse con el significado de la descripción. Si no hay suficiente superposición, no coincidirá. Solución: Compara la descripción con la redacción de tu solicitud y agrega frases de activación que los usuarios realmente digan, como "ayúdame a analizar", "por qué es lento" o "aceléralo".

1. La Skill no se carga: Verifica las rutas y los nombres de archivo. SKILL.md debe estar dentro de un directorio con nombre, no directamente en la raíz de skills. El nombre del archivo debe ser exactamente SKILL.md en mayúsculas. Ejecuta claude --debug para ver los errores de carga.

1. Claude usa la Skill incorrecta: Esto significa que tienes múltiples Skills con descripciones demasiado similares, lo que dificulta que Claude las distinga. Solución: Haz que cada descripción sea lo más específica posible para ayudar a Claude a decidir cuándo usar cuál.

1. La Skill personal está siendo ignorada: Una Skill de mayor prioridad (como una empresarial) con el mismo nombre podría estar sobrescribiéndola. Verifica los cuatro niveles de prioridad. Solución: Cambia el nombre de tu Skill a algo más único.

1. Plugin instalado pero la Skill no es visible: Limpia el caché con rm ~/.claude/plugins/cache, reinicia Claude Code y vuelve a instalar. Si aún no funciona, la estructura de directorios del plugin podría estar incorrecta; usa la herramienta de validación skills-ref validate para verificarlo.

1. Skill cargada pero falla durante la ejecución: Si la Skill usa paquetes externos, asegúrate de que estén instalados. Agrega información de dependencias a la descripción de la Skill.

Anthropic también proporciona una herramienta de validación llamada skills-ref para verificar si la estructura de archivos y la sintaxis YAML de la Skill son correctas. Se recomienda instalarla a través de uv para el método más rápido.