Agent Skills: configura .claude/skills y .agents/skills

Para un repositorio compartido por Claude Code, Codex, Cursor y Gemini CLI, mantén los archivos de las habilidades en .agents/skills/<skill-name>/. Haz que Claude Code acceda a cada habilidad compartida mediante un enlace simbólico relativo a su directorio, ubicado en .claude/skills/. Después, comprueba la detección y la invocación en cada cliente antes de adoptar esta estructura en todo el equipo.

Esta configuración permite editar una sola copia del flujo de trabajo y adaptarse a las distintas reglas de búsqueda de los clientes. Si tu equipo solo utiliza Claude Code, puede conservar su estructura actual en .claude/skills/; mover los directorios resulta útil cuando otro cliente necesita utilizar las mismas habilidades.

¿AAIF ha estandarizado el nombre del directorio?

AAIF alberga el estándar, pero cada cliente sigue decidiendo dónde buscar habilidades. Anthropic anunció la donación el 22 de octubre de 2026, y la fundación dio la bienvenida a Agent Skills como proyecto alojado.

La guía de implementación para clientes deja explícitamente el directorio contenedor fuera de los requisitos de la especificación. Recomienda considerar .agents/skills/ para favorecer la interoperabilidad, junto al directorio propio de cada cliente. Esa recomendación no implica que todos los clientes existentes busquen habilidades en él.

La unidad portable es un directorio que contiene SKILL.md con un bloque inicial de metadatos YAML (frontmatter) e instrucciones en Markdown. La especificación del formato exige name y description; pueden acompañarlos recursos opcionales. La sintaxis de invocación, los entornos de ejecución de scripts y los permisos siguen dependiendo del cliente. En particular, allowed-tools continúa siendo experimental y su soporte varía entre implementaciones, por lo que no constituye una política de permisos portable.

¿En qué rutas buscan las cuatro herramientas?

Utiliza los directorios raíz documentados del sistema de archivos local que aparecen a continuación. Las rutas y los controles de esta guía reflejan la documentación oficial a fecha de 2026-10-26; añade <skill-name>/SKILL.md a cada raíz para obtener la estructura utilizada aquí.

Herramienta	Directorios raíz en el repositorio	Directorios raíz de usuario	Elección para un repositorio compartido
Claude Code	`.claude/skills/`	`~/.claude/skills/`	Añade un alias por habilidad desde `.claude/skills/` al directorio compartido.
Codex CLI y extensión para IDE	`.agents/skills/`	`~/.agents/skills/`	Lee directamente el directorio compartido.
Cursor Agent	`.agents/skills/`, `.cursor/skills/`; también `.claude/skills/` y `.codex/skills/` por compatibilidad	Los mismos cuatro nombres de directorio bajo `~/`	Utiliza `.agents/skills/`; no hace falta otro alias para Cursor.
Gemini CLI	`.agents/skills/` y `.gemini/skills/`	`~/.agents/skills/` y `~/.gemini/skills/`	Lee directamente `.agents/skills/`. Tiene prioridad sobre `.gemini/skills/` dentro del mismo ámbito.

La guía actual de Claude Code no enumera la detección nativa en .agents/skills/, y la solicitud de mejora #31005 sigue abierta. A su vez, las guías de Codex y Gemini citadas arriba no enumeran .claude/skills/ como raíz de búsqueda. Utiliza las rutas documentadas sin tratar ambos directorios como universalmente intercambiables.

Estas son rutas de detección local. Una habilidad guardada en el directorio personal de tu portátil no está disponible automáticamente en un worker remoto o en un contenedor recién creado; ese entorno también debe recibir los archivos.

Crea una habilidad compartida y un alias para Claude Code

Guarda la habilidad completa bajo .agents/skills/ y enlaza su directorio, incluidos los scripts o las referencias que añadas en el futuro. Un alias por habilidad también deja espacio para las habilidades existentes específicas de Claude.

Empieza con un cliente instalado y autenticado que ya pueda trabajar en tu repositorio, además de Git. Esta configuración del sistema de archivos no necesita nuevas credenciales de API; siguen aplicándose los requisitos normales de acceso al cliente y los permisos para usar herramientas.

