Guía completa para principiantes sobre Agent Skills: Crea tu primera habilidad

Todo el que trabaja con IA se ha enfrentado a este problema:

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

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

Guardas indicaciones en tus notas y las 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 se debería usar la IA?

Skill nació específicamente 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, indicaciones, 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: Skills no están vinculados 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.

El Skill que escribas hoy se puede mover sin problemas a otro Agente mañana; tu inversión no quedará bloqueada 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 se aplican a todas las herramientas de IA que admiten Agent Skills.

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

1. ¿Qué es Exactamente un Skill?

Definición en una frase:

Un Skill es una carpeta, centrada en un archivo Markdown llamado SKILL.md, que le dice 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 un cierto tipo de cosa" en un módulo de capacidad reutilizable y activado automáticamente.

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

La IA general es como una máquina básica: inteligente pero carente de conocimiento de dominio. Un Skill es un módulo plug-and-play: instala un "Skill de Estilo Xiaohongshu", y la IA se convierte inmediatamente en un editor que entiende tu marca; instala un "Skill de Informe Semanal", y la IA genera inmediatamente informes 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 un Agent Skill, no un script exclusivo de Claude.

Límites con otros cuatro conceptos:

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

Analogías comunes:

• Indicación = Enviar un mensaje de WeChat a un empleado; lo olvidan 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 toma de decisiones; un Skill es solo una parte de él.

Estos cuatro no son mutuamente excluyentes.

En el trabajo real, a menudo se combinan: MCP permite que Claude se conecte a Reddit para extraer datos, un 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 evitar 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 un Skill es la carga de tres capas, que es la razón por la que una docena de Skills pueden coexistir sin saturar el contexto:

Por ejemplo:

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

Este mecanismo te permite tener 17 Skills activos 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 L1 es la más crítica: determina si tu Skill se activará.

Hechos clave:

1. Claude solo lee las descripciones de todos los Skills al inicio.
2. Hace juicios semánticos basados en la descripción, no en la coincidencia de palabras clave.
3. Claude tiende a ser conservador: si no está seguro, no se activa. En las 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 de activación tanto en chino como en inglés: Coincide con lo que sea que diga el usuario.
3. Sé insistente en lugar de conservador: Anthropic afirma explícitamente que el principal problema es la falta de activación.

3. Principios Centrales para Escribir Buenos Skills

Tres Principios Principales

Cómo manejar la libertad:

Cinco Patrones de Diseño

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

Los Skills útiles a menudo mezclan 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"

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

"Intenta explicarle al modelo por qué las cosas son importantes en lugar de usar un montón de DEBES pesados."

Ejemplo negativo:

[Reglas estrictas de 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 arriesgado), se queda atascado. En el segundo caso, Claude entiende "por qué la seguridad es importante" y se inclinará hacia la precaución incluso en áreas grises.

Las razones permiten que el modelo generalice; las reglas solo cubren escenarios en los que puedas pensar. 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 genera inconsistencias cuando actualizas un lugar pero olvidas el otro.

Archivos a Evitar

Los Skills son para la IA, no para los humanos. No agregues README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md o CHANGELOG.md. Estos documentos humanos solo desperdician contexto.

4. Construyendo tu Primer Skill

Los Seis Pasos Oficiales de Anthropic

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

1. Capturar la Intención: Aclarar qué hacer / cuándo activar / formato de salida / necesidades de prueba.
2. Entrevista e Investigación: Casos límite / formatos de E/S / 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) lado a lado para una comparativa.
6. Iterar: Modificar según los comentarios y volver a ejecutar hasta que esté satisfecho.

Cuatro Vías Rápidas para Usuarios Regulares

skill-creator: El Meta-Skill para Escribir Skills

Recomiendo encarecidamente instalar primero el skill-creator oficial de Anthropic. Es un Skill diseñado 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:

• Evaluar: Generar automáticamente casos de prueba para verificar si el Skill se activa correctamente.
• Mejorar: Optimizar automáticamente las descripciones e instrucciones basándose en los resultados de las pruebas, utilizando una división 60/40 de entrenamiento/prueba para evitar el sobreajuste.
• Comparar: Rastrear las tasas de éxito y el uso de tokens, incluso ejecutando pruebas A/B entre dos versiones.

