← Volver al listado de tecnologías ← Índice de Agent Skills

Distribución: dónde viven los skills y cómo se instalan

6 de agosto de 2026 Por: Artiko

agent-skillsplugins-de-agentesia-agentesdistribuciongitversionadoinstalacion

Distribución: dónde viven los skills y cómo se instalan

Los nueve capítulos anteriores construyeron un skill correcto: estructura, description afinada, scripts, referencias y evals. Falta la pregunta que decide si ese trabajo sirve a alguien más que a ti: dónde se deja el directorio para que un agente lo encuentre, y cómo llega a otras máquinas.

La respuesta empieza con una frase incómoda de la documentación oficial: la especificación no lo dice. Literalmente:

While the Agent Skills specification does not mandate where skill directories live (it only defines what goes inside them)…

La spec define qué hay dentro de un directorio de skill. Dónde vive ese directorio es decisión de cada cliente, guiada por convenciones muy adoptadas pero que no son normativas. Este capítulo separa con cuidado las dos cosas.

Qué es norma y qué es convención

Aspecto	Estado	Fuente
Un skill es un directorio con un `SKILL.md` dentro	Norma	`specification.md`
`SKILL.md` DEBE (MUST) tener frontmatter YAML seguido de Markdown	Norma	`specification.md`
`name` DEBE coincidir con el nombre del directorio padre	Norma	`specification.md`
Las referencias entre archivos usan rutas relativas desde la raíz del skill	Norma	`specification.md`
El skill vive en `.agents/skills/`	Convención	Guía de implementación de clientes
Proyecto tiene precedencia sobre usuario ante nombres duplicados	Convención universal entre implementaciones	Guía de implementación de clientes
Existe un gestor o registro de instalación	No definido	—

La consecuencia práctica es buena: como el formato solo describe el contenido de una carpeta, instalar un skill es copiar un directorio a un lugar que el cliente escanee. No hay compilación, ni registro central obligatorio, ni artefacto binario. Cualquier mecanismo que deje la carpeta en su sitio —cp, git clone, un submódulo, un instalador de terceros— produce exactamente el mismo resultado.

La consecuencia mala también es real: no hay un único comando de instalación válido en todas partes. Cada cliente documenta el suyo, y la única garantía de interoperabilidad es la convención .agents/skills/.

Los ámbitos de instalación

La guía de implementación describe los ámbitos que un cliente local suele escanear:

Most locally-running agents scan at least two scopes: project-level […] and user-level […]. Other scopes are possible too — for example, organization-wide skills deployed by an admin, or skills bundled with the agent itself.

Y da la tabla de rutas sugeridas:

Ámbito	Ruta	Propósito
Proyecto	`<project>/.<tu-cliente>/skills/`	Ubicación nativa del cliente
Proyecto	`<project>/.agents/skills/`	Interoperabilidad entre clientes
Usuario	`~/.<tu-cliente>/skills/`	Ubicación nativa del cliente
Usuario	`~/.agents/skills/`	Interoperabilidad entre clientes

flowchart TD
    A["Arranque de sesión"] --> B["Escanear ámbito de usuario"]
    A --> C["Escanear ámbito de proyecto"]
    A --> D["Ámbitos adicionales<br/>organización o empaquetados con el agente"]
    B --> B1["~/.agents/skills/"]
    B --> B2["~/.cliente/skills/"]
    C --> C1["proyecto/.agents/skills/"]
    C --> C2["proyecto/.cliente/skills/"]
    B1 --> E["Catálogo unificado<br/>name más description"]
    B2 --> E
    C1 --> E
    C2 --> E
    D --> E
    E --> F["Colisión de name:<br/>proyecto gana sobre usuario"]

Dentro de cada directorio de skills el cliente busca subdirectorios que contengan un archivo llamado exactamente SKILL.md. Nada más define un skill instalado.

Ámbito personal

Es el directorio del usuario. Lo que instalas ahí te acompaña en todos tus proyectos, independientemente del repositorio en el que estés trabajando.

~/.agents/skills/
- pdf-processing/
  - SKILL.md
  - scripts/
    - extract.py
- data-analysis/
  - SKILL.md
- README.md  # ignorado: no es un directorio de skill

Sirve para lo transversal: tu estilo de commits, tu forma de redactar changelogs, utilidades de formato, procedimientos que aplicas en cualquier código. Nada de esto pertenece a un repositorio concreto y ponerlo en uno sería imponerlo a quien colabore.

Ámbito de proyecto

Vive dentro del repositorio, así que viaja con el código: se clona, se revisa en pull requests y se versiona con el resto del proyecto.