Escribe la habilidad en el formato común

Crea .agents/skills/review-staged/SKILL.md en tu editor y, si es necesario, crea también los directorios que lo contienen. Si esa habilidad ya existe, elige otro nombre y actualiza de forma coherente el directorio, el frontmatter y los comandos.

Pega este archivo completo:

---
name: review-staged
description: "Review staged Git changes for correctness before a commit. Use when the user asks to review the Git index or staged changes."
---

Begin the answer with `Skill loaded: review-staged`.

1. Locate the repository root with `git rev-parse --show-toplevel`.
   Run all following commands from that directory.
2. Run `git diff --cached --name-only`. If it prints no paths,
   report `No staged changes.` and stop.
3. Run `git diff --cached --check` and `git diff --cached --`.
   Treat a nonzero `--check` exit as evidence to report, not a reason
   to skip reading the diff.
4. Read relevant files as needed. Report concrete correctness issues
   with file and line references. Separate confirmed issues from questions.
5. Finish with suggested verification commands. Do not claim they ran.

Do not edit files, stage changes, or create a commit.

El flujo de trabajo revisa el índice de Git: los cambios preparados para el próximo commit. La referencia de diff de Git documenta --cached para esa comparación y --check para detectar errores de espacios en blanco y marcadores de conflicto. El ejemplo pide al agente que ejecute comandos normales en vez de depender de mecanismos de expansión del prompt específicos de un cliente.

Añade el alias con Bash en macOS o Linux

Crea un enlace simbólico relativo para esta habilidad. Claude Code documenta explícitamente el soporte de directorios de habilidades enlazados simbólicamente.

Ejecuta lo siguiente en Bash, desde cualquier ubicación dentro del repositorio Git que quieras configurar:

(
  set -eu
  cd "$(git rev-parse --show-toplevel)"
  test -f .agents/skills/review-staged/SKILL.md
  mkdir -p .claude/skills

  skill_link=.claude/skills/review-staged
  if [ -e "$skill_link" ] || [ -L "$skill_link" ]; then
    printf '%s\n' "Already exists: $skill_link" >&2
    exit 1
  fi

  ln -s ../../.agents/skills/review-staged "$skill_link"
  test -L "$skill_link"
  test -f "$skill_link/SKILL.md"
  readlink "$skill_link"
)

La salida esperada es ../../.agents/skills/review-staged, con código de salida 0. Los dos componentes .. son relativos al directorio que contiene el enlace, .claude/skills/, y llevan de vuelta a la raíz del repositorio.

Si ya existe una entrada en la ruta del enlace, examínala antes de cambiar nada. Conserva un alias existente si es correcto; si hay un directorio real de la habilidad, revisa sus diferencias con la copia principal y decide cómo resolverlas. El comando rechaza sustituir tanto un directorio como un enlace roto.

Crea el enlace equivalente en Windows

Utiliza PowerShell 7.1 o posterior para el enlace relativo a un directorio que se muestra a continuación. La documentación de New-Item de Microsoft documenta ese requisito de versión; crear enlaces simbólicos en Windows normalmente requiere permisos elevados o una versión compatible de Windows con Developer Mode habilitado.

Con el SKILL.md principal ya guardado, ejecuta lo siguiente desde la raíz del repositorio:

