📄 Qué es una agent skill
Una agent skill es, en la práctica, un único archivo: SKILL.md. Tiene dos partes: un frontmatter YAML con los campos obligatorios name e description, y un cuerpo en Markdown con la instrucción en sí. Cuando el contexto de la conversación coincide con la descripción, el agente lee ese archivo y incorpora la instrucción sobre el propio comportamiento, como si hubieras explicado la convención en ese momento.
💡 Concepto central
Una skill no es un plugin que ejecuta código. Es conocimiento empaquetado en texto que el agente empieza a «saber». El canónico aquí es el skill-creator de Anthropic, que define la estructura SKILL.md como estándar.
- •Formato: Markdown con frontmatter YAML
- •Obligatorios: name + description
- •Activación: automática, según la relevancia del contexto
- •Distribución: versionada vía git, instalable vía skills.sh
SKILL.md mínimo:
--- name: react-best-practices description: Aplica boas práticas React ao gerar ou revisar componentes. Use quando o usuário cria ou edita arquivos .jsx/.tsx. --- # React Best Practices Ao gerar componentes React, sempre: - Use componentes funcionais com hooks - Prefira TypeScript com tipos explícitos - Siga nomenclatura PascalCase para componentes
🎯 Consejo práctico
Piensa en una skill como la memoria persistente del agente. Sin ella, tienes que volver a explicar las convenciones en cada sesión. Con ella, el agente ya las conoce, y el conocimiento queda en un archivo que comparte todo el equipo.
🧠 Instrucción, no script
El error más común de quienes vienen de la programación es tratar la skill como una función. Una skill no ejecuta — se lee. No hay una «llamada»; se activa según el contexto. El agente compara la situación actual con la description de cada skill instalada y, cuando es relevante, aplica la instrucción. Tú describes qué e cuándo, no los pasos mecánicos.
✗ Pensar como un script
- ✗"Paso 1, paso 2, paso 3..." rígido
- ✗Espera que la skill "se ejecute" y devuelva
- ✗Description vaga ("ayuda con código")
- ✗Asume un control de flujo determinista
✓ Pensar como una instrucción
- ✓Describe el comportamiento y el porqué
- ✓Confía en que el agente la aplique en el momento adecuado
- ✓La Description dice QUÉ hace Y CUÁNDO usarla
- ✓Deja espacio para el criterio del agente
La description es el activador
Como la activación depende del contexto, la description es literalmente lo que decide si la skill se activa. Debe decir qué hace e cuándo usar, y ser incluso un poco "pushy": los agentes tienden a activar las skills menos de lo debido.
Por eso, el cuerpo de la skill debe explicar el por qué de las cosas, en vez de amontonar MUST en mayúsculas. Las instrucciones con una razón se siguen mejor que las órdenes secas.
🏆 Por qué se impuso el formato
Había muchas maneras de enseñar comportamiento a un agente: archivos propietarios, configuraciones específicas, plugins binarios. Lo que se impuso fue lo más simple: Markdown puro. Por tres razones que se refuerzan entre sí: portabilidad entre agentes, control de versiones vía git y un efecto de red medido en millones de instalaciones.
Portable entre más de 50 agentes
Markdown es el mínimo común denominador. Una skill escrita una vez funciona en Claude Code, Cursor, Copilot, Codex y decenas de herramientas más. Tu inversión no queda atada a una herramienta.
Se puede versionar mediante git
Por ser texto, la skill se integra al flujo de trabajo que los equipos ya dominan: PRs, diffs, revisión, historial. ¿Cambió la convención? Es un commit. Nada de formatos binarios opacos.
53,9M de installs en total
El efecto de red ya ocurrió: skills.sh suma 53,9 millones de instalaciones. Cuando todos publican en el mismo formato, el formato se convierte en el estándar de facto y se refuerza a sí mismo.
💡 Por qué esto te importa
Escribir una skill es una de las pocas cosas en IA con bajo riesgo de "vendor lock-in". El artefacto es un .md. Si la herramienta cambia mañana, tu skill sigue siendo válida.
🔀 Skill vs prompt vs CLAUDE.md vs MCP vs subagente
Una skill no reemplaza las otras capas: convive con ellas. El error es convertir todo en una skill o no convertir nada. Cada mecanismo resuelve un problema distinto. La tabla mental de abajo te ayuda a elegir.
💬 Prompt
Efímero, solo sirve para ese mensaje. Úsalo para algo puntual que no vas a repetir. No escala ni se versiona.
📌 CLAUDE.md (reglas del proyecto)
Contexto siempre activa de ese repositorio. Úsalo para reglas que se aplican en todas las sesiones del proyecto. Consume tokens todo el tiempo; por eso, incluye solo lo esencial.
🔌 MCP
Le da al agente herramientas y datos (llamar a una API, leer una base de datos). Es capacidad, no conocimiento. La skill indica cómo actuar; MCP proporciona qué usar.
🤖 Subagente
Uno ejecutor aislado con su propio contexto, para delegar una tarea pesada sin saturar la conversación principal. Es arquitectura de ejecución, no una instrucción reutilizable.
🧩 Skill
Conocimiento reutilizable que se activa según el contexto. Úsala cuando haya un comportamiento que se repita en muchas situaciones y convenga cargarlo solo cuando sea relevante, sin ocupar contexto todo el tiempo (a diferencia de CLAUDE.md).
Regla práctica para elegir:
é só desta vez? -> prompt vale sempre, neste repo? -> CLAUDE.md preciso de uma ferramenta? -> MCP quero delegar execução? -> subagente conhecimento que se repete? -> skill
💡 Atención al costo de contexto
La gran ventaja de la skill sobre el CLAUDE.md es el carga bajo demanda: solo name+description permanece siempre en el contexto; el cuerpo entra únicamente cuando se activa la skill. El conocimiento extenso que no siempre se necesita debería convertirse en una skill, no en una regla del proyecto.
📦 skills.sh como registry — el "npm de skills"
Si la skill es el «paquete», el skills.sh es el registry — el npm de este mundo. Cataloga skills por repositorio y muestra la recuento de instalaciones (la mejor señal pública de calidad y confianza) y se instala con un comando.
📦 npm (Node.js)
- →
npm install react— instala un paquete - →descargas/semana — señal de adopción
- →registro central (npmjs.com)
- →package.json — registro local
🧩 skills.sh (agentes)
- →
npx skills add owner/repo— instala una skill - →install count — señal de adopción
- →catálogo central (skills.sh)
- →repos en GitHub — fuente versionada
Flujo de uso del catálogo:
# 1. descobrir no leaderboard / buscar npx skills find react # 2. instalar pelo caminho owner/repo npx skills add vercel-labs/skills # 3. listar o que está instalado npx skills list
El número de instalaciones es tu indicador de calidad
Como en cualquier registry abierto, junto a las skills excelentes hay muchas de baja calidad. La cantidad de instalaciones es el filtro más sencillo: la skill más instalada del catálogo, find-skills (vercel-labs/skills), tiene 1.802.925 instalaciones. frontend-design (anthropics/skills) tiene 488.299.
No es una prueba de calidad, pero sí un fuerte indicador de que mucha gente confió en ella y la siguió usando.
👥 Quién publica
El ecosistema no es un jardín amurallado de una sola empresa. Publican grandes empresas y miles de personas de la comunidad: en total 5.075 repos fuente alimentan el catálogo. Esto es lo que le da fuerza al formato: nadie es su dueño.
🟢 vercel-labs
Creadora de skills con más instalaciones como find-skills (1,8M), vercel-react-best-practices (443k) e web-design-guidelines (358k). Enfoque en web/frontend y herramientas para agentes.
🟢 anthropics
Publica el skill-creator (246k) — el canónico sobre cómo escribir skills — y frontend-design (488k). Es la referencia de estructura del formato.
🟢 microsoft
Con azure-skills, domina DevOps/Cloud: microsoft-foundry (360k), azure-ai (358k) y la familia azure-deploy/diagnostics/prepare.
🟢 comunidad
La mayoría de los repos. Ejemplos: obra/superpowers (test-driven-development, 107k), larksuite/cli (lark-slides, 139k), supabase, stripe, coreyhaines31.
Anatomía de una ruta de skill en el catálogo:
vercel-labs/skills # repo fonte (owner/repo) └── find-skills # a skill (1.802.925 installs) └── SKILL.md # o arquivo de instrução
💡 Qué te dice esto
Los grandes nombres dominan los temas más populares (web, cloud, agentes). Queda muchísimo espacio en los nichos que no cubren, y es justo donde tu skill de la comunidad puede liderar. El mapa completo es el tema del Módulo 1.2.
✅ Resumen del módulo
Próximo:
1.2 — 🗺️ El mapa de skills.sh: 39k skills, la ley de potencia y los 16 grupos. Dónde están las oportunidades y por qué casi nadie instala la mayoría de las skills.