Guía completa para principiantes sobre Agent Skills: Cómo crear tu primera habilidad

Todo el que trabaja con IA se ha topado con este problema:

Le enseñas algo, al día siguiente inicias una nueva conversación y todo vuelve a cero.

Pasas tres días ajustando un flujo de trabajo, yendo y viniendo con Claude para dejarlo perfecto, solo para tener que explicarlo todo de nuevo al día siguiente.

Guardas prompts en tus notas y los pegas cada vez, pero pegar una instrucción de 500 palabras todos los días durante un mes te hace preguntarte: ¿así es como realmente debería usarse la IA?

Skill nació precisamente para resolver este problema.

Fue lanzado por Anthropic en octubre de 2025 y se convirtió en un estándar abierto en diciembre.

Hoy, todo internet grita "Skills cambian la productividad", pero la mayoría solo ha oído hablar de ello sin entender realmente la diferencia entre Skills, prompts, bases de conocimiento, MCP y agentes—y mucho menos construir uno ellos mismos.

Este artículo lo explica todo de una vez.

Primero, entiende una cosa: las Skills no están atadas a ninguna IA específica.

Mucha gente escucha "Claude Skills" y piensa que es una función exclusiva de Claude, pero no lo es. Agent Skills es un estándar abierto lanzado por Anthropic; Claude es solo el implementador principal.

La misma carpeta de Skill se puede colocar en ~/.claude/skills/ para Claude Code, ~/.cursor/skills/ para Cursor, o usarse con OpenAI Codex, Gemini CLI, VS Code Copilot y JetBrains Junie.

La Skill que escribas hoy se puede mover sin problemas a otro Agente mañana; tu inversión no quedará atrapada en una sola empresa.

Este artículo usará principalmente Claude Code como ejemplo (ya que es el que establece el estándar con el ecosistema más completo), pero todos los principios, métodos de escritura y experiencias de solución de problemas aplican a todas las herramientas de IA que soportan Agent Skills.

Cuando veas "Claude Skill", piensa "Agent Skill".

1. ¿Qué es exactamente una Skill?

Definición en una frase:

Una Skill es una carpeta, centrada en un archivo Markdown llamado SKILL.md, que le indica a una IA cómo ejecutar de manera estable un tipo específico de trabajo profesional según un SOP que tú defines.

Encapsula "cómo se debe hacer cierto tipo de cosa" en un módulo de capacidad reutilizable y activado automáticamente.

Esencialmente, es un "paquete de expansión" para IA de propósito general.

La IA general es como una máquina básica: inteligente pero sin conocimiento del dominio. Una Skill es un módulo plug-and-play: instala una "Skill de estilo Xiaohongshu", y la IA se convierte inmediatamente en un editor que entiende tu marca; instala una "Skill de informe semanal", y la IA genera informes al instante en el formato de tu empresa.

Y este "paquete de expansión" no es exigente con la IA: Claude Code, Codex, Cursor, Gemini CLI y Junie reconocen el mismo formato.

Estás haciendo una Agent Skill, no un script exclusivo de Claude.

Límites con otros cuatro conceptos:

Mucha gente confunde Skills con prompts, bases de conocimiento, MCP y agentes, pero son distintos:

Analogías comunes:

• Prompt = Enviar un mensaje de WhatsApp a un empleado; lo olvida una vez que termina.
• Skill = Escribir un manual para el empleado y ponerlo en su escritorio, junto con una caja de herramientas.
• Base de conocimiento = Una biblioteca que te dice qué existe en el mundo.
• MCP = Varios utensilios de cocina que resuelven el problema de "si se puede hacer".
• Agente = Todo el sistema de empleados, con memoria y capacidad de decisión; una Skill es solo una parte de él.

Estos cuatro no son mutuamente excluyentes.

En el trabajo real, a menudo se combinan: MCP permite a Claude conectarse a Reddit para extraer datos, una Skill le enseña cómo filtrar/clasificar/recomendar esos datos, una Base de conocimiento proporciona materiales de marca, y el Agente es todo el sistema que ejecuta el proceso.

2. Arquitectura y mecanismo de funcionamiento

Estructura de archivos

Cada subdirectorio resuelve un problema diferente pero sirve al mismo objetivo: ahorrar contexto y estabilizar la calidad:

• scripts/: Cálculos precisos sin consumir contexto.
• references/: Se cargan bajo demanda para no desperdiciar espacio.
• assets/: Estandariza los formatos de salida.

