gh skill: instala skills de Claude Code desde GitHub CLI

TL;DR: El 16/04/2026 GitHub lanzó gh skill en la versión 2.90.0 del CLI. Con un único comando puedes descubrir, instalar, fijar versiones y publicar skills de agente para Claude Code, Cursor, Codex o Gemini. Dejas de clonar repos a mano en ~/.claude/skills/ y empiezas a tratar tus skills como paquetes reproducibles entre máquinas.

El problema: tu setup de skills no viaja bien

Si llevas meses usando Claude Code, tu carpeta ~/.claude/skills/ es un pequeño caos. Carpetas clonadas con git clone, otras copiadas a mano desde Gists, algunas que ni recuerdas de dónde salieron. Cuando cambias de portátil o quieres que un compañero use tu mismo flujo, el proceso es manual y frágil.

El patrón de skills y subagentes como capa reutilizable ya se había consolidado como estándar, pero faltaba la pieza de distribución. Hasta ahora cada equipo improvisaba: scripts bash, submódulos de Git, instaladores propios. Con gh skill, GitHub mueve esa gestión al sitio donde ya vive el código.

¿Qué es gh skill?

gh skill es un subcomando oficial del GitHub CLI que instala, actualiza y publica agent skills desde cualquier repositorio público o privado de GitHub. Sigue la Agent Skills specification y funciona con Claude Code, GitHub Copilot, Cursor, Codex, Gemini CLI y Antigravity.

La diferencia frente a clonar un repo es la misma que hay entre git clone y npm install: metadatos de procedencia, versión fija, actualizaciones controladas y un único comando que coloca los archivos en el directorio correcto según el agente.

Requisitos previos

GitHub CLI v2.90.0 o superior (gh --version para comprobarlo).
Autenticación activa con gh auth login.
Claude Code instalado localmente si el destino es --agent claude-code.

Instalación paso a paso

1. Actualiza el CLI

En macOS con Homebrew, Ubuntu con apt o Windows con winget, el canal estable ya publica la 2.90.0. Verifica la versión antes de seguir:

# Comprueba versión y disponibilidad del nuevo subcomando
gh --version
gh skill --help

Si gh skill devuelve unknown command, actualiza el CLI. El subcomando es nativo, no es una extensión externa.

2. Descubre skills disponibles

El buscador consulta el índice público de repositorios que siguen el spec:

# Busca skills relacionadas con MCP y apps
gh skill search mcp-apps

Los resultados incluyen el repositorio, el nombre de la skill y la última versión publicada.

3. Instala una skill en Claude Code

Con --agent claude-code los archivos aterrizan en ~/.claude/skills/ (scope usuario) o en .claude/skills/ del repo (scope proyecto):

# Instala documentation-writer para Claude Code a nivel usuario
gh skill install github/awesome-copilot documentation-writer \
  --agent claude-code \
  --scope user

En modo interactivo, gh skill install github/awesome-copilot sin nombre te lista las skills del repo y las instalas marcándolas.

4. Fija la versión

Este paso es el que marca diferencia real en producción. Una skill es código ejecutable que altera el comportamiento del agente, así que un cambio silencioso puede romper flujos sin avisar:

# Pin por tag de release
gh skill install github/awesome-copilot documentation-writer --pin v1.2.0

# Pin por SHA para máxima reproducibilidad
gh skill install github/awesome-copilot documentation-writer --pin abc123def

El pin queda escrito en el SKILL.md local como metadato de procedencia. Cuando más adelante ejecutes gh skill update, solo cambiará si tú subes el pin.

Comandos clave en una tabla

Comando	Para qué sirve	Cuándo lo usas
`gh skill search`	Busca skills por palabra clave	Al explorar qué existe antes de construir la tuya
`gh skill install`	Instala una skill en el agente elegido	Setup inicial de máquina nueva u onboarding
`gh skill update`	Revisa y aplica actualizaciones	Mantenimiento periódico, respetando pins
`gh skill publish`	Publica tu skill con metadatos de release	Cuando empaquetas una skill interna para el equipo

Agentes compatibles y rutas de instalación

Agente	Flag	Ruta por defecto (scope user)
Claude Code	`--agent claude-code`	`~/.claude/skills/`
Cursor	`--agent cursor`	`~/.cursor/skills/`
Codex	`--agent codex`	`~/.codex/skills/`
Gemini CLI	`--agent gemini`	`~/.gemini/skills/`
GitHub Copilot	(por defecto)	`~/.copilot/skills/`

Caso real: compartir skills entre dos máquinas

