Compartir skills de agentes entre repositorios sin desvíos

Cómo compartir skills de agentes entre repositorios

Para compartir skills de agentes entre repositorios, deje de copiar el archivo y empiece a depender de él. Mantenga un único repositorio de skills, etiquételo y haga que cada proyecto fije una etiqueta. Después, añada una prueba de humo para cada skill y revise cada actualización como revisaría la actualización de una dependencia.

Son cuatro partes: una fuente de verdad compartida, una versión fijada por repositorio, una prueba de humo para cada skill y un proceso de revisión. A continuación se explica por qué existe cada parte, qué hacen al respecto las herramientas distribuidas en 2026 y cómo crear todo el sistema en un remoto git autohospedado sin usar servicios externos.

Un skill 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 un skill de agente y cómo funciona SKILL.md. Esta página trata sobre la cadena de suministro que rodea 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 tus proyectos y en los de nadie más.
• .claude/skills/<skill-name>/SKILL.md corresponde al nivel del proyecto. Se carga para quien clone ese repositorio.
• <plugin>/skills/<skill-name>/SKILL.md se incluye en un plugin. Se carga 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 ubicada en .claude/skills/ pertenece a un repositorio. Tienes ocho repositorios. Por tanto, la skill se copia ocho veces.

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

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

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

Problema uno: ocho copias que divergen sin que nadie lo advierta

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 actualiza las otras siete copias. Otra persona añade una regla sobre 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. Un 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 de los demás, así que la única señal aparece cuando alguien detecta que dos repositorios no coinciden.

Problema dos: nada fija una versión

Incluso cuando un equipo mantiene las instrucciones en un único lugar, el método habitual para compartirlas es un paso de copia: un script de configuración, una línea `curl` en el documento de incorporación o un alias de shell que sincroniza una carpeta. Todos estos métodos instalan lo que haya actualmente en la parte más reciente de la rama.

Esto significa que dos desarrolladores que trabajan con el mismo commit de la misma aplicación pueden ejecutar instrucciones diferentes porque realizaron la sincronización en días distintos. También significa que no se puede responder a la pregunta importante después de una ejecución incorrecta de un agente: ¿qué versión de la skill 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. Son 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 fidelidad con que sigue una instrucción larga. 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.

Ninguno de esos casos produce un fallo evidente. El agente sigue respondiendo. La respuesta simplemente es peor que el mes pasado, y eso es difícil de detectar cuando se revisa una solicitud de extracción cada vez.

Qué resuelven las herramientas disponibles en 2026

Ya 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 fecha de 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 hay instalado. El registro de lo instalado se conserva 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 todos los skills registrados desde el lock file, para que una segunda máquina termine con el mismo conjunto. Considere esa solicitud un informe de estado. La idea del lock file está resuelta. La parte específica de cada proyecto todavía está en desarrollo.

Especificaciones y pruebas. SkillSpec adopta el otro enfoque. Trata un SKILL.md como un contrato que se debe comprobar, no como prosa en la que confiar, con el objetivo declarado de hacer 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 según el riesgo. Es un crate de Rust con licencia doble MIT o Apache 2.0, en la versión 0.2.2 a fecha de 29 de julio de 2026. Instale la versión fijada, no 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, de modo 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 en su PATH está ganando un binario anterior.

Prácticas del proveedor. Google describió cómo compila los skills de google/skills en una publicación sobre cómo compila, prueba y escala los skills de agentes. Si se elimina la escala, el mecanismo es la integración continua (CI) habitual. Cada skill pasa linters para comprobar los metadatos de frontmatter, el número de líneas, la estructura de directorios y la nomenclatura antes de integrarse. Un comprobador de enlaces hace fallar la compilación si alguna URL devuelve 404, lo que detecta el enlace plausible que inventó un agente. Los autores deben proporcionar un conjunto de prompts de evaluación y una rúbrica de puntuación junto con el skill. Después, los 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 disminuye su calidad.

El patrón común a las tres respuestas

No tiene que elegir una de ellas. Debajo de todas hay una única estructura, y git sin extensiones le proporciona todo lo necesario.

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 actualizarla consiste en hacer 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. Los cambios en una skill compartida pasan por revisión, y cada consumidor ve un diff antes de incorporarlos.

Esa es la estructura de una dependencia. Las skills se convirtieron en artefactos compartidos más rápido de lo que evolucionaron las herramientas para gestionarlas, por lo que recurrir a las herramientas en las que ya confía es la opción más segura.

Diseño para un equipo pequeño con un remoto Git autohospedado

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 son etiquetas. Use etiquetas anotadas porque incluyen un mensaje y una fecha. Escriba el mensaje como el motivo por el que un consumidor querría actualizar la versión:

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 bare mediante SSH en su propio VPS, nada de lo siguiente cambia. Todo se basa en git y un enlace simbólico.

Anclar con un submódulo de git

Un submódulo registra un commit exacto de otro repositorio dentro del repositorio actual. Ese registro es el anclaje. 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 hace posible este mecanismo. Una entrada de skill en el nivel del proyecto puede ser un enlace simbólico a un directorio ubicado en otra ruta 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 que los archivos se almacenan en el submódulo, en el commit que haya elegido.

Compruebe el anclaje:

git submodule status

Una línea correcta empieza con un espacio, continúa con el 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 no coincide con el 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 clon 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 puede incluirse en una pull request.

