Compartir skills entre repositorios sin desviaciones

Cómo compartir habilidades de agentes entre repositorios

Para compartir habilidades de agentes entre repositorios, deje de copiar el archivo y empiece a depender de él. Mantenga un único repositorio de habilidades, asígnele etiquetas y permita que cada proyecto fije una etiqueta. Después, añada una prueba básica por habilidad y revise cada actualización como revisaría la actualización de una dependencia.

Esto consta de cuatro partes: una fuente de verdad compartida, una versión fijada por repositorio, una prueba básica por habilidad y un proceso de revisión. A continuación se explica por qué existe cada parte, cómo lo gestionan las herramientas que se publican en 2026 y cómo crear todo el sistema en un remoto git autogestionado sin depender de servicios externos.

Una habilidad de agente es una carpeta que contiene un archivo SKILL.md, además de los scripts y archivos de referencia que necesita. Si esta unidad es nueva para usted, lea primero qué es una habilidad de agente y cómo funciona SKILL.md. Esta página trata sobre la cadena de suministro que rodea a esa unidad.

Dónde se encuentra una skill y por qué es difícil compartirla

Claude Code carga las skills desde tres ubicaciones, y la documentación de skills indica cada ruta.

• ~/.claude/skills/<skill-name>/SKILL.md es personal. Se carga en todos sus proyectos, pero en los de nadie más.
• .claude/skills/<skill-name>/SKILL.md corresponde al nivel del proyecto. Se carga para cualquiera que clone ese repositorio.
• <plugin>/skills/<skill-name>/SKILL.md se incluye en un plugin. Se carga en cualquier lugar donde esté habilitado ese plugin.

La segunda opción es la útil para un equipo, porque se confirma en el repositorio y todos los que lo clonan la reciben. También es donde empiezan los problemas. Una skill en .claude/skills/ pertenece a un repositorio. Tiene ocho repositorios. Por tanto, la skill se copia ocho veces.

El frontmatter no ayuda. La especificación de Agent Skills permite seis claves, y las rutas de distribución que aplican esta restricción muestran la lista cuando se usa otra:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Observe lo que falta: no existe ninguna clave version. El archivo no registra qué copia es más reciente. Esto es razonable, porque una skill es un documento, no un paquete. Sin embargo, el versionado debe proceder de la capa que rodea al archivo, y esa capa es responsabilidad suya.

Problema uno: ocho copias que divergen en silencio

Copiar y pegar funciona el primer día. Falla al día sesenta. Alguien corrige una instrucción incorrecta en el repositorio payments y no modifica las otras siete copias. Otra persona añade una regla sobre la paginación en orders. Ahora, el mismo nombre de skill produce dos revisiones diferentes según el directorio desde el que se inició el agente, y ningún desarrollador lo sabe.

El fallo es silencioso porque no existe un estado de error. Una skill es texto. Una instrucción obsoleta produce una respuesta segura pero incorrecta, que es el tipo de error más costoso. El agente no compara su copia con las demás, así que la única señal aparece cuando una persona detecta que dos repositorios no coinciden.

Problema dos: nada fija una versión

Incluso cuando un equipo mantiene las habilidades en un solo lugar, el método habitual para compartirlas es un paso de copia: un script de configuración, una línea curl en la documentación de incorporación o un alias de shell que sincroniza una carpeta. Todos estos métodos instalan lo que se encuentra actualmente en la punta de la rama.

Esto significa que dos desarrolladores que usan el mismo commit de la misma aplicación pueden ejecutar instrucciones diferentes porque sincronizaron las habilidades en días distintos. También significa que no se puede responder a la pregunta importante después de una ejecución defectuosa del agente: ¿qué versión de la habilidad produjo este resultado? Sin una revisión registrada, la ejecución no es reproducible y el informe del error no permite actuar.

Problema tres: nadie sabe si la skill sigue funcionando

Una skill no tiene compilador. Es un conjunto de instrucciones dirigidas a un modelo, por lo que puede dejar de funcionar aunque el archivo siga siendo idéntico byte por byte. Una actualización del modelo cambia el grado de precisión con el que sigue una instrucción extensa. Una herramienta de línea de comandos que usa la skill cambia el nombre de una opción. Una URL de un archivo de referencia empieza a devolver 404 y el agente trabaja a partir de la página de error.