Un Ejemplo Mínimo

Supongamos que eres un blogger 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 "convertir a versión Xiaohongshu" lo activará automáticamente.

Desde crear el archivo hasta usarlo toma 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 de un proyecto, mantenlos 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 (Recalcado)

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

Importancia operativa: 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 Dolorosos para Usuarios Nacionales

• 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 Central: Una tarea clara por Skill. No hagas un "Skill universal".

Si la granularidad es demasiado gruesa, la descripción se vuelve confusa y las activaciones son imprecisas. Si es demasiado fina, los costos de gestión aumentan. Una granularidad razonable es un 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 Escritura de Blogs

No hagas un "Skill de Escritura Todo en Uno". Divídelo en 5 Skills colaborativos:

Modo de colaboración: El Skill principal llama explícitamente a otros Skills en su sección ## Pasos.

Beneficios de esta división:

Cinco Experiencias de Ingeniería

1. Granularidad fina: Una tarea clara por Skill.
2. Colaboración explícita: Usa ## Pasos en el Skill principal para llamar a otros.
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: Pon 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 de línea base para que la salida no se desvíe demasiado.

7. Evaluación Profesional e Iteración

Sistema de Evaluación:

El proceso estándar de skill-creator:

1. Escribe indicaciones 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 sobre pass_rate / time / 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 deberían).
• Dificultad: "Casi aciertos" para las que no deberían activar—consultas que comparten palabras clave pero necesitan otras herramientas.
• Script de optimización: 60% entrenamiento + 40% prueba reservada para evitar el sobreajuste.
• Ejecuta 5 rondas y elige la descripción con la puntuación de prueba más alta.

Buenos ejemplos de activaciones: No escribas solo "extraer tabla PDF"; escribe como un usuario real:

"vale, mi jefe me acaba de enviar este archivo xlsx (está en mis descargas, se llama algo así como 'Q4 sales final FINAL v2.xlsx') y quiere que añada 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 pierdan el tiempo y elimina las partes que no ayudan.
3. Explica por qué: Los LLM tienen una 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 de iteración real: La skill /daily de un autor tardó 6 versiones en estabilizarse.

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

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

8. ¿Cuándo Deberías Hacer un Skill?

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

Por el contrario: Cuándo NO hacer uno

• Tareas únicas: Solo usa una indicación.
• Sobreenvasado: 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 lo uses.

9. Lista de Verificación de Errores

10. Ecosistema y Lista de Imprescindibles

Mapa de Recursos de Skills

Lista de Skills Imprescindibles

11. Potencial Comercial de los Skills

Los 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 de IA vertical requería ciclos largos, costos altos y equipos técnicos. Ahora:

• Umbral de código cero: Construye Agentes verticales sin programar.
• Validación rápida: Ciclos de desarrollo comprimidos de semanas a minutos.
• Servicio API: Empaqueta un Skill como una API para potenciar productos existentes.
• Skills como productos: Similar a vender colecciones de indicaciones, pero con mayor valor.

Casos reales:

• Article-Copilot: Un solo Skill para toda la cadena, desde la limpieza de materiales hasta la escritura.
• Skill de Compañero de IA: Da a los Agentes generales una memoria profunda para convertirse en verdaderos compañeros.
• Skill de Preparación de Entrevistas: Genera informes completos basados en empresa/puesto/currículum. Alguien usó esto para conseguir una entrevista en Hithink RoyalFlush.
• Método de Super Huang: Docenas de Skills + trabajos cron que ejecutan informes por horas mientras él duerme.

Cualquier persona con experiencia en una industria puede destilar su conocimiento en un Skill para ahorrar tiempo o venderlo como producto.

Conclusión

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

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

Los 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. El Skill que escribas para Claude Code hoy se puede mover a Cursor o Gemini mañana.

Para aquellos que aún están mirando:

Los 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.