Divulgación progresiva de tres capas: el alma del diseño de Skills

El mecanismo central de una Skill es la carga en tres capas, razón por la cual una docena de Skills pueden coexistir sin explotar el contexto:

Por ejemplo:

Cuando Claude se inicia, solo hojea las "portadas" de todas las Skills para decidir cuál usar; solo cuando es hora de trabajar abre el texto principal; y solo cuando necesita consultar un apéndice hojea las referencias.

Este mecanismo te permite tener 17 Skills activas simultáneamente sin obstruir la ventana de contexto de 200K.

Metadatos YAML

Descripciones de campos:

La descripción determina el éxito o el fracaso

En la arquitectura de tres capas, la descripción de L1 es la más crítica: determina si tu Skill se activará.

Datos clave:

1. Claude solo lee las descripciones de todas las Skills al iniciar.
2. Hace juicios semánticos basados en la descripción, no en coincidencias de palabras clave.
3. Claude tiende a ser conservador: si no está seguro, no se activa. En pruebas, las descripciones vagas tenían una precisión de activación de solo el 55%.

Ejemplo negativo (nunca se activará):

[Descripción vaga]

Ejemplo positivo (estilo "insistente" recomendado por Anthropic):

[Descripción específica]

Tres reglas de oro para escribir descripciones:

1. Escribe QUÉ + CUÁNDO juntos: di qué hace y cuándo usarlo.
2. Enumera palabras desencadenantes tanto en inglés como en español: que coincidan con lo que diga el usuario.
3. Sé insistente en lugar de conservador: Anthropic afirma explícitamente que el principal problema es la activación insuficiente.

3. Principios básicos para escribir buenas Skills

Tres principios principales

Cómo manejar la libertad:

Cinco patrones de diseño

Anthropic resumió cinco patrones de diseño de Skills de usuarios tempranos:

Las Skills útiles a menudo combinan múltiples patrones. No tienes que seguirlos estrictamente, pero saber que existen te ayuda a diseñar con más estructura.

Regla de oro: usa "Por qué" en lugar de "Debe"

Esto es una cita del código fuente de skill-creator (la meta-skill oficial de Anthropic para hacer Skills):

"Intenta explicarle al modelo por qué las cosas son importantes en lugar de usar MUSTs pesados y dominantes."

Ejemplo negativo:

[Reglas estrictas con "DEBE"]

Ejemplo positivo:

[Explicando el razonamiento]

En el primer caso, Claude solo seguirá esas dos reglas. En situaciones no cubiertas por las reglas (como un comando aparentemente seguro pero riesgoso), se queda atascado. En el segundo caso, Claude entiende "por qué la seguridad es importante" y tenderá a ser cauteloso incluso en áreas grises.

Las razones permiten que el modelo generalice; las reglas solo cubren escenarios que puedas imaginar. La única excepción es el formato de salida: los requisitos mecánicos como "la salida debe usar esta plantilla" no tienen un "por qué" que explicar, así que simplemente codifícalos.

Propiedad de la información: no te repitas

skill-creator también tiene una regla de hierro:

"La información debe existir en SKILL.md o en references, no en ambos."

SKILL.md solo debe contener procedimientos básicos; mueve los detalles a references/. El almacenamiento duplicado provoca inconsistencias cuando actualizas uno y olvidas el otro.

Archivos que evitar

Las Skills son para IA, no para humanos. No agregues README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md ni CHANGELOG.md. Estos documentos humanos solo desperdician contexto.

4. Construyendo tu primera Skill

Los seis pasos oficiales de Anthropic

El proceso estándar definido dentro de skill-creator:

1. Capturar intención: aclarar qué hacer / cuándo activar / formato de salida / necesidades de prueba.
2. Entrevista e investigación: casos extremos / formatos de entrada/salida / archivos de ejemplo / dependencias.
3. Escribir SKILL.md: redactar el borrador.
4. Casos de prueba: escribir 2-3 casos de prueba reales.
5. Ejecutar y evaluar: ejecutar con-skill y línea base (sin skill) en paralelo para una comparativa.
6. Iterar: modificar según los comentarios y volver a ejecutar hasta estar satisfecho.

Cuatro vías rápidas para usuarios habituales

skill-creator: la meta-skill para escribir Skills

