Las skills de Claude Code son carpetas con un archivo SKILL.md que enseñan a Claude una tarea repetible, como revisar un PR o preparar una release, y Claude solo carga una cuando tu petición la necesita. Eso convierte a las skills en el lugar adecuado para instrucciones que importan en algunas tareas pero no en todas las sesiones. La pega es que una skill son instrucciones que tu agente va a seguir, así que una skill de internet merece el mismo cuidado que un script de internet.
Este artículo cubre el formato de las skills, dónde viven, cómo las elige Claude, cómo escribir una buena y cómo encontrar e instalar skills compartidas sin darle a tu agente algo peligroso.
Qué es una skill de Claude Code
Una skill es una carpeta. El único archivo obligatorio es SKILL.md:
---
name: release-notes
description: Use when the user asks for release notes or a changelog entry for a version.
---
1. Run `git log --oneline <last-tag>..HEAD`.
2. Group the commits into Features, Fixes and Other.
3. Write one plain sentence per change, for users, not developers.
4. Ask before writing to CHANGELOG.md.El frontmatter contiene el name y la description. El cuerpo es la instrucción que Claude sigue una vez cargada la skill. La carpeta también puede contener scripts y archivos de referencia a los que apuntan las instrucciones, de modo que una skill puede decir «ejecuta scripts/check.sh» o «lee reference/api.md para la lista de endpoints».
Dónde viven las skills de Claude Code
| Ubicación | Quién la tiene | Uso típico |
|---|---|---|
.claude/skills/<name>/SKILL.md | Todos los que trabajan en el repositorio, mediante git | Flujos del proyecto: deploy, migraciones, release |
~/.claude/skills/<name>/SKILL.md | Tú, en todos los proyectos | Hábitos personales: tu lista de revisión, estilo de commits |
El nombre de la carpeta se convierte en el comando, así que .claude/skills/release-notes/SKILL.md también se puede ejecutar como /release-notes. Escribe /skills en una sesión para listar las skills que ve Claude. Para el resto de los comandos slash, consulta la chuleta de comandos de Claude Code.
Cómo decide Claude usar una skill
Al empezar una sesión, Claude ve las descripciones de las skills, no su cuerpo completo. Cuando tu petición coincide con una descripción, carga esa skill. De ahí se derivan dos cosas:
- La descripción hace el enrutamiento. «Skill de notas de versión» es una descripción débil. «Use when the user asks for release notes or a changelog entry for a version» le dice a Claude cuándo recurrir a ella.
- Las skills mantienen pequeño tu contexto base. Solo las descripciones se cargan en cada sesión, así que sacar de
CLAUDE.mdlas instrucciones específicas de una tarea y pasarlas a skills aligera cada turno. Más sobre esto en la ventana de contexto de Claude Code.
Skills, CLAUDE.md, subagentes y MCP
Estas cuatro se solapan, así que conviene saber cuál encaja.
| Herramienta | Se carga | Ideal para |
|---|---|---|
CLAUDE.md | En cada sesión, el archivo entero | Reglas que siempre se aplican |
| Skill | La descripción siempre, el cuerpo bajo demanda | Un flujo que repites de vez en cuando |
| Subagente | Al delegar, en su propio contexto | Trabajo pesado cuyos detalles no necesitas de vuelta |
| Servidor MCP | Las definiciones de herramientas en cada sesión | Acceso a sistemas o datos externos |
Si pegas el mismo párrafo en tus prompts dos veces por semana, debería ser una skill. Si necesitas que el agente hable con una base de datos o una API, eso es un servidor MCP (qué es un servidor MCP).
Cómo escribir una buena skill
- Parte de una tarea que ya repites. Anota los pasos que escribes hoy.
- Escribe la descripción como un disparador. Empieza con «Use when…» y nombra las palabras que diría un usuario.
- Mantén el cuerpo corto y ordenado. Los pasos numerados ganan a los párrafos.
- Pon el material largo en archivos. Una tabla de referencia o un script va junto a
SKILL.md, y el cuerpo dice cuándo leerlo o ejecutarlo. - Di qué no hacer. «Ask before writing to CHANGELOG.md» evita la sorpresa que de otro modo arreglarías a mano.
- Pruébala en una sesión nueva. Pide la tarea con tus propias palabras y comprueba que Claude elige la skill sin que se lo digas.
El riesgo de las skills compartidas
Compartir skills es donde se vuelven útiles, y arriesgadas. Una skill puede decirle a tu agente que ejecute un comando de shell, lea un archivo fuera del proyecto o envíe algo a una URL. Si tu agente se ejecuta con permisos amplios, una skill maliciosa o descuidada se ejecuta con ellos también. Cosas que buscar antes de instalar una:
- Comandos destructivos o privilegiados (
rm -rf,sudo) - Lectura de secretos, como archivos
.envo claves SSH - Envío de datos a un host que no conoces
- Patrones de descarga y ejecución, como pasar
curla un shell - Código ofuscado o caracteres Unicode ocultos
- Inyección de prompts: texto que intenta anular tus instrucciones
El artículo sobre seguridad de los agentes de programación con IA cubre los permisos y el sandboxing con más profundidad.
Gestionar skills en AgentVera
La galería de skills de AgentVera está en la página Details de un proyecto, Automation → Skills. Tiene tres vistas: Local, Discover y My published.
Local lista las skills de tu ordenador para los dos agentes que usan carpetas de skills:
| Agente | Carpeta del proyecto | Carpeta personal |
|---|---|---|
| Claude Code | .claude/skills | ~/.claude/skills |
| Codex | .agents/skills | ~/.codex/skills |
Desde ahí puedes:
- Crear una con New skill: elige el Agent (Claude Code o Codex), el Scope (This project o All projects), un Name (letras minúsculas, dígitos y guiones) y When should it be used?, que se convierte en la descripción. Create and edit abre el nuevo
SKILL.md. - Desactivar una skill sin borrarla. El interruptor mueve la carpeta a un lugar que las CLI no escanean.
- Previsualizar o editar
SKILL.md, copiar una skill al otro agente o ámbito, o eliminarla, lo que mueve la carpeta a la Papelera.
Encontrar e instalar skills con seguridad
Discover muestra las skills de tu organización y la galería pública. Busca, elige una de las 10 categorías (programación, testing, revisión de código, DevOps, datos, documentación, diseño, seguridad, productividad, otros), filtra por agente y ordena por Popular o New. La misma galería está en la web en app.agentvera.dev/skills.
La vista de detalle de cada skill tiene las pestañas Files, Security y Versions. La pestaña Security muestra el Server scan. El escaneo busca comandos destructivos o privilegiados, lectura de secretos, claves incrustadas, datos enviados al exterior, descarga y ejecución, código ofuscado, inyección de prompts, Unicode oculto, direcciones IP en bruto y hosts externos. Los resultados van desde limpio, pasando por info, riesgo bajo, medio y alto, hasta crítico.
Instalar son dos pasos:
- Download and scan. AgentVera descarga los archivos, verifica su SHA-256 y los vuelve a escanear en tu ordenador.
- Install. Los scripts se escriben como archivos normales y no se hacen ejecutables.
Los agentes ven la skill en su siguiente sesión. Cuando se publica una versión nueva, aparece un botón de actualización junto a la skill instalada. Las skills de la galería solo se instalan para los agentes que las admiten, Claude Code y Codex.
Las skills públicas pasan un escaneo de seguridad y una revisión de moderadores, pero aun así revisa los hallazgos y los archivos. El escaneo detecta patrones; tú sabes lo que tu proyecto debe y no debe hacer.
Compartir tus propias skills
Con un plan Pro o Team y una cuenta de AgentVera, Share publica una skill local. Le das un título, un resumen de 20 a 300 caracteres, hasta 6 etiquetas, una categoría y una versión como 1.0.0, con un changelog por cada versión. Una skill está limitada a 50 archivos de texto, 256 KB por archivo y 1 MB en total.
- Solo la organización: visible de inmediato para tu organización si el escaneo no encuentra nada alto ni crítico; si no, se rechaza.
- Pública: espera la aprobación de un moderador, y los hallazgos críticos no se aceptan. Haz su seguimiento en My published.
Skills y consumo de tokens
Cada skill añade su descripción al contexto base. Un puñado está bien; decenas de skills personales se acumulan en cada turno. El perfil Lean context de AgentVera no carga skills de nivel de usuario, una de las razones por las que su primera petición es más pequeña (medido aquí). Mantén las skills del proyecto en el repositorio y poda las personales que ya no uses.
Resumen
Las skills de Claude Code convierten prompts repetidos en carpetas que Claude carga bajo demanda: un SKILL.md con una descripción clara de «use when», pasos cortos y ordenados y los scripts que necesite, en .claude/skills para el proyecto o en ~/.claude/skills para ti. Las skills compartidas solo valen la pena si las revisas antes. AgentVera lista las skills de Claude Code y Codex en un solo lugar, escanea las skills de la galería en el servidor y otra vez en tu ordenador antes de instalar, y permite a los usuarios Pro y Team publicar las suyas. Descarga AgentVera para gestionar tus skills.