mi-repo/
- .agents/
  - skills/
    - revisar-migraciones/
      - SKILL.md
      - references/CHECKLIST.md
    - generar-endpoint/
      - SKILL.md
      - assets/plantilla-controlador.ts
- src/
- package.json

Es el ámbito correcto para todo lo que solo tiene sentido con este código delante: convenciones del repositorio, procedimientos de despliegue, la forma concreta en que aquí se escriben las migraciones. Un skill de proyecto es documentación ejecutable que pasa por code review como cualquier otro archivo.

La guía advierte de un riesgo específico de este ámbito:

Project-level skills come from the repository being worked on, which may be untrusted (e.g., a freshly cloned open-source project). Consider gating project-level skill loading on a trust check.

Es una recomendación para quien implementa clientes, no un requisito, pero explica algo que verás como usuario: algunos clientes piden confirmación antes de cargar skills de un repositorio recién clonado. Un SKILL.md es texto que entra en el contexto del agente; clonar un repo ajeno es aceptar sus instrucciones.

Ámbito de organización

La guía lo nombra como ámbito posible —organization-wide skills deployed by an admin— sin fijar rutas ni mecanismo. En la práctica es lo que despliega un administrador para todo un equipo o empresa: procedimientos de cumplimiento, plantillas corporativas, políticas de seguridad.

Para agentes que corren en contenedor o en un servidor remoto, la guía es explícita sobre el problema:

User-level and organization-level skills don’t exist in the sandbox. You’ll need to provision them from an external source — for example, cloning a configuration repository, accepting skill URLs or packages through your agent’s settings, or letting users upload skill directories through a web UI.

Es decir: en entornos cloud los skills de proyecto son el caso fácil porque llegan con el repo clonado, mientras que los de usuario y organización hay que aprovisionarlos. Y un cuarto ámbito, los skills integrados del propio agente, se resuelve empaquetándolos como assets estáticos dentro del artefacto de despliegue.

Precedencia y colisiones

Cuando dos skills comparten name, hace falta una regla determinista. La guía la describe como convención universal entre implementaciones existentes:

The universal convention across existing implementations: project-level skills override user-level skills.

Dentro del mismo ámbito —por ejemplo el mismo name en <project>/.agents/skills/ y en <project>/.<cliente>/skills/— vale tanto first-found como last-found, siempre que el cliente sea consistente. Y en cualquier caso la guía pide registrar un aviso cuando un skill queda ensombrecido, para que el usuario sepa que la versión activa no es la que cree. Ojo con el registro normativo: esa instrucción está en la guía de implementación, no en la especificación, así que es práctica recomendada y no una obligación del formato.

Como autor esto te da una palanca: si un skill personal tuyo estorba en un repositorio concreto, un skill de proyecto con el mismo name lo sustituye sin desinstalar nada.

Repositorios de skills en git

La página principal de la documentación describe los skills como portable, version-controlled folders. La distribución natural es git, y no por casualidad: un skill es texto plano, con historial y diffs legibles.

Un repositorio de skills típico agrupa varios directorios hermanos:

skills-equipo/
- README.md
- LICENSE
- revisar-pr/
  - SKILL.md
  - references/CRITERIOS.md
- generar-changelog/
  - SKILL.md
  - scripts/agrupar-commits.py
- auditar-dependencias/
  - SKILL.md
  - assets/plantilla-informe.md

Cuando el catálogo crece, se añade un nivel de categoría. El repositorio google/skills organiza así sus skills:

skills/
- ads/
  - google-ads-api-quickstart/SKILL.md
- analytics/
  - google-analytics-data-api-basics/SKILL.md
- cloud/
  - gcloud/SKILL.md
  - gke-basics/SKILL.md
  - bigquery-basics/SKILL.md

El nivel de categoría no es parte de ninguna norma: el cliente descubre skills buscando subdirectorios con SKILL.md, así que la jerarquía intermedia es organización humana. Lo que sí sigue siendo obligatorio en cada hoja es que name coincida con el directorio padre inmediato: en skills/cloud/gcloud/SKILL.md el frontmatter declara name: gcloud, no cloud/gcloud.

Cuatro formas de instalar desde un repositorio

# 1. Copiar un skill concreto
git clone --depth 1 https://github.com/google/skills.git /tmp/gskills
cp -r /tmp/gskills/skills/cloud/gcloud ~/.agents/skills/gcloud

# 2. Clonar el repositorio completo dentro del directorio de skills
#    Cada subdirectorio con SKILL.md queda descubierto automáticamente
git clone https://github.com/mi-org/skills-equipo.git ~/.agents/skills/equipo