En ninguno de estos casos se produce un fallo evidente. El agente sigue respondiendo. La respuesta simplemente es peor que el mes pasado, y es difícil detectar ese cambio revisando una solicitud de incorporación de cambios cada vez.

Qué resuelven las herramientas disponibles en 2026

Ahora mismo están apareciendo varias respuestas, pero no coinciden en dónde debe residir la versión.

Lockfiles. La herramienta de línea de comandos skills de Vercel Labs (vercel-labs/skills, con licencia MIT y en la versión v1.5.22 a 5 de agosto de 2026) instala skills desde un repositorio git en el directorio que espera el agente y conoce la estructura de más de setenta agentes. npx skills add <repo> instala, npx skills update actualiza y npx skills list muestra lo que tiene instalado. El registro de lo instalado se guarda una vez por usuario, no una vez por repositorio, y una solicitud abierta en ese proyecto (issue 283) pide un comando skills install que reinstale cada skill registrado desde el lock file, de modo que una segunda máquina termine con el mismo conjunto. Considere esa solicitud como un informe de estado. La idea del lockfile está consolidada. La parte específica de cada proyecto todavía está en desarrollo.

Especificaciones y pruebas. SkillSpec adopta el enfoque contrario. Trata un SKILL.md como un contrato que se debe comprobar, no como prosa en la que se debe confiar, con el objetivo declarado de conseguir que los skills sean "seguibles, comprobables y demostrables". skillspec doctor <path> informa de dónde es probable que un agente pierda el hilo. skillspec boundary map <path> informa de qué recursos puede alcanzar el skill y skillspec boundary assess <path> clasifica esos resultados por riesgo. Es un crate de Rust, con licencia dual MIT o Apache 2.0, en la versión 0.2.2 a 29 de julio de 2026. Instale la versión fijada en lugar de la más reciente:

cargo install skillspec --version 0.2.2 --locked
skillspec --version

--locked compila con las versiones de las dependencias con las que se publicó el crate, por lo que la compilación no cambia sin que usted lo advierta. skillspec --version debería mostrar 0.2.2. Un número diferente significa que una versión anterior del binario situada antes en su PATH tiene prioridad.

Prácticas de los proveedores. Google describió cómo compila los skills de google/skills en una publicación sobre cómo compila, prueba y escala los skills de los agentes. Si se deja de lado la escala, el mecanismo es la integración continua (CI) habitual. Cada skill pasa comprobaciones de lint para los metadatos de frontmatter, el recuento de líneas, la estructura de directorios y los nombres antes de integrarse. Un comprobador de enlaces hace fallar la compilación ante cualquier URL que devuelva 404, lo que detecta el enlace verosímil que un agente inventó. Los autores deben proporcionar una suite de prompts de evaluación y una rúbrica de puntuación junto con el skill. Después, trabajos de evaluación programados se ejecutan semanalmente contra toda la biblioteca para detectar regresiones, y cada skill tiene un responsable asignado que debe corregirlo cuando baja su calidad.

El patrón común a las tres respuestas

No tiene que elegir una de ellas. Debajo hay una única estructura, y git sin extensiones le ofrece todos sus elementos.

1. Una única fuente de verdad. La skill tiene exactamente una ubicación, y cada repositorio hace referencia a ella en lugar de guardar una copia.
2. Una versión fijada por repositorio. Cada proyecto registra la revisión exacta que utiliza, de modo que una actualización es un commit en ese proyecto, con autor y fecha.
3. Una prueba de humo por skill. Una comprobación ejecutable demuestra que la skill sigue produciendo el resultado que promete.
4. Un proceso de revisión. Un cambio en una skill compartida pasa por revisión, y cada consumidor ve un diff antes de incorporarlo.

Esta es la estructura de una dependencia. Las skills se convirtieron en artefactos compartidos antes de que surgieran herramientas específicas para gestionarlas, por lo que recurrir a las herramientas en las que ya confía es la opción más segura.

Un diseño para un equipo pequeño con un remoto Git autogestionado

Un repositorio contiene las habilidades. No contiene nada más, por lo que su historial funciona como un registro de cambios de las instrucciones.

agent-skills/
  skills/
    api-review/
      SKILL.md
    release-notes/
      SKILL.md
  tests/
    api-review.sh
    release-notes.sh
  CHANGELOG.md

Las versiones se representan mediante etiquetas. Use etiquetas anotadas porque incluyen un mensaje y una fecha. Escriba el mensaje indicando el motivo por el que un consumidor querría actualizar:

git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0

Si el remoto es Gitea, Forgejo, GitLab o un repositorio desnudo mediante SSH en su propio VPS, nada de lo siguiente cambia. Todo se basa en git y un enlace simbólico.

Fijar una versión con un submódulo de git

Un submódulo registra un commit exacto de otro repositorio dentro de su repositorio. Ese registro es la fijación. En cada proyecto consumidor:

git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"

El enlace simbólico es lo que permite este funcionamiento. Una entrada de skill en el nivel del proyecto puede ser un enlace simbólico a un directorio situado en otra ubicación del disco, y Claude Code lo sigue y lee SKILL.md desde el destino. Así, la skill se carga como una skill normal del proyecto, mientras los archivos residen en el submódulo, en el commit que haya elegido.

Compruebe la fijación:

git submodule status

Una línea correcta empieza con un espacio, seguida del commit, la ruta y la etiqueta más cercana:

 4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)

Un - inicial indica que el submódulo nunca se ha inicializado, por lo que .claude/skills/api-review no apunta a nada y la skill no se carga sin mostrar errores. Corríjalo con git submodule update --init. Un + inicial indica que el commit extraído difiere del registrado, por lo que ese desarrollador está ejecutando instrucciones que nadie más tiene. Los clones nuevos necesitan git clone --recurse-submodules, y esa línea debe aparecer en el README, porque un clone normal deja vendor/agent-skills vacío y no muestra ningún error.

La actualización es deliberada, que es precisamente el objetivo:

git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"

La línea diff es la ruta de revisión. Muestra el mismo cambio que verá cualquier otro repositorio consumidor y cabe en una pull request.

Fijar versiones mediante un marketplace de plugins

Si prefiere no pedir a cada desarrollador que aprenda a usar submódulos, el sistema de plugins de Claude Code se encarga de la distribución y funciona con un remoto autohospedado. Coloque un catálogo en .claude-plugin/marketplace.json dentro del repositorio de skills:

{
  "name": "acme-agents",
  "owner": { "name": "Platform team", "email": "platform@example.com" },
  "plugins": [
    {
      "name": "team-skills",
      "description": "Shared review and release skills",
      "version": "1.4.0",
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0",
        "sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
      }
    }
  ]
}

Aquí intervienen dos fuentes distintas. Confundirlas es el error habitual. La fuente del marketplace, es decir, el origen desde el que se obtiene el catálogo, acepta ref para una rama o una etiqueta, pero no acepta sha. Una fuente de plugin dentro del catálogo acepta ambos. Cuando se establecen los dos, sha es el fijado efectivo. Por tanto, el fijado al commit exacto pertenece a la entrada del catálogo.

Cada repositorio consumidor declara después el marketplace en su .claude/settings.json versionado:

{
  "extraKnownMarketplaces": {
    "acme-agents": {
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0"
      }
    }
  },
  "enabledPlugins": {
    "team-skills@acme-agents": true
  }
}

A un compañero que confía en la carpeta del proyecto se le solicita instalar el marketplace. El plugin se habilita para esa persona sin necesidad de una página de la wiki que le indique cómo hacerlo. Los skills responden entonces a /team-skills:api-review, porque los skills de los plugins usan el nombre del plugin como espacio de nombres y no pueden entrar en conflicto con un skill del proyecto que tenga el mismo nombre. Después de publicar una etiqueta nueva, los consumidores actualizan con /plugin marketplace update acme-agents y ejecutan /reload-plugins si el resumen de instalación lo solicita.

Escribir una prueba de humo para una skill

Una prueba de humo es una ejecución programada del agente contra un fixture con un fallo conocido, más una aserción. Claude Code se ejecuta de forma no interactiva con -p, y una skill invocada por el usuario también funciona ahí: coloque /skill-name en la cadena del prompt y se expandirá antes de que comience la ejecución.

#!/usr/bin/env bash
set -euo pipefail

claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --allowedTools "Read" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
  | jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/null

fixtures/orders-api.md es un archivo corto con un fallo deliberado. La aserción comprueba que la skill lo nombre. jq -e termina con un código distinto de cero cuando su filtro produce null, por lo que una skill que deje de detectar el fallo sembrado hace que el script falle. claude también termina con un código distinto de cero cuando falla la ejecución, y set -euo pipefail convierte cualquiera de los dos fallos en una prueba fallida.

