Tu equipo tiene licencias de Claude Code, Cursor o Copilot. Cada developer ha encontrado sus propios trucos: prompts que funcionan, instrucciones que dan buenos resultados, formas de pedir code reviews que producen feedback útil. El problema es que ese conocimiento vive en la cabeza de cada persona. Cuando alguien se va, se lleva sus prompts. Cuando alguien nuevo entra, empieza de cero.
Los Skills resuelven exactamente esto. Son el mecanismo estándar para empaquetar instrucciones, scripts y conocimiento en unidades reutilizables que cualquier agente de IA puede descubrir y ejecutar. No es un concepto teórico: el equipo de Claude Code en Anthropic tiene cientos de Skills en uso activo, y los describe como el punto de extensión más utilizado de la herramienta.
Pero su flexibilidad es también su riesgo. Un Skill mal escrito consume tokens sin aportar valor, confunde al agente o, peor, produce resultados inconsistentes que el developer acepta sin revisar. Esta guía condensa las lecciones publicadas por Anthropic, los patrones que funcionan en equipos reales y los errores que hemos visto en 12 transformaciones.
Qué es un Skill y por qué importa
Un Skill es un archivo SKILL.md con instrucciones que un agente de IA carga cuando son relevantes. La idea es simple: en lugar de repetir la misma instrucción cada vez que necesitas algo, la escribes una vez, la empaquetas y dejas que el agente la descubra automáticamente o la invoque bajo demanda con /nombre-del-skill.
Pero un Skill es más que un archivo de texto. Es un directorio que puede contener:
- SKILL.md (obligatorio): las instrucciones principales con metadatos YAML.
- Archivos de referencia: documentación detallada que el agente carga solo cuando la necesita.
- Scripts ejecutables: código que el agente ejecuta directamente, sin tener que generarlo.
- Templates: plantillas que el agente rellena según el contexto.
- Ejemplos: pares entrada/salida que muestran el formato esperado.
La estructura típica de un Skill con complejidad media:
mi-skill/
├── SKILL.md # Instrucciones principales (obligatorio)
├── reference.md # Documentacion detallada (carga bajo demanda)
├── examples.md # Ejemplos de uso
├── templates/
│ └── template.md # Plantilla para rellenar
└── scripts/
└── validate.sh # Script que el agente ejecutaAnatomía de un SKILL.md efectivo
Todo SKILL.md tiene dos partes: un frontmatter YAML con metadatos y un cuerpo markdown con instrucciones.
El frontmatter: metadatos que guían al agente
El frontmatter define cuándo y cómo se usa el Skill. Los campos clave:
| Campo | Función | Clave |
|---|---|---|
| name | Nombre del Skill. Se convierte en /nombre. | Solo minúsculas, números y guiones. |
| description | Qué hace y cuándo usarlo. El agente lo usa para decidir si activarlo. | Siempre en tercera persona. Específico. |
| disable-model-invocation | Si es true, solo el usuario puede invocarlo. | Usar para deploy, envíos, acciónes destructivas. |
| allowed-tools | Herramientas que el agente puede usar sin pedir permiso. | Controla el alcance del Skill. |
| context | Si es fork, el Skill se ejecuta en un subagente aislado. | Ideal para tareas que no deben contaminar el contexto principal. |
El cuerpo: dos tipos de contenido
Según Anthropic, pensar en qué tipo de contenido contiene tu Skill ayuda a decidir cómo estructurarlo:
Contenido de referencia
Añade conocimiento que el agente aplica a tu trabajo actual: convenciónes, patrones, guías de estilo, conocimiento de dominio.
Se ejecuta: inline, junto con tu conversación.
Ejemplo: convenciónes de API, reglas de nombrado, patrones del proyecto.
Contenido de tarea
Instrucciones paso a paso para una acción concreta: deploys, commits, generación de código, migraciones.
Se ejecuta: normalmente invocado con /nombre.
Ejemplo: skill de deploy, skill de migración de base de datos.
Lecciones del equipo de Claude Code
Thariq Shihipar, del equipo de Anthropic, publicó una serie de artículos sobre las lecciones aprendidas construyendo Claude Code. En "How We Use Skills", comparte lo que han descubierto gestionando cientos de Skills internamente. Estas son las lecciones que más impacto tienen:
1. La sección de "Gotchas" es el contenido de mayor valor
Los mejores Skills empezaron como unas pocas líneas y un aviso sobre algo que podía fallar. Ese aviso — el gotcha — es lo que marca la diferencia. Es información que el agente no puede deducir del código: un edge case sutil, un comportamiento inesperado de una API, una convención no documentada.
En la práctica: Cada vez que un agente comete un error usando tu Skill, añade un gotcha. Los Skills más útiles de Anthropic han acumulado gotchas durante meses. No nacieron perfectos. Evolucionaron con el uso.
2. No repitas lo que el agente ya sabe
Claude (y otros modelos avanzados) sabe mucho sobre programación, frameworks y patrones comunes. Explicar qué es un PDF o cómo funciona una librería popular es gastar tokens sin aportar valor.
La regla de Anthropic: si estás publicando un Skill que es principalmente conocimiento, céntrate en información que empuje al agente fuera de su forma habitual de pensar. Las excepciones, los edge cases, las decisiones de tu equipo que son diferentes del patrón por defecto.
3. Da información, no restricciones excesivas
El agente intentará seguir tus instrucciones al pie de la letra. Si eres demasiado específico, pierdes la capacidad del agente de adaptarse al contexto real. Si eres demasiado vago, no aportas valor.
El equilibrio depende del riesgo:
Migraciones de BD, deploys, acciónes destructivas. Script exacto, sin variaciones.
Generacion de código, configuración. Pseudocódigo o template con parámetros.
Code reviews, análisis, investigación. Guia general, confía en el criterio del agente.
4. El sistema de archivos es progressive disclosure
No toda la información debe cargarse siempre. Los Skills de Anthropic usan el sistema de archivos como mecanismo de progressive disclosure: el SKILL.md contiene lo esencial y apunta a archivos de referencia que el agente carga solo cuando los necesita.
Esto no es una optimización menor. La ventana de contexto es un recurso compartido. Tu Skill compite con el historial de conversación, otros Skills, el system prompt y la solicitud actual del usuario. Cada token cuenta.
5. Desarrolla Skills de forma iterativa con el propio agente
El proceso más efectivo que usa Anthropic internamente sigue un patrón con dos instancias:
- Claude A (el experto): te ayuda a crear y refinar el Skill.
- Claude B (el usuario): usa el Skill en tareas reales y revela los huecos.
El ciclo: completa una tarea sin Skill → identifica qué contexto tuviste que dar manualmente → pide a Claude A que lo empaquete como Skill → prueba con Claude B → observa dónde falla → vuelve a Claude A para refinar.
Este ciclo es exactamente lo que en nuestra metodología Spec-Driven Development llamamos iteración sobre especificaciónes: el conocimiento se codifica, se testea y se mejora continuamente.
5 patrones que funcionan
Estos patrones aparecen recurrentemente en los Skills más efectivos, tanto internos de Anthropic como en equipos que hemos transformado:
1. Patrón Template
Proporcionas una plantilla que el agente rellena. Útil cuando necesitas un formato de salida consistente: commit messages, reports, documentación técnica. El grado de rigidez depende del caso: estricto para formatos de API, flexible para análisis.
2. Patrón Examples (entrada/salida)
Pares de ejemplo que muestran el formato esperado. Mas efectivo que describir el formato con palabras. El agente entiende el estilo y nivel de detalle que esperas viendo ejemplos concretos, no leyendo reglas abstractas.
3. Patrón Workflow con checklist
Para operaciones complejas de múltiples pasos, proporciona un checklist que el agente copia y marca a medida que avanza. Esto evita que se salte pasos críticos, especialmente en procesos de validación.
## Workflow de deploy
Copia este checklist y marca el progreso:
- [ ] Paso 1: Ejecutar suite de tests
- [ ] Paso 2: Build de la aplicación
- [ ] Paso 3: Push al target de deploy
- [ ] Paso 4: Verificar que el deploy fue exitoso
- [ ] Paso 5: Smoke test en producción4. Patrón Config
Almacenas configuración en un config.json dentro del directorio del Skill. Si no existe, el agente pide los datos al usuario. Esto permite que el mismo Skill funcione en diferentes entornos sin modificar las instrucciones.
5. Patrón de inyección dinámica
Skills que ejecutan comandos shell antes de enviar el contenido al agente. La sintaxis !`comando` ejecuta el comando y reemplaza el placeholder con el resultado. El agente recibe datos reales, no el comando.
Ejemplo practico: un Skill de code review que ejecuta !`git diff` para inyectar los cambios reales en el prompt antes de que el agente los analice.
Anti-patrones que destruyen Skills
Estos errores son tan comunes como dañinos. Los hemos visto repetidamente:
Skill demasiado verboso
Explicar qué es un PDF, cómo funcionan los decoradores de Python o qué hace git commit. El agente lo sabe. Cada párrafo innecesario es contexto que desplaza información útil. La regla: si puedes asumir que el agente lo sabe, no lo incluyas.
Demasiadas opciones
"Puedes usar pypdf, pdfplumber, PyMuPDF o pdf2image..." Esto no ayuda, paraliza. Proporciona un default claro y una alternativa para el caso excepcional. Nada más.
Referencias anidadas
SKILL.md apunta a advanced.md, que apunta a details.md, que contiene la información real. El agente puede leer parcialmente archivos referenciados desde otros archivos referenciados. Mantén las referencias a un solo nivel de profundidad.
Información que caduca
"Si estás haciendo esto antes de agosto 2025, usa la API v1." Esto se convierte en desinformación en cuanto pasa la fecha. Usa secciónes de "patrón legacy" con detalles colapsables si necesitas contexto histórico.
Terminología inconsistente
Mezclar "API endpoint", "URL", "ruta" y "path" para referirse a lo mismo. El agente no sabe que son sinónimos en tu contexto. Elige un termino, úsalo siempre.
El coste real: Un Skill mal escrito no es inocuo. Consume tokens de la ventana de contexto, reduce la calidad de respuesta del agente en otras tareas y, si produce resultados sutilmente incorrectos, genera deuda técnica que pasa desapercibida hasta que es tarde.
Skills en equipo: de lo individual a lo organizacional
La potencia real de los Skills aparece cuando dejan de ser herramientas individuales y se convierten en conocimiento compartido del equipo. Hay cuatro niveles de distribución:
En ~/.claude/skills/. Disponible en todos tus proyectos. Tus propias convenciónes y workflows.
En .claude/skills/ del repositorio. Se commitea con el código. Todo el equipo del proyecto lo hereda automáticamente.
Desplegado organizacionalmente a travésde managed settings. Todos los usuarios de la empresa lo tienen disponible.
El equipo de Anthropic describe cómo han creado un marketplace interno de plugins donde los Skills que ganan tracción orgánicamente son promovidos al marketplace oficial via PR. No hay un equipo centralizado decidiendo qué Skills usar: la adopción es bottom-up.
Este modelo refleja lo que vemos en los equipos más efectivos: el conocimiento no se impone top-down. Se descubre, se valida y se escala.
Skills y Spec-Driven Development: dos caras de la misma moneda
Si has leído nuestros insights sobre context engineering y Spec-Driven Development, verás que los Skills son la implementación práctica de ambos conceptos:
- Context engineering define la disciplina de diseñar y gestionar el contexto de IA. Los Skills son su mecanismo de empaquetado y distribución.
- SDD establece que el trabajo con IA debe partir de especificaciónes estructuradas. Un Skill es una especificación: define qué debe hacer el agente, con qué herramientas, siguiendo qué patrón, y qué errores evitar.
En nuestra metodología, los Skills forman parte de la Constitución del proyecto: el conjunto de reglas y conocimiento que la IA debe respetar. Junto con los templates de especificación, los playbooks de prompts y los checklists de code review, los Skills completan el sistema que hace que la IA produzca resultados consistentes y alineados con los estándares del equipo.
Cómo empezar: checklist para tu primer Skill
No necesitas crear un sistema completo desde el primer día. Empieza con un Skill, mide el impacto y escala. Este es el camino:
- Identifica una tarea repetitiva. Algo que tu equipo explica a la IA más de tres veces por semana. Commit messages, code reviews, migraciones de componentes, configuración de tests.
- Completa la tarea con el agente sin Skill. Observa qué contexto tienes que proporcionar manualmente. Apunta las correcciones que haces.
- Crea el Skill mínimo. Solo el SKILL.md con frontmatter básico y las instrucciones esenciales. Sin archivos extra. Sin scripts.
- Testea con un caso real. No con un ejemplo inventado. Observa dónde el agente falla o acierta.
- Añade gotchas. Cada error del agente es un gotcha potencial. Añadelo al Skill.
- Commitea al repositorio. Ponlo en
.claude/skills/para que todo el equipo lo herede. - Itera. El Skill mejorará con cada uso real. No intentes que sea perfecto al principio.
---
name: code-review
description: Revisa código siguiendo las convenciónes del
proyecto. Usa cuando el usuario pide una review o antes de
commitear cambios.
---
Al revisar código, sigue estos pasos:
1. Verifica que cumple las convenciónes en CONVENTIONS.md
2. Busca posibles bugs o edge cases no cubiertos
3. Sugiere mejoras de legibilidad solo si son significativas
4. Marca como "gotcha" cualquier patrón que pueda ser confuso
## Gotchas de este proyecto
- Los hooks de React deben seguir el patrón useXxxQuery
(no useGetXxx)
- Nunca usar any en tipos de respuesta de API
- Los tests de integración requieren el flag --run-dbEl futuro: Skills como ventaja competitiva
Estamos en un momento de inflexión. La IA generativa ya no se diferencia por el modelo: todos los equipos tienen acceso a los mismos LLMs. La diferenciación esta en cómo configuras y diriges esa IA.
Los equipos que traten los Skills como un activo de ingeniería — versionado, testeado, distribuido, mejorado continuamente — tendrán una ventaja compuesta. Cada Skill que funciona reduce fricción para todo el equipo. Cada gotcha añadido evita un error que habría costado horas de debug. Cada patrón compartido elimina variabilidad en la calidad del output.
La pregunta no es si tu equipo necesita Skills. Es cuánto tiempo puedes permitirte seguir sin ellos.
Lectura complementaria: Context Engineering: la disciplina que satisface equipos con IA | Instrucciones compartidas y curadas para equipos | Spec-Driven Development
Metodología: En onext implementamos Skills, context engineering y SDD como parte de nuestros Centros de Excelencia de IA. 12 equipos transformados, 0 sprints perdidos.