# 3. Submódulo, para fijar el catálogo del equipo dentro de un proyecto
cd mi-repo
git submodule add https://github.com/mi-org/skills-equipo.git .agents/skills/equipo
git submodule update --init --recursive

# 4. Enlace simbólico, para desarrollar un skill sin copiarlo en cada cambio
ln -s ~/Desarrollos/mi-skill ~/.agents/skills/mi-skill

Diferencias que importan:

Copiar desacopla: tu copia no cambia cuando cambia el origen. Bien para estabilidad, mal para recibir correcciones.
Clonar te deja actualizar con git pull, pero arrastra todo el catálogo del origen, incluidos skills que no quieres en tu contexto. Recuerda que cada skill instalado consume unos 50-100 tokens de catálogo en cada sesión.
Submódulo fija un commit exacto y lo registra en el repositorio del proyecto: es la opción reproducible para equipos.
Symlink es para desarrollo, no para distribución. El comportamiento con enlaces simbólicos depende del cliente y no está definido por la spec.

Instalación desde un repositorio público

Toma google/skills como caso real. Su README.md propone dos vías distintas según lo que quieras.

Para skills sueltos, el README documenta un instalador de terceros:

npx skills add google/skills

Y explica: “From the npx install command, you can select the specific skills from this repo to install”. Es una herramienta del ecosistema (con insignia de skills.sh en el README), no parte de la especificación: instalar un skill sigue siendo copiar una carpeta, y ese comando automatiza la selección y la copia.

Para los plugins que el mismo repositorio empaqueta, el README da comandos por harness:

Harness	Instalación
Claude Code	`claude plugin marketplace add google/skills`, luego `claude plugin install <plugin>@google-plugins`
Codex	`codex plugin marketplace add google/skills`, luego instalar desde el explorador `/plugins`
Antigravity CLI	`agy plugin install https://github.com/google/skills/<plugin-path>`

Que un mismo repositorio ofrezca ambas vías es exactamente la frontera que este capítulo tiene que explicar, y la retomamos más abajo.

Antes de instalar: revisión mínima

Instalar un skill es dejar que un texto ajeno entre en el contexto de tu agente y, si trae scripts/, que se ejecute código en tu máquina. Revisión mínima antes de copiar la carpeta:

# 1. Leer el SKILL.md entero. Es texto que el modelo obedecera.
cat ~/.agents/skills/gcloud/SKILL.md

# 2. Revisar que scripts trae y que hacen
find ~/.agents/skills/gcloud -type f -name "*.py" -o -name "*.sh"

# 3. Validar el formato con la biblioteca de referencia
skills-ref validate ~/.agents/skills/gcloud

skills-ref validate comprueba que el frontmatter es válido y que se cumplen las convenciones de nombres. No dice nada sobre si el contenido es correcto o seguro: eso lo lees tú. Y para saber si el skill hace lo que promete en tu entorno, el instrumento es el del capítulo anterior: evaluar la calidad con evals.

Presta atención especial a la description: un skill instalado con una description demasiado amplia se disparará en tareas que no le tocan y degradará todo lo demás. Es el problema del capítulo 6, agravado porque el texto no lo escribiste tú.

Versionado y control de cambios

La especificación no define un campo de versión obligatorio. Lo que ofrece es el campo opcional metadata, un mapa de claves y valores string para propiedades que la spec no define. El propio ejemplo canónico de la spec lo usa así:

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

Dos cosas a notar: el valor va entre comillas porque metadata mapea strings a strings, y la spec recomienda que las claves sean razonablemente únicas para evitar conflictos accidentales entre clientes. Ese version es informativo: ningún cliente está obligado a interpretarlo, resolver dependencias ni comparar versiones.

El versionado real, por tanto, lo pone git.

flowchart LR
    A["Editar SKILL.md<br/>o recursos"] --> B["skills-ref validate"]
    B --> C["Ejecutar el eval set"]
    C --> D{"Tasa de disparo<br/>y calidad OK"}
    D -->|No| A
    D -->|Sí| E["Commit atómico"]
    E --> F["Tag de versión"]
    F --> G["Consumidores fijan el tag<br/>o el commit"]

google/skills muestra el pinning en su forma más estricta: los plugins que bundlea son submódulos de git declarados en .gitmodules con una rama o tag concreto, y su manifiesto los declara con un ref explícito:

{
  "name": "alloydb",
  "source": {
    "source": "github",
    "repo": "gemini-cli-extensions/alloydb",
    "ref": "0.2.0"
  },
  "description": "Create, connect, and interact with an AlloyDB for PostgreSQL database and data."
}