Un modelo reformula sus respuestas entre ejecuciones, por lo que nunca debe comprobar una frase completa. Compruebe un identificador que la skill deba emitir o un campo del esquema solicitado, y mantenga pequeño el fixture para que la ejecución tenga un coste bajo.

En CI, añada --bare. Sin esta opción, claude -p carga el mismo contexto que usaría una sesión interactiva, incluidos los hooks, los plugins y CLAUDE.md de la máquina donde se ejecuta. Por tanto, la configuración personal de otro miembro del equipo puede cambiar el resultado. El modo bare omite toda la detección automática, por lo que también omite la skill que se está probando. Cargue esa skill de forma explícita. El modo bare tampoco lee el inicio de sesión de su suscripción, así que establezca primero ANTHROPIC_API_KEY en el entorno:

claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --plugin-dir vendor/agent-skills \
  --allowedTools "Read" \
  --output-format json

Con --output-format stream-json, el primer evento de la ejecución informa de qué plugins se cargaron e incluye un array plugin_errors con los que no se cargaron. Haga que el trabajo de CI falle si plugin_errors no está vacío. Esto detecta un pin dirigido a una revisión que ya no existe, un problema que de otro modo se manifiesta como un agente que ignora silenciosamente las reglas del equipo.

Una skill compartida es una instrucción ejecutable

Dos características hacen que esto sea literal, y ambas importan cuando el archivo procede de otro equipo.

Primero, un SKILL.md puede ejecutar comandos de shell antes de que el modelo lea nada. Una línea como esta en el cuerpo realiza un preprocesamiento:

- Current branch: !`git rev-parse --abbrev-ref HEAD`

El comando se ejecuta en el equipo que carga la skill, y su salida sustituye al marcador de posición en el texto que recibe el modelo. Un bloque delimitado que comienza con tres acentos graves seguidos de ! ejecuta varios comandos de la misma forma. Nadie aprueba nada de esto durante la ejecución. Leer una skill compartida implica leer las sustituciones de comandos que contiene.

Segundo, el frontmatter puede autorizar herramientas previamente. allowed-tools concede las herramientas indicadas sin mostrar una solicitud de permiso durante el turno que invocó la skill. En una skill del proyecto, esa concesión se aplica cuando alguien acepta el diálogo de confianza del workspace para la carpeta. La documentación de Claude Code indica claramente la consecuencia: revise las skills del proyecto antes de confiar en un repositorio, porque una skill puede concederse a sí misma acceso amplio a las herramientas.

Por tanto, trate una actualización de una skill exactamente como una actualización de una dependencia. Fíjela mediante el commit exacto siempre que el mecanismo lo permita, porque un tag puede cambiar y una rama cambia por definición. En un equipo con restricciones, "disableSkillShellExecution": true en la configuración sustituye cada sustitución de comandos por el texto literal [shell command execution disabled by policy] en lugar de ejecutarla; si se aplica mediante la configuración administrada, el usuario no puede anularla. Las skills incluidas y administradas están exentas de esta configuración.

La misma precaución se aplica a lo que lee una skill. Una skill que ejecuta env o abre un archivo de configuración incorpora al contexto del modelo todo lo que encuentra. Este es el fallo descrito en mantener los secretos fuera de los agentes que ejecuta.

Qué leer al actualizar una versión

• El diff del contenido de cada SKILL.md, porque ese texto contiene las instrucciones que seguirá el agente.
• Todas las sustituciones de comandos, porque se ejecutan en su máquina cuando se carga la skill.
• Cualquier cambio en allowed-tools, porque esa línea concede herramientas sin solicitar confirmación.
• La ejecución de pruebas asociada a la etiqueta. Si el repositorio compartido ejecuta sus propias pruebas de humo en CI, la etiqueta que va a fijar debería tener una ejecución correcta asociada.

Si un revisor no puede leer todo el diff en diez minutos, está revisando una skill que ha crecido demasiado. Divídala. El mismo argumento se aplica a los documentos del repositorio que leen los agentes: mantenga las reglas duraderas en los archivos descritos en la separación entre AGENTS.md y HUMAN.md y el razonamiento arquitectónico en un DESIGN.md escrito para agentes, y limite las skills a procedimientos concretos.

Cuando un cambio de modelo o herramienta rompe una skill