New-Item -ItemType Directory -Force -Path '.claude/skills' -ErrorAction Stop | Out-Null
Push-Location '.claude/skills' -ErrorAction Stop
try {
    New-Item -ItemType SymbolicLink -Path 'review-staged' `
        -Target '../../.agents/skills/review-staged' -ErrorAction Stop | Out-Null
    Get-Item 'review-staged' | Select-Object LinkType, Target
    Test-Path 'review-staged/SKILL.md' -PathType Leaf
}
finally {
    Pop-Location
}

El valor esperado de LinkType es SymbolicLink, y la comprobación del archivo debe devolver True. Si la creación falla por falta de privilegios, utiliza el procedimiento aprobado por tu organización para habilitar Developer Mode o ejecutar con permisos elevados.

No des por hecho que Git Bash nativo se comporta como Linux: Git for Windows documenta que ln -s crea copias de forma predeterminada. Utiliza el procedimiento de PowerShell e inspecciona el enlace resultante.

Puede aparecer un fallo distinto después de clonar. Con core.symlinks=false, Git crea en el árbol de trabajo un archivo normal que contiene el texto del destino del enlace simbólico. Diagnostica ese caso en PowerShell:

git config --show-origin --get core.symlinks
Get-Item '.claude/skills/review-staged' |
    Select-Object LinkType, Target, PSIsContainer
Test-Path '.claude/skills/review-staged/SKILL.md' -PathType Leaf

Si el alias es un archivo de texto, inspecciona su contenido antes de sustituir ese archivo concreto por un enlace real. Configura un método compatible de creación de enlaces simbólicos durante el checkout para los próximos clones. Cambiar únicamente el ajuste de Git no convierte un archivo de texto ya creado durante el checkout en un enlace a un directorio.

Comprueba la detección, la activación y la salida

Primero revisa el catálogo del cliente; después, invoca la habilidad de forma explícita. Que el archivo exista en disco no demuestra que el cliente lo haya detectado, y una entrada en el catálogo tampoco demuestra que se hayan cargado sus instrucciones.

Abre o inicia cada cliente en la raíz del repositorio. Utiliza estos controles dentro del cliente, no en un prompt de Bash o PowerShell:

Cliente	Confirmar la detección	Invocar el ejemplo
Claude Code	Ejecuta `/skills`; utiliza `/reload-skills` si hace falta, como indica su referencia de comandos.	Envía `/review-staged`.
Codex CLI o extensión para IDE	Abre `/skills` o el selector de habilidades `$`.	Envía `$review-staged Review my staged changes.`
Cursor Agent	Abre Customize → Skills y busca la habilidad en el selector `/`.	Selecciona `review-staged` y solicita una revisión de los cambios preparados.
Gemini CLI	Ejecuta `/skills list`; utiliza `/skills reload` después de añadir archivos.	Pide: `Use the review-staged skill to review my staged changes.`

El flujo de activación documentado de Gemini utiliza activate_skill y una solicitud interactiva de consentimiento. Aprueba el directorio de la habilidad que quieras utilizar cuando se te solicite. Su guía de administración explica los comandos para listar y recargar habilidades.

La respuesta esperada empieza por Skill loaded: review-staged, seguida de los problemas encontrados y las comprobaciones sugeridas, o de No staged changes. si el índice está vacío. Inspecciona también la traza de activación o de lectura del archivo y los comandos Git, además del marcador. Esto permite comprobar que se ha cargado el flujo de trabajo; no demuestra que todos los hallazgos de la revisión sean correctos.

Cursor lee ambas rutas en esta estructura. Sus notas de la versión 3.25 del IDE, del 14 de octubre de 2026, indican que las habilidades con el mismo nombre pueden aparecer como filas separadas en el menú. Comprueba si hay entradas duplicadas en tu versión instalada; no des por hecho que todos los clientes eliminan los alias duplicados de la misma manera.

Usa una estructura predecible para monorepos y CI

Mantén las habilidades compartidas en la raíz del repositorio e inicia allí cada cliente durante la primera configuración que verifiques. Para flujos de trabajo específicos de un paquete, indica su nombre en la descripción y en las instrucciones de la habilidad, sin depender de que todos los clientes busquen igual en directorios anidados. El ejemplo anterior revisa deliberadamente todo el índice de Git.

Una estructura práctica asigna una responsabilidad a cada ubicación:

Ubicación	Responsabilidad
`.agents/skills/review-staged/SKILL.md`	Instrucciones compartidas que se mantienen y editan.
`.agents/skills/review-staged/references/`	Documentos de apoyo opcionales distribuidos con esa habilidad.
`.claude/skills/review-staged`	Alias relativo al directorio completo de la habilidad compartida.
`packages/mobile/`	Código de la aplicación mencionado en la tarea solicitada.

Las reglas de ámbito varían. Claude Code y Codex buscan sus respectivos directorios de habilidades ascendiendo desde el directorio de inicio hasta la raíz del repositorio. Cursor también documenta habilidades en directorios anidados del proyecto cuyo ámbito se limita a los archivos situados bajo el directorio que las contiene. La guía de administración de Gemini describe las habilidades del área de trabajo con relación al directorio actual. Iniciar los cuatro clientes en la raíz evita depender de esas diferencias.

Guarda cada habilidad compartida en un subdirectorio situado directamente bajo la raíz de habilidades. La guía de primeros pasos de Gemini limita la detección a esa profundidad; la búsqueda recursiva de Cursor no hace que un nivel adicional de carpetas de categorías sea portable.

Para un área de trabajo que solo incluya un paquete, repite allí la comprobación de detección e instala o enlaza la habilidad compartida si hace falta. No reutilices el destino ../../ del alias situado en la raíz en una ubicación más profunda sin recalcularlo.

Incluye en el commit el directorio con la copia principal y el enlace simbólico relativo si los entornos de checkout de tu equipo lo admiten. Mantén el destino dentro del repositorio para que un clon nuevo pueda resolverlo sin acceder al directorio personal de un desarrollador.

En un entorno de CI con Linux, esta comprobación en Bash verifica los archivos y el enlace necesarios tras el checkout:

test -f .agents/skills/review-staged/SKILL.md &&
test -L .claude/skills/review-staged &&
test -f .claude/skills/review-staged/SKILL.md

Un código de salida 0 significa que esas comprobaciones del sistema de archivos han pasado. La detección y la invocación por parte del cliente siguen requiriendo las comprobaciones anteriores en el entorno de ejecución real.

Si la habilidad sigue sin cargarse, comprueba dónde falla

Corrige el problema en la etapa que falla en lugar de cambiar el prompt una y otra vez. Estas son ramas de diagnóstico alternativas, no una secuencia de ajustes que todo el mundo deba cambiar.

No aparece en el catálogo: Confirma la raíz del área de trabajo, la escritura de los nombres de directorio y el nombre exacto SKILL.md. Lee el archivo a través de la ruta en la que busca el cliente. Si funciona la ruta principal pero falla la de Claude, repara el enlace o el checkout.
El archivo se encuentra, pero se rechazan los metadatos: Comprueba los delimitadores YAML, una description no vacía de como máximo 1024 caracteres y un nombre de directorio que coincida con name y tenga 1–64 caracteres, entre letras minúsculas, dígitos y guiones. Evita los guiones iniciales, finales o consecutivos.
El archivo nuevo todavía no aparece: Recarga las habilidades de Claude o Gemini con los comandos anteriores. Codex documenta la detección automática y el reinicio como alternativa si esta falla; vuelve a abrir Cursor cuando sea necesario repetir la detección al inicio.
Falta una habilidad del área de trabajo de Gemini: Comprueba la confianza de la carpeta mediante /permissions trust. La referencia de configuración actual indica que skills.enabled vale true de forma predeterminada, aunque una política del administrador puede prohibir las habilidades. Gestiona los ajustes deshabilitados y las decisiones de confianza desde los controles correspondientes.
Se ejecuta la habilidad equivocada: Inspecciona las copias de usuario y de proyecto que tengan el mismo nombre. Claude da prioridad a las habilidades de usuario sobre las de proyecto; Codex puede mostrar ambas; Gemini da prioridad a las del área de trabajo sobre las de usuario. Prefiere nombres distintos para flujos de trabajo diferentes.
Aparece en la lista, pero no se selecciona automáticamente: Invócala primero de forma explícita. Si funciona, mejora la descripción para que nombre la tarea de la que se ocupa. Una descripción más clara ayuda a la selección; mover un archivo que ya se detecta correctamente no.
Se carga, pero fallan los comandos: Comprueba que Git esté disponible, el directorio de trabajo y el error de permisos indicado. Compartir el directorio no instala el entorno de ejecución ni concede permisos para ejecutar comandos.