La lección aplica igual a un skill suelto: si dependes de un catálogo ajeno, fija un tag o un commit. Un git pull sin control puede cambiar la description de un skill que llevas meses usando y alterar cuándo se dispara, sin que nada falle de forma visible.

Qué cambios son peligrosos

Cambio	Riesgo	Qué hacer
Editar la `description`	Alto: cambia cuándo se activa el skill, y eso no da error	Re-ejecutar el eval set de disparo antes de publicar
Renombrar el directorio	Alto: `name` DEBE coincidir con el directorio padre; si no, el skill deja de cargar o carga con aviso	Renombrar directorio y `name` en el mismo commit
Mover un archivo de `references/`	Medio: las rutas relativas del `SKILL.md` quedan rotas y el agente no lo detecta hasta necesitarlas	Buscar y actualizar todas las referencias
Añadir pasos al cuerpo	Medio: el cuerpo completo entra en contexto al activar; crecer sin control encarece cada activación	Vigilar el tamaño; mover detalle a `references/`
Cambiar un script de `scripts/`	Medio: cambia comportamiento sin cambiar instrucciones	Probar el script aislado y con el agente
Añadir `compatibility`	Bajo: es informativo	Solo si hay requisitos reales de entorno

Los dos primeros son los que muerden. Un name que ya no coincide con su directorio es un incumplimiento de la spec, aunque algunos clientes sean tolerantes y carguen igual avisando; no puedes contar con esa tolerancia. Y una description retocada “para que quede más clara” es la causa más habitual de que un skill deje de dispararse sin que nadie entienda por qué.

Regla práctica: un commit por cambio de comportamiento, con el eval set pasado. El historial de git de un skill debe permitir responder “¿desde cuándo se dispara en este caso?” leyendo diffs.

La frontera con los plugins

Aquí es donde empieza el curso hermano, y conviene trazar la línea con precisión porque se confunde a diario.

Un skill suelto es lo que define la especificación: un directorio con SKILL.md y, opcionalmente, scripts/, references/ y assets/. No tiene manifiesto, no declara dependencias, no registra herramientas ni servidores. Se instala copiando la carpeta a un directorio escaneado. Es la unidad mínima e interoperable: funciona en cualquier cliente conforme sin adaptación.

Un plugin es una unidad de empaquetado y distribución de nivel superior. Agrupa varios componentes —entre ellos, uno o varios skills, y también servidores MCP— bajo un manifiesto propio, se publica en un marketplace y se instala con el gestor de plugins del harness. El README de google/skills lo describe en una línea: “This repo also bundles Google product plugins (Skills + MCP servers) for agent harnesses.”

flowchart TD
    subgraph S["Skill suelto: definido por la especificación"]
        S1["SKILL.md"]
        S2["scripts/"]
        S3["references/"]
        S4["assets/"]
    end
    subgraph P["Plugin: capa de empaquetado del harness"]
        P1["Manifiesto del plugin"]
        P2["Uno o varios skills"]
        P3["Servidores MCP"]
        P4["Otros componentes del harness"]
    end
    S -.->|"puede ir dentro de"| P2
    P1 --> M["Marketplace"]
    M --> I["Instalación por gestor de plugins"]
    S -.->|"instalación directa:<br/>copiar la carpeta"| D["Directorio de skills escaneado"]

Comparación directa:

	Skill suelto	Plugin que contiene skills
Definido por	La especificación de Agent Skills	El formato de plugins del harness
Unidad	Un directorio con `SKILL.md`	Un paquete con manifiesto
Puede incluir servidores MCP	No	Sí
Instalación	Copiar la carpeta a un directorio escaneado	Gestor de plugins y marketplace
Portabilidad	Cualquier cliente conforme	Los harnesses que soportan ese formato de plugin
Versionado	Git del repositorio que lo contiene	Manifiesto y `ref` del marketplace
Descubrimiento por el agente	Idéntico: el cliente encuentra el `SKILL.md`	Idéntico, una vez instalado

El punto clave está en la última fila: una vez instalado, el agente no distingue. Un skill que llegó copiado a mano y uno que llegó dentro de un plugin se descubren igual, se catalogan igual y se activan igual. El plugin resuelve la logística —qué se instala junto a qué, desde dónde, en qué versión, con qué servidores MCP asociados—, no cambia el formato del skill.