Varios elementos subyacentes a una skill pueden cambiar sin que nadie la edite. Una actualización del modelo puede cambiar la fiabilidad con la que sigue una instrucción larga, por lo que una skill que dependía de que el modelo llegara al paso nueve puede dejar de hacerlo. Una herramienta de línea de comandos puede cambiar el nombre de una opción, de modo que el agente ejecuta la opción antigua, lee el error e improvisa. Una URL referenciada puede empezar a devolver 404. Un arnés de agente puede cambiar la forma en que selecciona las skills, por lo que un description que antes ganaba la coincidencia puede dejar de hacerlo.

Por eso la prueba de humo es fundamental en esta configuración. Ejecute la prueba de cada skill según una programación y también después de cada push. Google ejecuta sus trabajos de evaluación semanalmente contra toda la biblioteca por este motivo, y un trabajo cron semanal en un VPS pequeño es suficiente para un equipo con diez skills. Es la única forma de detectar el fallo antes que un desarrollador.

La portabilidad también ayuda. La especificación Agent Skills limita el frontmatter a seis claves, por lo que una skill escrita conforme a esa especificación se carga en herramientas distintas de aquella para la que se creó, mientras que cada clave específica del arnés que añada supone apostar por un proveedor. Escribir skills que sobrevivan a un cambio de modelo es una disciplina propia, descrita en hacer que una skill funcione con cualquier modelo.

FAQ

¿Cómo comparto una misma habilidad de agente entre varios repositorios?

Coloque la habilidad en un repositorio git dedicado, etiquete las versiones y haga que cada proyecto consumidor haga referencia a una etiqueta en lugar de copiar el archivo. Hay dos mecanismos adecuados. Un submódulo git registra un commit exacto, y un enlace simbólico desde .claude/skills/<name> al submódulo hace que se cargue como una habilidad normal del proyecto. Un marketplace de plugins hace lo mismo mediante /plugin, con la fijación declarada en .claude/settings.json del repositorio consumidor. Ambos almacenan la versión en el historial de git, por lo que puede determinar qué instrucciones produjeron una ejecución concreta del agente.

¿Puedo fijar una habilidad de agente a una versión específica?

No desde SKILL.md, porque ese frontmatter no tiene ninguna clave version. La fijación debe proceder de la capa que rodea al archivo. Un submódulo git fija un commit exacto por diseño. En un marketplace de plugins de Claude Code, una fuente de plugin acepta ref para una rama o etiqueta y sha para un commit exacto; sha tiene prioridad cuando ambos están presentes. La propia fuente del marketplace sólo acepta ref. Prefiera fijar el commit, porque una etiqueta puede cambiar después de haberla revisado.

¿Qué debe comprobar una prueba básica de una habilidad?

Compruebe algo estable. Ejecute la habilidad de forma no interactiva contra un fixture que contenga un fallo conocido y verifique que un identificador específico aparezca en la salida, por ejemplo, el identificador de una regla que la habilidad deba notificar. Solicitar una salida estructurada con --output-format json y --json-schema hace que la comprobación sea exacta, y jq -e hace que el script falle si falta el valor. No compruebe una frase completa, porque el modelo reformula sus respuestas entre ejecuciones.

¿Es seguro instalar una habilidad compartida desde el repositorio de otro equipo?

Trátela como una dependencia de código, porque contiene instrucciones ejecutables. Un SKILL.md puede ejecutar comandos de shell durante la carga mediante la forma de sustitución de comandos !, y el campo de frontmatter allowed-tools puede autorizar previamente herramientas sin mostrar una solicitud. Revise el diff en cada actualización, fije un commit exacto en lugar de una rama y prefiera una fuente controlada por su propio equipo. En equipos administrados, "disableSkillShellExecution": true en la configuración impide por completo que se ejecuten sustituciones de comandos.

¿Funcionará una habilidad compartida en agentes distintos de Claude Code?

Depende del frontmatter que utilice. La especificación Agent Skills define seis claves: name, description, license, compatibility, metadata y allowed-tools. Una habilidad limitada a esas claves se carga en las herramientas que implementan la especificación y también se carga en Claude Code sin cambios. Las claves específicas del entorno de ejecución y las funciones del cuerpo que exceden la especificación se ignoran o se rechazan en otros entornos, por lo que debe mantenerlas fuera de cualquier habilidad que pretenda compartir ampliamente.