Mi setup diario mezcla portátil y un servidor remoto. Antes sincronizaba ~/.claude/skills/ con un script rsync que se rompía cada vez que una skill añadía dependencias externas. Ahora la ruta es trivial:

# Máquina 1: lista lo instalado
gh skill list --agent claude-code

# Máquina 2: replica el setup con pines concretos
gh skill install github/awesome-copilot git-commit --pin v2.1.0 --agent claude-code
gh skill install myorg/internal-skills code-review --pin abc123 --agent claude-code

El paso lógico siguiente es meter esa lista en un script de bootstrap del repo o en tus dotfiles, junto con tu configuración de CLAUDE.md y tus servidores MCP activos. Así, un ./setup.sh deja la máquina nueva con el mismo comportamiento del agente que la anterior.

En Producción

Rendimiento y coste

gh skill no añade latencia en runtime: solo copia ficheros al directorio del agente. El coste es de red en el momento del install. Lo que sí puede crecer es tu contexto efectivo: si instalas 30 skills en scope user, todas están visibles para Claude Code aunque no las uses. Conviene mantener la lista curada, como apuntábamos al hablar de skills escritas automáticamente: cantidad no es calidad.

Seguridad y supply chain

Una skill puede ejecutar scripts. El flag --pin es la defensa básica: fija SHA en lugar de tag cuando la skill venga de un repo externo que no controlas. Para skills internas, publica desde una organización con protected branches y revisa el SKILL.md antes de cada bump de versión. Trátalas con el mismo rigor que tratas una dependencia de npm o PyPI.

Escala y límites

El comando está pensado para equipos de desarrollo, no para despliegues masivos. Si tu organización gestiona skills para cientos de desarrolladores, lo razonable es combinarlo con tu registro interno y automatizar gh skill install dentro de tu provisioning. Para un equipo pequeño, con ejecutar los comandos en el onboarding es suficiente.

Errores comunes y depuración

Error: unknown command "skill". Causa: CLI por debajo de 2.90.0. Solución: actualiza con el gestor de paquetes o reinstala desde releases de cli/cli.
Error: skill installed but not detected by Claude Code. Causa: scope incorrecto (project vs user). Solución: revisa si la sesión de Claude Code se abrió fuera del repo y usa --scope user si buscas disponibilidad global.
Error: permission denied al ejecutar scripts de la skill. Causa: permisos de ejecución perdidos al copiar. Solución: revisa el SKILL.md para los requisitos y aplica chmod +x a los scripts si procede.
Error: skill update fails with 404. Causa: el repo original borró la release fijada. Solución: migra el pin a un SHA o a un mirror interno.

Cuándo compensa y cuándo no

gh skill compensa cuando tu flujo depende de skills que viven en GitHub y quieres versiones fijas. No compensa si tus skills son 100% privadas y locales, sin intención de compartirlas; en ese caso, un repo con .claude/skills/ y un git pull sigue siendo más simple. La herramienta brilla en el punto intermedio: skills internas publicadas en tu organización, con tag semántico y rotación controlada.

Si todavía andas decidiendo qué skills merecen existir, antes de empaquetar conviene entender cómo está diseñado el harness de Claude Code para saber qué encaja mejor en una skill, una subagente o simplemente en tu CLAUDE.md.

Preguntas frecuentes

¿Necesito Copilot para usar gh skill con Claude Code?

No. gh skill forma parte del GitHub CLI y funciona sin suscripción a Copilot. Solo necesitas autenticación con gh auth login y la versión 2.90.0 o superior del CLI.

¿Dónde instala gh skill las skills para Claude Code?

Con --agent claude-code y --scope user, las coloca en ~/.claude/skills/. Con --scope project, las coloca en .claude/skills/ del repositorio actual, donde viajarán con el código.

¿Cómo actualizo skills sin romper mi flujo?

Fija la versión con --pin v1.2.0 o con un SHA. Así gh skill update respeta el pin y no aplica cambios hasta que tú decidas subir la versión, evitando regresiones silenciosas en el comportamiento del agente.

Cierre

gh skill mueve las skills de agente al mismo terreno donde ya vive nuestro código: repos, releases y SHAs. La consecuencia práctica es que el cómo de trabajar con Claude Code deja de ser una carpeta caótica en tu home y pasa a ser una lista declarativa, versionada y compartible. No resuelve qué skills tienes que escribir, pero sí cierra la distancia entre tener una buena skill y que todo tu equipo la use exactamente igual.

Si ya has migrado tu setup a gh skill, cuéntame en Twitter @sergiomarquezp_ qué skills externas te han aportado más. En el próximo post compararé la publicación de skills internas con gh skill publish frente a un marketplace privado, entrando en el detalle de gobernanza de versiones.