google/skills es la demostración en un solo repositorio: por un lado skills/ con 103 archivos SKILL.md instalables sueltos (89 en cloud/, 12 en ads/, 2 en analytics/ al momento de esta consulta), y por otro plugins/ junto a manifiestos de marketplace en .claude-plugin/marketplace.json y .agents/plugins/marketplace.json. Mismo contenido conceptual, dos superficies de distribución.

Cuándo basta un skill y cuándo empaquetar

Basta un skill suelto cuando lo que distribuyes es conocimiento y procedimiento: instrucciones, referencias, plantillas y, como mucho, scripts autocontenidos. Es el 90% de los casos y la opción con mejor portabilidad.

Empaquetar en plugin aporta cuando necesitas alguna de estas: distribuir varios skills que solo tienen sentido juntos, acompañarlos de servidores MCP que dan acceso a APIs o datos, fijar versiones de forma explícita para un equipo, o publicar en un marketplace del que otros instalen con un comando.

El formato de plugins, sus manifiestos, los marketplaces y la relación con MCP son el tema del curso hermano: Agent Plugins Spec. Aquí termina la parte del estándar de skills; allí empieza la capa de empaquetado.

Catálogos públicos reales

Un aviso primero, porque ahorra búsquedas inútiles: la documentación oficial de Agent Skills no mantiene un directorio de skills de la comunidad. Su CONTRIBUTING.md es explícito: no se aceptan envíos de skills y no existe tal directorio, aunque señala que podría cambiar en el futuro. El Client Showcase de agentskills.io lista clientes que soportan el formato, no skills.

Lo que sí existe son catálogos publicados por organizaciones:

anthropics/skills — enlazado desde la documentación oficial como Example Skills y desde las guías de creación. Ahí vive skill-creator, el skill que la propia documentación cita para automatizar el ciclo de evals y mejora de descripciones que vimos en el capítulo 9.
google/skills — catálogo oficial de skills para productos y tecnologías de Google, con 103 SKILL.md en el momento de esta consulta, organizados en cloud, ads y analytics, bajo licencia Apache 2.0. Su política de contribución es cerrada: no acepta pull requests externos porque cada skill pasa por verificación interna, pero sí acepta issues y fomenta explícitamente fork & remix. Tiene curso propio en esta trilogía: Google Skills.
Repositorios satélite de Google, enlazados desde su propio README: flutter/skills, dart-lang/skills, genkit-ai/skills, los skills de Firestore en firebase/agent-skills y los de ADK en google/agents-cli.

Estudiar catálogos ajenos es, además, la mejor forma de calibrar tu propia escritura: leer diez SKILL.md de un catálogo mantenido enseña más sobre longitud, tono y estructura que cualquier lista de reglas.

Checklist de distribución

Antes de publicar un skill para otros:

Resumen

La especificación define qué hay dentro de un directorio de skill, no dónde vive; instalar un skill es copiar su carpeta a un directorio que el cliente escanee.
Los ámbitos habituales son usuario (~/.agents/skills/, ~/.<cliente>/skills/), proyecto (<project>/.agents/skills/, <project>/.<cliente>/skills/) y, cuando el despliegue lo requiere, organización o skills empaquetados con el propio agente.
.agents/skills/ es una convención emergente de amplia adopción para interoperabilidad entre clientes, no un requisito de la spec.
Ante colisiones de name, la convención universal es que proyecto gana sobre usuario; dentro del mismo ámbito, cada cliente elige una regla y la aplica de forma consistente.
Los skills de proyecto viajan con el repositorio, lo que es su virtud y su riesgo: la guía sugiere condicionar su carga a una comprobación de confianza.
En agentes cloud o en sandbox, los skills de usuario y organización no existen en el entorno y hay que aprovisionarlos desde fuera: repositorio de configuración, URLs o paquetes, o subida por UI.
Git es el mecanismo natural de distribución: copiar, clonar, submódulo o symlink, cada uno con distinta relación entre actualizaciones y reproducibilidad.
La spec no define un campo de versión; metadata.version es informativo y el versionado real lo dan los tags y commits de git.
Los cambios más peligrosos son editar la description y renombrar el directorio sin ajustar name: ninguno de los dos falla de forma ruidosa.
Un skill suelto es la unidad de la especificación; un plugin es una capa de empaquetado del harness que puede contener varios skills y servidores MCP, con manifiesto y marketplace. Una vez instalados, el agente los descubre igual.
google/skills muestra ambas superficies en un mismo repositorio: 103 SKILL.md instalables sueltos y plugins con manifiestos de marketplace.
No existe un directorio oficial de skills de la comunidad: agentskills.io lista clientes, no skills.

Siguiente: El ecosistema: qué clientes soportan skills y en qué se diferencian