Recomiendo encarecidamente instalar primero el skill-creator oficial de Anthropic. Es una Skill diseñada para ayudarte a hacer Skills. Una vez iniciado, Claude te entrevistará—preguntándote sobre tu flujo de trabajo, condiciones de activación y límites—y luego generará automáticamente el SKILL.md y la estructura de carpetas.

Comando de instalación:

[Comando]

No solo produce resultados; también te ayuda a:

• Eval: generar casos de prueba automáticamente para verificar si la Skill se activa correctamente.
• Improve: optimizar automáticamente descripciones e instrucciones basándose en los resultados de las pruebas, usando una división 60/40 entrenamiento/prueba para evitar sobreajuste.
• Benchmark: rastrear tasas de éxito y uso de tokens, incluso ejecutando pruebas A/B entre dos versiones.

Un ejemplo mínimo

Supón que eres un bloguero de comida de Xiaohongshu que quiere reescribir recetas normales al estilo Xiaohongshu:

Colócalo en ~/.claude/skills/xiaohongshu-recipe/SKILL.md. En el futuro, decir "convierte a versión Xiaohongshu" lo activará automáticamente.

Desde crear el archivo hasta usarlo lleva menos de 20 minutos.

5. Instalación, almacenamiento y uso entre herramientas

Prioridad de carga (4 niveles)

Claude Code busca en el siguiente orden; las ubicaciones más específicas tienen mayor prioridad:

Consejo: a menos que sea específico del proyecto, mantenlas en el directorio personal ~/.claude/skills/ para una gestión unificada.

Tres métodos de instalación:

Recuerda reiniciar Claude Code después de la instalación.

Compatibilidad entre herramientas (reiterado)

Como se mencionó, las Skills no están atadas a Claude. Aquí están las comparaciones de rutas:

Significado operativo: puedes crear un enlace simbólico de la misma carpeta SKILL.md a diferentes directorios de herramientas. Este es el mayor beneficio de Agent Skills como estándar abierto.

Puntos débiles para usuarios domésticos

• Claude oficial es caro: usa APIs proxy para una mejor relación costo-rendimiento.
• CC Switch: una herramienta de código abierto para gestionar y cambiar múltiples configuraciones de API (github.com/farion1231/cc-switch).
• La instalación nativa es más estable que npm: curl -fsSL https://claude.ai/install.sh | bash.

6. Avanzado: arquitectura de colaboración multi-Skill

Granularidad

Principio básico: una tarea clara por Skill. No hagas una "Skill universal".

Si la granularidad es demasiado gruesa, la descripción se vuelve poco clara y las activaciones son imprecisas. Si es demasiado fina, aumentan los costos de gestión. Una granularidad razonable es una Skill por categoría de problema, con un cuerpo de SKILL.md de aproximadamente 200-500 líneas.

Caso de estudio: suite de Skills para escribir blogs

No hagas una "Skill de escritura todo en uno". Divídela en 5 Skills colaboradoras:

Modo de colaboración: la Skill principal llama explícitamente a otras Skills en su sección ## Steps.

Beneficios de esta división:

Cinco experiencias de ingeniería

1. Granularidad fina: una tarea clara por Skill.
2. Colaboración explícita: usa ## Steps en la Skill principal para llamar a otras.
3. Scripts para cálculos: usa scripts para contar caracteres SEO o estadísticas de enlaces; no dejes que el modelo estime.
4. Guías de estilo independientes: coloca el conocimiento estable (estilo de escritura/especificaciones de marca) en references/ para que solo cambies un archivo para actualizar el estilo.
5. Plantilla de respaldo: las plantillas proporcionan una garantía base para que la salida no se desvíe demasiado.

7. Evaluación e iteración profesional

Sistema de evaluación:

El proceso estándar de skill-creator:

1. Escribe prompts de prueba en evals/evals.json.
2. Ejecuta with_skill y baseline (sin skill) simultáneamente para una comparación a doble ciego.
3. Puntúa cada afirmación usando agents/grader.md.
4. Usa aggregate_benchmark para generar un informe de pass_rate / tiempo / tokens.

Optimización automática de descripciones

La parte más valiosa de skill-creator es la Optimización de Descripciones:

• Escribe 20 consultas de evaluación de activación (8-10 que deberían activar + 8-10 que no).
• Dificultad: "casi aciertos" para las que no activan—consultas que comparten palabras clave pero necesitan otra herramienta.
• Script de optimización: 60% entrenamiento + 40% prueba retenida para evitar sobreajuste.
• Ejecuta 5 rondas y elige la descripción con la puntuación de prueba más alta.

