Claude Skills: La guía de 32 páginas de Anthropic, decodificada
Llevo ocho meses escribiendo las mismas instrucciones para Claude. Cada lunes por la mañana, el mismo prompt de planificación de sprint. Cada llamada con clientes, la misma plantilla de notas de reunión. Cada despliegue, la misma checklist pegada en la ventana de chat como una especie de Día de la Marmota digital.
Entonces Anthropic lanzó una guía de 32 páginas sobre algo llamado Claude Skills — y en una sola tarde, borré todos los prompts que tenía guardados.
No archivados. Borrados. Porque una vez que entiendes lo que realmente son los Skills, volver a copiar y pegar prompts se siente como volver a escribir cartas después de descubrir el correo electrónico. El concepto es engañosamente simple: le enseñas algo a Claude una vez, dentro de una carpeta con un archivo markdown y algunos scripts opcionales, y simplemente sabe cómo hacer eso de ahí en adelante. Sin volver a explicar. Sin "aquí está mi guía de estilo otra vez." Sin "recuerda, usamos Tailwind, no Bootstrap."
Un archivo SKILL.md. Algo de YAML al inicio. Listo.
Pero — y esto es lo que quiero profundizar — la guía en sí es tanto brillante como frustrante. Brillante porque el framework que plantea es genuinamente poderoso. Frustrante porque los detalles de implementación más importantes están enterrados bajo capas de documentación pulida, y algunas de las lecciones más difíciles de aprender sobre cómo hacer que los Skills realmente funcionen se mencionan de pasada o no se mencionan en absoluto.
Pasé tres días leyendo la guía, construyendo Skills, rompiendo Skills y reconstruyéndolos. Lo que sigue es todo lo que desearía que alguien me hubiera dicho antes de empezar — las partes que Anthropic clavó, las partes que pasaron por alto, y los cinco patrones que realmente importan una vez que eliminas el lenguaje de marketing.
El concepto que hace que todo encaje
Este es el modelo mental que finalmente hizo que Claude Skills tuviera sentido para mí, y no es el que Anthropic presenta primero.
Probablemente ya conozcas MCP — el Model Context Protocol que permite a Claude conectarse con herramientas externas como Notion, Linear, Figma, GitHub, Slack, y básicamente cualquier cosa con una API. MCP se trata de acceso. Le da a Claude las llaves de tus herramientas. Abrir la puerta, entrar, mirar alrededor.
Los Skills son diferentes. Los Skills se tratan de criterio.
Piénsalo de esta manera. Contratas a un nuevo desarrollador y le das acceso de administrador a todo tu stack — tu herramienta de gestión de proyectos, tu pipeline de CI/CD, tu sistema de diseño, tus canales de comunicación. Técnicamente puede tocar todo. Pero no conoce las convenciones de tu equipo. No sabe que el cálculo de velocidad de sprint excluye los bugs de menos de dos story points. No sabe que las entregas de diseño siempre pasan por un flujo específico de Figma-a-Linear con anotaciones de accesibilidad obligatorias. No sabe que los anuncios de despliegue siguen un formato particular en un canal de Slack específico.
Acceso sin criterio crea caos. MCP le da acceso a Claude. Los Skills le dan criterio a Claude.
Esa distinción es toda la guía en una sola frase. Todo lo demás — el frontmatter YAML, la estructura de carpetas, los cinco patrones, los consejos de depuración — son detalles de implementación que cuelgan de esa idea central.
Una vez que esto hizo clic para mí, dejé de pensar en los Skills como "prompts sofisticados" y empecé a pensar en ellos como conocimiento institucional capturado en código. Y ese replanteamiento cambió cómo construí cada uno de ellos.
La pregunta práctica, por supuesto, es cómo capturas ese conocimiento en un formato que Claude pueda usar. La guía dedica muchas páginas a esto, y parte es genuinamente útil. Pero hay un atajo que nadie te cuenta, y llegaré a él después de repasar la mecánica.
Qué hay realmente en la carpeta — Y qué hace cada parte
Un Claude Skill vive en una carpeta. Como mínimo, esa carpeta contiene un archivo: SKILL.md. Eso es todo. Un archivo markdown, y tienes un Skill funcional.
En la parte superior de ese archivo markdown está el frontmatter YAML — el bloque de metadatos entre guiones triples que le dice a Claude qué es este Skill, qué hace y, críticamente, cuándo activarlo. El resto del archivo contiene las instrucciones reales: cómo realizar la tarea, qué estándares seguir, qué herramientas usar y qué errores evitar.
Opcionalmente, puedes agregar scripts, documentos de referencia y plantillas a la carpeta. Un PDF de guía de estilo. Un script bash que ejecuta linting. Un esquema JSON para las respuestas de tu API. Claude los referenciará al ejecutar el Skill.
Aquí hay un ejemplo mínimo — un Skill que genera informes de estado semanales para mis proyectos:
---
name: weekly-status-report
description: >
Generates a formatted weekly status report by pulling data
from Linear and GitHub. Trigger when user asks for a status
report, weekly update, or progress summary.
---
## Generador de Informes de Estado Semanales
### Qué hace este Skill
Produce un informe de estado semanal conciso que cubre el trabajo completado,
los elementos en progreso, los bloqueadores y las prioridades de la próxima semana.
### Fuentes de datos
1. Obtener los issues completados de Linear para el sprint actual
2. Obtener los PRs fusionados de GitHub de los últimos 7 días
3. Obtener los bloqueadores abiertos etiquetados con "blocked" en Linear
### Formato del informe
- **Resumen** (2-3 frases, mayores logros y riesgos)
- **Completado** (lista con viñetas con referencias a tickets)
- **En progreso** (lista con viñetas con estimaciones de porcentaje)
- **Bloqueadores** (lista con viñetas con responsable y antigüedad en días)
- **Próxima semana** (top 3 prioridades)
### Reglas de estilo
- Sin jerga — esto va dirigido a stakeholders, no a ingenieros
- Comenzar cada sección con el elemento de mayor impacto
- Los bloqueadores deben incluir quién es responsable de la resolución
- Mantener la longitud total bajo 500 palabras
Ese es un Skill completo. Cuando le pido a Claude "dame la actualización de estado de esta semana", reconoce el trigger de la descripción, carga el Skill, se conecta a Linear y GitHub a través de MCP, y produce un informe siguiendo mi formato y reglas de estilo exactos.
Sin ingeniería de prompts. Sin recordar dónde guardé la plantilla. El conocimiento vive en el Skill, y Claude sabe cuándo recurrir a él.
Pero aquí está la parte que la guía entierra en una barra lateral que merece estar en la página uno: el campo de descripción en tu frontmatter YAML es la línea más importante que escribirás. Si esto sale mal, nada más importa.
Las dos líneas que definen el éxito o fracaso de tu Skill
Perdí cuatro horas con esto. Cuatro horas construyendo un Skill perfectamente detallado que Claude nunca activó. Las instrucciones eran claras. El formato era preciso. Los documentos de referencia eran completos. Y cada vez que le pedía a Claude que hiciera lo que el Skill estaba diseñado para hacer, simplemente... usaba su conocimiento general. Ignoraba el Skill por completo.
El problema era mi campo de descripción.
Mi descripción original decía: "Helps with code review processes." Seis palabras. Vagas. Pasivas. Claude no tenía idea de cuándo activarlo porque "helps with code review processes" podría significar literalmente cualquier cosa.
La reescribí: "Performs structured code review on pull requests. Trigger when user shares a PR link, asks for code review, requests a PR review, or pastes a diff. Checks for security vulnerabilities, performance issues, naming conventions per team standards, and test coverage gaps."
Empezó a funcionar inmediatamente. Cada vez.
El patrón que descubrí por prueba y error — y la guía insinúa esto pero no lo dice con suficiente claridad — es que tu descripción necesita tres cosas:
1. Qué hace (verbo activo, resultado específico): "Generates weekly reports" no "Helps with reporting."
2. Cuándo activar (frases de activación explícitas): "Trigger when user asks for X, Y, or Z." Enumera las palabras y frases reales que un humano usaría. No seas ingenioso. Sé literal.
3. Qué cubre (límites del alcance): "Checks for A, B, C, and D." Esto le dice a Claude qué está dentro del dominio del Skill y, por implicación, qué no lo está.
El campo name también importa — usa kebab-case, sin espacios, y hazlo descriptivo. weekly-status-report supera a report-v2 supera a wsr. Claude usa el nombre como una señal adicional para el emparejamiento, así que los nombres descriptivos mejoran la precisión de activación.
Volví y reescribí las descripciones de los siete Skills que había construido. Seis de ellos empezaron a activarse correctamente de inmediato. El séptimo necesitó otra ronda de refinamiento — resultó que mis frases de activación se solapaban con otro Skill, y Claude se confundía sobre cuál cargar.
Lo que me lleva a un problema que la guía no aborda en absoluto: qué pasa cuando los Skills entran en conflicto. Más sobre esto en un minuto. Primero, los tres casos de uso para los que Anthropic diseñó este sistema — porque entender los casos de uso previstos cambia cómo piensas en la construcción de Skills.
Tres casos de uso — Y el que Anthropic subestima
La guía divide Claude Skills en tres aplicaciones principales. Cada una resuelve un problema genuinamente diferente, y confundirlos es un error que cometí al principio.
Caso de uso 1: Creación de documentos
Esta es la aplicación más directa. Tienes un tipo específico de documento — una presentación, una especificación técnica, una propuesta para cliente, un brief de diseño — que necesita seguir estándares consistentes cada vez. Fuentes, estructura, tono, secciones requeridas, frases prohibidas. En lugar de pegar una guía de estilo en cada conversación, la codificas una vez en un Skill.
Construí uno para propuestas de clientes que incluye nuestros niveles de precios, lenguaje estándar de alcance, avisos legales requeridos y reglas de formato. Lo que antes me tomaba 20 minutos de elaboración de prompts por propuesta ahora toma una frase: "Escribe una propuesta para [cliente] cubriendo [alcance]." El Skill se encarga de todo lo demás.
Caso de uso 2: Automatización de flujos de trabajo
Aquí es donde los Skills empiezan a devolver tiempo en serio. Procesos de múltiples pasos que necesitan ocurrir de la misma manera cada vez — planificación de sprints, checklists de despliegue, secuencias de onboarding, procedimientos de respuesta a incidentes.
Mi Skill de planificación de sprint es del que estoy más orgulloso. Se conecta a Linear para obtener el estado actual del proyecto, analiza nuestra velocidad en los últimos tres sprints, identifica los elementos que se arrastran y siguen posponiéndose, sugiere prioridades basadas en la proximidad de fechas límite y cadenas de dependencia, y crea los tickets de sprint reales con puntos estimados. Un proceso que solía consumir 90 minutos de mi lunes por la mañana ahora ocurre en unos cuatro minutos, conmigo revisando y aprobando el resultado en lugar de generarlo desde cero.
La clave para los Skills de flujo de trabajo: necesitas ser explícito sobre el orden de las operaciones y la lógica de decisión en cada paso. "Analizar la velocidad" es demasiado vago. "Calcular el promedio de story points completados por sprint en los últimos 3 sprints, excluyendo sprints de menos de 8 días. Si la velocidad está disminuyendo durante 2+ sprints consecutivos, marcar esto en el resultado de la planificación con el porcentaje de caída" — eso es lo que Claude necesita.
Caso de uso 3: Mejora de MCP
Este es el caso de uso que más entusiasma a Anthropic, y honestamente, es el que creo que subestiman en cuanto a su potencial. La mejora de MCP significa superponer experiencia de dominio sobre el acceso a herramientas. Tu Skill no solo usa Figma — conoce tu sistema de diseño, tus convenciones de nomenclatura de componentes, tus requisitos de accesibilidad y el flujo específico para entregar diseños a ingeniería.
Construí un Skill de entrega de diseño a desarrollo que obtiene los últimos diseños de Figma, extrae las especificaciones de los componentes, los mapea a nuestra biblioteca existente de componentes React, identifica las brechas donde se necesitan nuevos componentes, crea tickets en Linear para el trabajo de ingeniería con criterios de aceptación extraídos de las especificaciones de diseño, y publica un resumen en nuestro canal de desarrollo en Slack.
Seis herramientas diferentes. Un Skill. Una frase de activación: "Procesa los nuevos diseños."
Esto es lo que Anthropic subestima de este caso de uso: el valor compuesto. Cada vez que un experto de dominio en tu equipo revisa el resultado del Skill y dice "en realidad, también necesitamos verificar X antes de la entrega", agregas esa verificación al archivo SKILL.md. A lo largo de semanas y meses, el Skill acumula conocimiento institucional que de otro modo viviría solo en las cabezas de las personas. Se convierte en un documento vivo de cómo tu equipo realmente trabaja — no cómo las herramientas fueron diseñadas para funcionar, sino cómo tu gente usa esas herramientas en tu contexto específico.
Eso no es automatización. Es memoria organizacional con capacidad de ejecución. Y no creo que la mayoría de los equipos hayan comprendido lo poderoso que es esto.
Ahora — los cinco patrones que realmente estructuran cómo construyes estas cosas.
Cinco patrones que cubren el 90% de los Skills del mundo real
La guía presenta cinco "patrones probados" para estructurar Skills. Después de construir once Skills en tres proyectos, diría que estos patrones son genuinos — no son categorías de marketing. Cada uno resuelve un problema estructuralmente diferente, e intentar forzar un Skill en el patrón equivocado crea bugs sutiles que son difíciles de diagnosticar.
Patrón 1: Flujo de trabajo secuencial
Los pasos ocurren en un orden fijo. El paso 2 depende del resultado del paso 1. El paso 3 depende del paso 2. Sin ramificaciones, sin condicionales — solo un pipeline confiable.
Ideal para: procedimientos de despliegue, checklists de cumplimiento, secuencias de onboarding, scripts de migración de datos.
El detalle clave que la guía acierta: numera tus pasos explícitamente e incluye criterios de validación entre pasos. "Antes de proceder al paso 3, verificar que el paso 2 produjo [resultado específico]. Si no, reintentar el paso 2 con [enfoque alternativo]."
Patrón 2: Coordinación Multi-MCP
El flujo de trabajo abarca múltiples servicios externos. Figma a Linear a Slack. GitHub a Jira a Confluence. El Skill orquesta el flujo de datos entre herramientas que no se comunican nativamente entre sí.
Ideal para: flujos de trabajo entre herramientas, entregas de diseño, gestión de releases, notificaciones entre equipos.
Mi mayor aprendizaje aquí: incluye instrucciones explícitas de transformación de datos entre las llamadas a herramientas. El formato en que Figma exporta las especificaciones de componentes no es el formato que Linear acepta para las descripciones de tickets. Tu Skill necesita especificar exactamente cómo reformar los datos a medida que se mueven entre herramientas.
Patrón 3: Refinamiento iterativo
Generar resultado, validarlo contra criterios, mejorarlo, validar de nuevo. El Skill incluye su propio ciclo de calidad en lugar de producir un resultado de una sola pasada.
Ideal para: generación de informes, creación de contenido, revisión de código donde quieres cobertura completa, cualquier resultado que se beneficie de la autocrítica.
Uso este patrón para mi Skill de propuestas para clientes. Primer borrador, luego una pasada de revisión verificando jerga y ambigüedad, luego una pasada final de formato. La diferencia de calidad del resultado entre una sola pasada y el proceso iterativo es sustancial — fácilmente vale los 30 segundos extra de tiempo de procesamiento.
Patrón 4: Selección consciente del contexto
Mismo objetivo, diferentes caminos de ejecución basados en el contexto. Subes un PNG y usa un flujo de trabajo. Subes un SVG y usa otro. Archivo pequeño se procesa en línea; archivo grande se fragmenta.
Ideal para: procesamiento de archivos, generación de contenido en diferentes formatos, scripts de despliegue que varían por entorno.
Este patrón es más complicado de lo que parece. Tu SKILL.md necesita lógica de ramificación clara: "Si la entrada es [tipo A], seguir los pasos 1-4. Si la entrada es [tipo B], seguir los pasos 5-8." Condiciones de ramificación ambiguas llevan a que Claude elija el camino equivocado y produzca un resultado correcto para el escenario equivocado — lo cual es más difícil de detectar que un error obvio.
Patrón 5: Inteligencia de dominio
El Skill encarna experiencia profunda en un dominio específico — reglas de cumplimiento financiero, protocolos de seguridad, estándares de codificación médica, criterios de revisión legal. El valor no está en el flujo de trabajo; está en el conocimiento mismo.
Ideal para: verificación de cumplimiento, auditorías de seguridad, procesos de revisión especializados, cualquier tarea donde "conocer las reglas" es la parte difícil.
Este es el patrón donde los documentos de referencia en tu carpeta de Skill se ganan su lugar. Un archivo SKILL.md que apunta a una checklist de cumplimiento de seguridad de 50 páginas puede convertir a Claude en un auditor de primera pasada genuinamente útil. No un reemplazo de la experiencia humana — pero un primer revisor incansable que nunca olvida verificar el punto 47 de la página 12.
Bien, ese es el framework. Ahora déjame ahorrarte las horas que perdí en errores de los que la guía no te advierte.
Cuatro errores que cometí para que tú no tengas que hacerlo
Error 1: Descripciones vagas que nunca se activan.
Ya cubrí esto, pero vale la pena repetirlo porque es el modo de fallo número uno. Si tu Skill nunca se activa, la descripción es casi siempre el problema. Escribe frases de activación que coincidan con las palabras exactas que un humano usaría. "Run my deployment checklist" no "assist with deployment processes."
Error 2: Instrucciones enterradas en muros de texto.
Mis primeros Skills eran novelas. Páginas de contexto, información de fondo, casos límite, filosofía sobre por qué hacemos las cosas de cierta manera. Claude los analizaba, pero la relación señal-ruido era terrible. Las instrucciones importantes se diluían con el texto explicativo.
Lo que funciona mejor: prioriza las instrucciones críticas al principio. Pon las reglas no negociables en las primeras 20 líneas. Usa encabezados agresivamente. Reserva el contexto de fondo para un documento de referencia separado en la carpeta que Claude pueda consultar cuando sea necesario pero no tenga que procesar en cada invocación.
Error 3: Falta de manejo de errores para las llamadas MCP.
Este me pegó fuerte. Mi Skill de planificación de sprint funcionaba maravillosamente — hasta que la API de Linear devolvió un error de límite de tasa un lunes por la mañana, y el Skill simplemente... se detuvo. Sin fallback. Sin reintento. Sin degradación elegante. Solo un Claude confundido diciendo que no podía completar la solicitud.
Tu Skill necesita anticipar fallos de herramientas. Agrega instrucciones explícitas: "Si la llamada a la API de Linear falla, esperar 10 segundos y reintentar una vez. Si falla de nuevo, proceder con datos en caché de la última ejecución exitosa y notar que los datos pueden estar desactualizados." Esto es ingeniería de resiliencia básica, pero es fácil olvidarlo cuando te enfocas en el camino feliz.
Error 4: Intentar hacer demasiado en un solo Skill.
Construí un Skill llamado "project-manager" que intentaba manejar planificación de sprint, informes de estado, generación de retrospectivas, refinamiento de backlog y actualizaciones a stakeholders. Eran 400 líneas de instrucciones cubriendo cinco flujos de trabajo distintos.
Era terrible. Claude activaba el Skill correcto pero seguía el flujo de trabajo equivocado dentro de él. Las frases de activación para diferentes sub-tareas se solapaban. Las instrucciones para planificación de sprint contradecían algunas de las convenciones usadas en la generación de retrospectivas.
Lo dividí en cinco Skills separados. Cada uno se volvió más simple, más confiable y más fácil de mantener. La sobrecarga de tener cinco carpetas en lugar de una es negligible. La mejora en precisión y consistencia fue dramática.
El principio subyacente: un Skill, un trabajo. Si estás escribiendo "también" o "adicionalmente" en tu SKILL.md, probablemente necesites un segundo Skill.
La idea que cambia cómo piensas sobre la IA en el trabajo
La guía termina con un pensamiento que casi pasé por alto, pero en realidad es la idea más importante en las 32 páginas.
La mayoría de las personas usan la IA como un asistente de propósito general. Cada conversación empieza desde cero. Explicas tu contexto, tus preferencias, tus estándares, tus herramientas, tus flujos de trabajo — y luego obtienes una respuesta moldeada por toda esa explicación. Mañana, lo haces de nuevo. Y otra vez. Y otra vez.
Claude Skills invierte este modelo. En lugar de llevar el contexto a la IA en cada conversación, incrustas el contexto dentro del entorno de la IA permanentemente. La IA comienza cada conversación relevante ya conociendo tus estándares, ya conectada a tus herramientas, ya comprendiendo tus flujos de trabajo.
Esto no es un truco de productividad. Es un cambio arquitectónico en cómo los humanos y la IA colaboran.
Cuando miro los once Skills que he construido en los últimos tres días, estoy mirando una versión comprimida de cómo trabaja mi equipo. Nuestros estándares de revisión de código. Nuestro proceso de despliegue. Nuestro estilo de comunicación con clientes. Nuestra metodología de planificación de sprints. Nuestro flujo de trabajo de entrega de diseño. Todo codificado, ejecutable y mejorando cada vez que alguien del equipo agrega una línea a un archivo SKILL.md.
Las organizaciones que descubran esto temprano — que empiecen a construir bibliotecas de Skills capturando sus mejores prácticas y conocimiento institucional — van a tener una ventaja compuesta que crece cada mes. No porque la IA sea más inteligente. Porque la IA los conoce mejor.
Empecé este artículo hablando de borrar mis prompts guardados. Ese fue el síntoma. El cambio real es más profundo. Dejé de pensar en Claude como una herramienta a la que instruyo y empecé a pensar en él como un miembro del equipo al que incorporo. La carpeta de Skills es el manual de incorporación. Y al igual que incorporar a un humano, la inversión inicial de escribir instrucciones claras se devuelve cada día que esa persona — o ese Skill — se presenta y hace el trabajo sin que se lo digan dos veces.
Anthropic construyó el framework. Las 32 páginas presentan la mecánica. Pero el valor no está en el framework — está en lo que pones dentro de él.
Así que esta es mi pregunta: ¿cuál es el flujo de trabajo que repites cada semana y que podrías enseñarle a Claude una vez y nunca volver a explicar? Empieza por ahí. Una carpeta. Un SKILL.md. Una descripción que realmente se active.
Todo lo demás se construye a partir de ese primer Skill que funciona.
Trabajemos juntos
¿Buscas construir sistemas de IA, automatizar flujos de trabajo o escalar tu infraestructura tecnológica? Me encantaría ayudarte.
- Fiverr (construcciones personalizadas e integraciones): fiverr.com/s/EgxYmWD
- Portfolio: mejba.me
- Ramlit Limited (soluciones empresariales): ramlit.com
- ColorPark (diseño y branding): colorpark.io
- xCyberSecurity (servicios de seguridad): xcybersecurity.io
