Skills para Claude Code: una carpeta, tres agentes IA
TL;DR: Una skill es una carpeta con un archivo SKILL.md. Ese formato funciona sin cambios en Claude Code (~/.claude/skills/), Codex CLI (~/.codex/skills/) y Antigravity CLI (~/.agents/skills/). Con un symlink de sistema operativo, editas el archivo una sola vez y los tres agentes ven el mismo contenido actualizado al instante.
¿Qué es una skill para agentes IA de línea de comandos?
Una skill es un bloque de instrucciones especializadas que le das a un agente IA para que sepa cómo comportarse en un dominio concreto. En lugar de repetir el mismo contexto en cada conversación, defines el comportamiento una vez y el agente lo carga automáticamente cada vez que arranca.
El formato es simple: una carpeta con un archivo SKILL.md dentro. Nada más es obligatorio. El resto (scripts, ejemplos, referencias) es opcional.
Lo relevante es que Claude Code, Codex CLI y Antigravity CLI comparten este estándar. El agente lee el name y la description de todas tus skills al arrancar (unos 100 tokens por skill), y solo carga el contenido completo cuando decide que esa skill es relevante para la tarea en curso. Esto se llama divulgación progresiva y es lo que hace que tener varias skills no penalice el rendimiento.
Una aclaración importante antes de continuar: esta guía usa las rutas de Antigravity CLI (
~/.agents/skills/), que es la herramienta actual. No confundir con Gemini CLI (~/.gemini/skills/), una versión anterior que todavía aparece en muchas guías en línea.
Estructura de una skill
saludo-prueba/
├── SKILL.md ← OBLIGATORIO
├── scripts/ ← Opcional: código ejecutable
├── references/ ← Opcional: documentación bajo demanda
├── examples/ ← Opcional: implementaciones de referencia
└── assets/ ← Opcional: plantillas y recursosEl archivo SKILL.md tiene dos secciones:
1. Frontmatter YAML
---
name: saludo-prueba
description: |
Skill de demostración. USE FOR: probar que las skills cargan correctamente
en Claude Code, Codex CLI y Antigravity CLI. DO NOT USE FOR: tareas de
producción reales.
---Dos campos son obligatorios:
name: solo minúsculas, números y guiones; máximo 64 caracteres; debe coincidir exactamente con el nombre de la carpeta. Si la carpeta se llamasaludo-prueba, elnamedebe sersaludo-prueba. Un mismatch silencia la skill sin mensaje de error.description: máximo 1024 caracteres. Es el campo más crítico porque el agente lo lee al inicio de cada sesión para decidir si la skill aplica. Incluir explícitamente patronesUSE FOR:/DO NOT USE FOR:acelera esa decisión.
2. Cuerpo en Markdown
Después del frontmatter, escribes las instrucciones en Markdown libre. Aquí van las reglas de comportamiento, los pasos de un proceso, los comandos disponibles, o cualquier contexto que el agente deba conocer cuando active esta skill.
Regla de portabilidad
Si usas solo name, description y Markdown plano, tu skill funciona en los tres agentes sin modificación. Los campos específicos de un agente son ignorados por los demás sin errores.
Rutas donde busca cada agente
Estas son las rutas para un usuario en Windows:
| Agente | Ruta de skills |
|---|---|
| Claude Code | %USERPROFILE%\.claude\skills\ |
| Codex CLI | %USERPROFILE%\.codex\skills\ |
| Antigravity CLI | %USERPROFILE%\.agents\skills\ |
En Git Bash: ~/.claude/skills/, ~/.codex/skills/, ~/.agents/skills/.
El problema con estas tres rutas separadas: si copias la carpeta de la skill en las tres, tienes tres versiones independientes. En cuanto editas una, las otras quedan desactualizadas.
La solución es crear una sola carpeta real y enlaces simbólicos desde cada ruta de agente hacia ella.
Cómo crear la fuente de verdad única
Paso 1 — Crear el directorio fuente
Abre Git Bash y ejecuta:
mkdir -p ~/skills-vault/saludo-pruebamkdir -p crea toda la cadena de carpetas de una vez, sin error si ya existen. Aquí creamos skills-vault como tu repositorio personal de skills, y dentro saludo-prueba como la primera.
Paso 2 — Crear el SKILL.md
cat > ~/skills-vault/saludo-prueba/SKILL.md << 'EOF'
---
name: saludo-prueba
description: |
Skill de demostración que verifica que el sistema de skills funciona.
USE FOR: comprobar carga de skills, pruebas de instalación.
DO NOT USE FOR: tareas de producción.
version: "1.0"
---
# Skill de saludo y prueba
Cuando esta skill está activa, responde con:✅ SKILL «saludo-prueba» v1.0 ACTIVADA Hola, [nombre del usuario]. El sistema de skills funciona correctamente.
Confirma siempre la versión para verificar que el symlink está activo.
EOFVerifica que el archivo existe:
ls ~/skills-vault/saludo-prueba/
# Debe mostrar: SKILL.mdPunto crítico: a partir de ahora,
~/skills-vault/saludo-prueba/es la única carpeta que editas. Las entradas en.claude,.codexy.agentsserán enlaces, no carpetas reales. Si creas una carpeta independiente en alguna de esas rutas, romperás la sincronización y tendrás tres versiones distintas sin saberlo.
Paso 3 — Crear los symlinks en Windows
Los symlinks de carpeta en Windows requieren permisos de administrador (o el Modo de desarrollador activado en Configuración → Privacidad y seguridad → Para desarrolladores).
Opción A: CMD como Administrador (más fiable)
Abre CMD con clic derecho → «Ejecutar como administrador» y ejecuta:
mkdir "%USERPROFILE%\.agents\skills"
mklink /D "%USERPROFILE%\.agents\skills\saludo-prueba" "%USERPROFILE%\skills-vault\saludo-prueba"
mkdir "%USERPROFILE%\.claude\skills"
mklink /D "%USERPROFILE%\.claude\skills\saludo-prueba" "%USERPROFILE%\skills-vault\saludo-prueba"
mkdir "%USERPROFILE%\.codex\skills"
mklink /D "%USERPROFILE%\.codex\skills\saludo-prueba" "%USERPROFILE%\skills-vault\saludo-prueba"Aviso sobre el orden de argumentos — es la causa número uno de errores:
| Herramienta | Orden |
|---|---|
ln -s (Git Bash) |
ln -s ORIGEN ENLACE |
mklink /D (CMD) |
mklink /D ENLACE ORIGEN |
Son al revés. mklink también requiere que la carpeta padre exista; por eso el mkdir va antes.
Opción B: Git Bash (requiere Modo de desarrollador)
export MSYS=winsymlinks:nativestrict
mkdir -p ~/.agents/skills ~/.claude/skills ~/.codex/skills
ln -s ~/skills-vault/saludo-prueba ~/.agents/skills/saludo-prueba
ln -s ~/skills-vault/saludo-prueba ~/.claude/skills/saludo-prueba
ln -s ~/skills-vault/saludo-prueba ~/.codex/skills/saludo-pruebaSin la variable MSYS=winsymlinks:nativestrict, Git Bash en Windows puede copiar el archivo en lugar de enlazarlo, que es exactamente lo que queremos evitar.
Paso 4 — Verificar que son enlaces y no copias
En CMD:
dir "%USERPROFILE%\.agents\skills"
dir "%USERPROFILE%\.claude\skills"
dir "%USERPROFILE%\.codex\skills"En la salida debe aparecer <SYMLINKD> junto al nombre de la carpeta:
29/05/2026 10:00 <SYMLINKD> saludo-prueba [C:\Users\...\skills-vault\saludo-prueba]Si aparece <DIR> en lugar de <SYMLINKD>, es una carpeta real, no un enlace. Bórrala y repite el paso anterior.
Probar que los tres agentes leen la misma skill
-
Reinicia la sesión de cada agente. Es el paso más olvidado: los agentes indexan las skills al arrancar, no en caliente.
-
En cada agente escribe: «prueba la skill de saludo» o «activa la skill saludo-prueba». Una frase ambigua como «hola» puede no activarla porque el agente la resuelve sin skills.
-
Los tres deben responder con el marcador
✅ SKILL "saludo-prueba" v1.0 ACTIVADA.
Prueba definitiva de sincronización
Edita solo la fuente:
# Cambia v1.0 → v1.1 en la fuente
sed -i 's/v1.0/v1.1/g' ~/skills-vault/saludo-prueba/SKILL.mdReinicia los tres agentes y vuelve a activar la skill. Si los tres responden con v1.1 sin que hayas tocado nada en .claude, .codex ni .agents, el enlace está funcionando correctamente.
Errores comunes y cómo resolverlos
| Error | Causa | Fix |
|---|---|---|
| La skill no aparece al arrancar | name en frontmatter no coincide con el nombre de la carpeta |
Verificar que name: saludo-prueba y la carpeta se llamen igual |
mklink devuelve «El sistema no puede encontrar la ruta» |
La carpeta padre no existe | Ejecutar mkdir antes del mklink |
| El enlace crea una copia en lugar de un symlink | Git Bash sin MSYS=winsymlinks:nativestrict |
Exportar la variable o usar CMD como Administrador |
Aparece <DIR> en lugar de <SYMLINKD> |
Se creó una carpeta real, no un enlace | Borrar la carpeta y repetir con permisos de administrador |
| La skill se activa pero muestra versión antigua | Agente no reiniciado | Cerrar y abrir la sesión del agente |
mklink requiere Administrador |
Sin permisos de admin ni Modo de desarrollador | Activar Modo de desarrollador o ejecutar CMD como admin |
Resumen: la lista de verificación completa
[ ] Carpeta fuente creada en ~/skills-vault/nombre-skill/
[ ] SKILL.md con name igual al nombre de la carpeta
[ ] description incluye USE FOR: / DO NOT USE FOR:
[ ] mkdir antes de mklink para cada agente
[ ] mklink /D con orden ENLACE → ORIGEN (no al revés)
[ ] CMD ejecutado como Administrador
[ ] dir muestra <SYMLINKD> (no <DIR>)
[ ] Agentes reiniciados tras crear los enlaces
[ ] Prueba con frase explícita de activación
[ ] Editar SIEMPRE en ~/skills-vault/, nunca en .claude/.codex/.agentsEscalar: agregar más skills al vault
Una vez que tienes la estructura, añadir una nueva skill es siempre el mismo patrón:
# 1. Crear en el vault
mkdir ~/skills-vault/mi-nueva-skill
# (crear SKILL.md dentro)
# 2. Enlazar en los tres agentes (CMD como admin)
mklink /D "%USERPROFILE%\.agents\skills\mi-nueva-skill" "%USERPROFILE%\skills-vault\mi-nueva-skill"
mklink /D "%USERPROFILE%\.claude\skills\mi-nueva-skill" "%USERPROFILE%\skills-vault\mi-nueva-skill"
mklink /D "%USERPROFILE%\.codex\skills\mi-nueva-skill" "%USERPROFILE%\skills-vault\mi-nueva-skill"Con el tiempo, ~/skills-vault/ se convierte en tu repositorio personal de conocimiento para agentes IA: puedes versionarlo con Git, compartirlo con un equipo, o hacer backup sin coordinar tres carpetas distintas.
Deja una respuesta