Buenos ejemplos de activación: no escribas solo "extraer tabla de PDF"; escribe como un usuario real:

"vale, mi jefa me acaba de enviar este archivo xlsx (está en mis descargas, se llama algo así como 'Q4 ventas final FINAL v2.xlsx') y quiere que agregue una columna que muestre el margen de beneficio como porcentaje."

Esto incluye rutas de archivo, contexto personal, nombres de columnas, lenguaje informal y posibles errores tipográficos.

Mentalidad de iteración

Cuatro puntos de skill-creator:

1. Generaliza a partir de los comentarios: no agregues reglas complicadas para un solo caso. Si un problema se repite, prueba con una metáfora o flujo de trabajo diferente.
2. Mantenlo ligero: revisa las transcripciones en busca de instrucciones que hagan perder tiempo y elimina las partes que no ayuden.
3. Explica por qué: los LLM tienen teoría de la mente y pueden generalizar.
4. Encuentra trabajo redundante: si cada subagente está escribiendo create_docx.py de forma independiente, agrégalo a scripts/.

La primera versión nunca es perfecta.

Un caso real de iteración: la skill /daily de un autor tardó 6 versiones en estabilizarse.

• v1: Pasos poco claros, rutas incorrectas.
• v2: Se agregó integración con el sistema de descubrimiento de contenido.
• v3: Se corrigieron errores en el cálculo del progreso semanal.
• v4: Se agregaron activaciones automáticas (recordatorios los martes, archivado a fin de mes).
• v5: Se agregó el modo claro de iPhone (saltando pasos de Python en móvil).
• v6: Finalmente "buena de usar".

Una Skill no es un archivo de configuración que se ajusta y se olvida; es un documento vivo de tu flujo de trabajo.

8. ¿Cuándo deberías crear una Skill?

No todo merece una Skill. Actúa solo cuando aparezca una de estas tres señales:

Por el contrario: cuándo NO crear una

• Tareas únicas: solo usa un prompt.
• Sobre-encapsulación: dividir Skills después de solo tres usos; los costos de mantenimiento superan los beneficios.
• Buscar la perfección: intentar que la v1 sea perfecta; descubrirás que las necesidades eran imaginarias una vez que realmente la usas.

9. Lista de verificación de errores

10. Ecosistema y lista imprescindible

Mapa de recursos de Skills

Lista de Skills imprescindibles

11. Potencial comercial de las Skills

Las Skills son más que herramientas de eficiencia personal; están redefiniendo cómo se producen las aplicaciones de IA.

En el pasado, desarrollar una aplicación vertical de IA requería ciclos largos, costos altos y equipos técnicos. Ahora:

• Umbral sin código: construye Agentes verticales sin programar.
• Validación rápida: los ciclos de desarrollo se comprimen de semanas a minutos.
• Servicio de API: empaqueta una Skill como una API para potenciar productos existentes.
• Skills como productos: similar a vender colecciones de prompts, pero con mayor valor.

Casos reales:

• Article-Copilot: una sola Skill para toda la cadena, desde la limpieza de material hasta la escritura.
• AI Partner Skill: brinda a los Agentes generales memoria profunda para convertirse en verdaderos compañeros.
• Interview Prep Skill: genera informes completos basados en empresa/puesto/currículum. Alguien la usó para obtener una entrevista en Hithink RoyalFlush.
• El método de Super Huang: docenas de Skills + tareas cron que ejecutan informes cada hora mientras él duerme.

Cualquiera que esté inmerso en una industria puede destilar su experiencia en una Skill para ahorrar tiempo o venderla como producto.

Conclusión

Si un Agente es el cuerpo del mundo de la IA, una Skill es el alma que se le inyecta.

Es como la relación entre Steam y el Taller; la arquitectura extensible da a los juegos vida infinita.

Las Skills no son difíciles: son solo Markdown con algo de estructura. Pero la tendencia que representan es vital: la IA pasando de "tienes que enseñarle cada vez" a "solo le enseñas una vez".

Y el estándar es abierto. La Skill que escribes hoy para Claude Code se puede mover a Cursor o Gemini mañana.

Para los que aún miran desde fuera:

Las Skills no se diseñan; surgen del trabajo repetido.

Ejecuta una cosa primero, luego encapsúlala. Los buenos flujos de trabajo se iteran, no se planifican.

Abre tu terminal, instala skill-creator y convierte ese párrafo que has repetido tres veces hoy en tu primer SKILL.md.