Fijar la versión con 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, y confundirlas es el error más 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 ambas opciones. Si se establecen las dos, sha es el pin efectivo. Por tanto, el pin del commit exacto debe estar en la entrada del catálogo.

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

{
  "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, y el plugin se habilita sin que una página de la wiki tenga que indicarle que lo haga. Las skills responden entonces a /team-skills:api-review, porque las skills de los plugins usan el nombre del plugin como espacio de nombres y no pueden colisionar con una 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 de un agente mediante un script contra un fixture con un fallo conocido, junto con una aserción. Claude Code se ejecuta de forma no interactiva con -p, y una skill invocada por el usuario también funciona ahí: incluya /skill-name en la cadena del prompt y se expandirá antes de iniciar 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 único fallo deliberado. La aserción comprueba que la skill lo identifica. 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 hará que falle el script. claude 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 hacer una aserción sobre una frase completa. Hágala sobre un identificador que la skill deba emitir o sobre un campo de un esquema solicitado, y mantenga pequeño el fixture para que la ejecución siga siendo económica.

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 todo el descubrimiento automático, por lo que también omite la skill que 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 una referencia fijada a una revisión que ya no existe, un problema que de otro modo se manifiesta como un agente que ignora en silencio las reglas internas.

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.

En primer lugar, 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 la máquina que carga la skill y su salida sustituye el marcador de posición en el texto que recibe el modelo. Un bloque delimitado que se abre con tres comillas invertidas seguidas de ! ejecuta varios comandos del mismo modo. Nadie aprueba nada de esto durante la ejecución. Leer una skill compartida implica leer sus sustituciones de comandos.

En segundo lugar, el frontmatter puede preautorizar herramientas. allowed-tools concede las herramientas indicadas sin mostrar una solicitud de permiso durante el turno que invocó la skill. En una skill de proyecto, esa concesión se aplica cuando alguien acepta el cuadro de 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 un acceso amplio a las herramientas.

Por tanto, trate una actualización de una skill exactamente igual que una actualización de una dependencia. Fije la versión mediante el commit exacto siempre que el mecanismo lo permita, porque un tag puede cambiar de destino y una rama cambia por definición. En una máquina restringida, "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, y, si se aplica mediante la configuración administrada, el usuario no puede anularlo. Las skills incluidas y administradas están exentas de esa 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 explicado en mantener los secretos fuera de los agentes que ejecuta. Una skill que obtiene una página o ejecuta una consulta expone esos mismos datos hacia el exterior, porque el texto recuperado llega al contexto con el mismo aspecto que las instrucciones que usted escribió. Es un límite que conviene conocer antes de dirigir un agente a su propia instancia de SearXNG para realizar búsquedas web.

Qué leer al actualizar una versión

• El diff del cuerpo 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 básicas en CI, la etiqueta a la que fija la versión debe tener una ejecución correcta asociada.

Si un revisor no puede leer todo el diff en diez minutos, la skill ha crecido demasiado. Divídala. El mismo criterio 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 mantenga las skills como procedimientos específicos.

Cuando un cambio de modelo o de herramienta rompe una skill

Varios elementos subyacentes pueden cambiar sin que nadie edite una skill. Una actualización del modelo cambia 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 cambia el nombre de un flag, así que el agente ejecuta el flag antiguo, lee el error e improvisa. Una URL referenciada empieza a devolver 404. Un arnés de agente cambia la forma en que selecciona las skills, por lo que un description que antes ganaba la coincidencia puede dejar de hacerlo. Cuando un procedimiento empieza a terminar antes de tiempo de esa forma, ningún cambio de versión lo corrige. Las propias instrucciones necesitan una estructura que obligue a ejecutar los últimos pasos. Ese es el enfoque de la skill unlazy y su método Depth Tree.

Por eso la prueba de humo es tan importante en este esquema. Ejecute la prueba de cada skill con una periodicidad definida y también con cada push. Google ejecuta sus trabajos de evaluación semanalmente contra toda la biblioteca por este motivo. Para un equipo con diez skills, basta con un trabajo cron semanal en un VPS pequeño. 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ó. En cambio, cada clave específica del arnés que añada es una apuesta por un proveedor. Escribir skills que sobrevivan a un cambio de modelo requiere una disciplina propia, descrita en hacer que una skill funcione con cualquier modelo.

FAQ

¿Cómo comparto una 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 que funcionan. 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 mercado de plugins hace lo mismo mediante /plugin, con la fijación declarada en .claude/settings.json del repositorio consumidor. Ambos guardan 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 esa cabecera de metadatos 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 mercado de plugins de Claude Code, una fuente de plugin acepta ref para una rama o etiqueta y sha para un commit exacto; si se especifican ambos, prevalece sha. La fuente del mercado sólo acepta ref. Prefiera fijar el commit, porque una etiqueta puede cambiar después de haberla revisado.

¿Qué debe comprobar una prueba rápida de una habilidad?

Compruebe algo estable. Ejecute la habilidad de forma no interactiva contra un fixture que contenga un fallo conocido y verifique que aparezca un identificador específico 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 cuando falta el valor. No compruebe una frase completa, porque un 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 cabecera de metadatos allowed-tools puede autorizar herramientas previamente 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 máquinas administradas, "disableSkillShellExecution": true en la configuración impide por completo la ejecución de sustituciones de comandos.

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

Depende de la cabecera de metadatos 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 no formen parte de la especificación se ignoran o se rechazan en otros entornos, por lo que debe mantenerlas fuera de cualquier habilidad que pretenda compartir ampliamente.