CommunityRedacción y edicióngithub.com

GitHub CLI (`gh`)

Habilidades de agente cuidadosamente elaboradas y eficientes en tokens para flujos de trabajo de agentes confiables.

¿Qué es GitHub CLI (`gh`)?

Esta habilidad de agente proporciona una interfaz completa y eficiente en tokens para interactuar con GitHub desde la línea de comandos a través del CLI `gh`. Cubre una amplia gama de funcionalidades de GitHub, incluyendo la gestión de repositorios (vista, clonación, lectura de archivos remotos), issues, pull requests, releases, discussions, búsqueda en múltiples categorías (issues, PRs, código, commits, repositorios) y flujos de trabajo de Actions. La habilidad está diseñada para minimizar el consumo de tokens al priorizar la salida de texto predeterminada sobre `--json`, recomendar la clonación para exploración de múltiples archivos, y sugerir el alcance de la salida (por ejemplo, `--name-only`) antes de recuperar contenido completo. Proporciona pautas de seguridad explícitas para operaciones de escritura, comandos de vista previa y fallbacks de API para versiones antiguas de `gh`. La referencia detallada incluye banderas comunes, opciones de filtrado, campos JSON clave y enlaces a documentación de referencia complementaria para discussions, issues y pull requests, asegurando que los agentes de IA puedan ejecutar tareas de GitHub de forma fiable y autónoma.

Compatible con~Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add MichaelYochpaz/agent-skills

Installed? Explore more Redacción y edición skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

GitHub CLI (gh)

Interactúa con GitHub desde la línea de comandos: repositorios, releases, issues, PRs, discussions, búsqueda, revisión de código y Actions.

Verificado con gh 2.95.0.

Pautas para el agente

  • Para archivos o directorios remotos conocidos, usa gh repo read-file / gh repo read-dir (vista previa en gh 2.95). Para versiones antiguas de gh o necesidades solo de API, usa el fallback de la API de contenidos en API Patterns.
  • Cuando una tarea requiera buscar en varios archivos o explorar código desconocido donde las rutas no se conocen de antemano, clona a un directorio temporal (gh repo clone owner/repo <temp-dir> -- --depth 1) y usa herramientas locales de lectura y búsqueda de archivos.
  • Prefiere la salida de texto predeterminada sobre --json para leer/visualizar; es más eficiente en tokens. Usa --json con --jq solo cuando extraigas campos específicos de forma programática. Para descubrir los campos admitidos, ejecuta el comando con --json y sin lista de campos, luego solicita solo los campos que necesites.
  • Al ver logs o diffs, primero acota la salida (por ejemplo, --name-only, --log-failed) antes de obtener el contenido completo.
  • La bandera --repo no es necesaria cuando se ejecuta dentro de un repositorio clonado; el repositorio del directorio actual se usa por defecto. Para gh api, usa la ruta explícita (repos/OWNER/REPO/...) o establece la variable de entorno GH_REPO.
  • Usa esta habilidad para los flujos de trabajo cubiertos. Cuando falte una bandera o campo necesario, un comando falle con una bandera desconocida o modificada, o el comando esté marcado como vista previa, consulta la ayuda de ese comando específico (por ejemplo, gh pr diff --help).

Seguridad

  • Operaciones de escritura (create, edit, comment, review, close, merge, delete, rerun, run cancel, workflow run/enable/disable, mutaciones de discussion) modifican el estado de GitHub. Confirma con el usuario antes de ejecutarlas, especialmente en repositorios que no te pertenecen.
  • gh api con --method POST/PUT/PATCH/DELETE envía solicitudes de escritura. Verifica el endpoint y la carga útil. El método predeterminado es GET (seguro); agregar parámetros -f/-F cambia el método predeterminado a POST.
  • Operaciones destructivas (delete, close, merge --admin) pueden ser irreversibles. Requieren confirmación explícita del usuario.

Prerrequisitos

Verifica que gh esté instalado y autenticado antes de ejecutar comandos:

gh --version
gh auth status

Si no está autenticado, guía al usuario a través de gh auth login.

Banderas comunes

Estas banderas están disponibles en muchos grupos de comandos, pero la compatibilidad varía según el comando:

  • --repo OWNER/REPO -- Apunta a un repositorio diferente (predeterminado: repositorio del directorio actual). También acepta URLs completas.
  • --json FIELDS -- Salida como JSON con los campos especificados. Pasa sin valor para listar los campos disponibles.
  • --jq EXPRESSION -- Filtra la salida JSON usando sintaxis de jq. Requiere --json.
  • --template STRING -- Formatea la salida JSON usando una plantilla Go (alternativa a --jq).
  • --web -- Abre el recurso en el navegador en lugar de mostrarlo en la terminal.
  • --limit N -- Número máximo de resultados para comandos de lista (el valor predeterminado suele ser 30).

Repositorios

Ver

Muestra la descripción, README, estrellas, desglose de lenguaje y otros metadatos de un repositorio.

gh repo view owner/repo
gh repo view owner/repo --json name,description,defaultBranchRef,languages,stargazerCount

Clonar

Clona un repositorio localmente. Configura automáticamente el remoto y, para forks, configura el remoto upstream.

gh repo clone owner/repo [target-directory]

Leer contenidos de repositorio remoto

Para lecturas rápidas de archivos o directorios conocidos, usa los comandos de lectura de repositorio (vista previa en gh 2.95):

# Archivo conocido
gh repo read-file src/main.py --repo owner/repo --ref main

# Directorio conocido
gh repo read-dir src --repo owner/repo --ref main

# Fallback para versiones antiguas de gh
gh api "repos/OWNER/REPO/contents/src/main.py?ref=main" -H "Accept: application/vnd.github.raw+json"

Para formas de salida, límites de tamaño de archivo y advertencias sobre listados de directorios, consulta API Patterns. Para exploración de múltiples archivos, clona en su lugar (consulta las Pautas para el agente).

Listar repositorios

Lista repositorios propiedad de un usuario u organización, con filtros opcionales de lenguaje y visibilidad.

gh repo list owner --limit 30

Releases

Listar

Lista releases en un repositorio, ordenadas por fecha de creación (más recientes primero). Por defecto muestra todos los releases, incluyendo pre-releases y borradores.

gh release list --repo owner/repo --limit 10

Banderas:

  • --exclude-pre-releases -- Excluir pre-releases
  • --exclude-drafts -- Excluir borradores

Campos JSON clave: tagName, name, publishedAt, isLatest, isDraft, isPrerelease, isImmutable

Ver (changelog, assets)

Muestra el cuerpo del changelog, etiqueta, assets y metadatos de un release. Omite la etiqueta para ver el último release.

gh release view --repo owner/repo                         # Último release
gh release view v1.2.0 --repo owner/repo                  # Etiqueta específica
gh release view v1.2.0 --json tagName,body,assets,publishedAt

Campos JSON clave: tagName, name, body, assets, author, publishedAt, isDraft, isPrerelease, isImmutable, url

Issues

Listar

Lista issues en un repositorio, filtrados por estado, etiqueta, asignado o consulta de búsqueda. Por defecto solo muestra issues abiertos.

gh issue list --repo owner/repo
gh issue list --repo owner/repo --state all --label bug --assignee @me
gh issue list --repo owner/repo --search "error no:assignee sort:created-asc"

Banderas:

  • --state VALUE -- open (predeterminado), closed, all
  • --label NAME -- Filtrar por etiqueta (repetir para múltiples)
  • --assignee LOGIN -- Filtrar por asignado (@me para uno mismo)
  • --search QUERY -- Sintaxis de búsqueda de GitHub

Campos JSON clave: number, title, state, stateReason, author, labels, assignees, createdAt, updatedAt, url

Ver

Muestra el título, cuerpo, etiquetas, asignados y estado de un issue. Usa --comments para incluir el hilo de comentarios completo.

gh issue view 123
gh issue view 123 --comments
gh issue view 123 --json title,body,labels,comments,state

Crear

Crea un nuevo issue con título, cuerpo, etiquetas y asignados.

gh issue create --title "Bug: descripción" --body "Detalles..." --label bug --assignee user1

Editar

Actualiza el título, cuerpo, etiquetas, asignados o hito de un issue. Todas las banderas se pueden combinar en una sola llamada.

Banderas:

  • --title TEXT / --body TEXT -- Actualizar título o cuerpo
  • --add-label NAME / --remove-label NAME -- Modificar etiquetas
  • --add-assignee LOGIN / --remove-assignee LOGIN -- Modificar asignados
  • --milestone NAME / --remove-milestone -- Establecer o eliminar hito

Comentar

Agrega un comentario a un issue existente.

gh issue comment 123 --body "Texto del comentario"

Cerrar / Reabrir

Cierra o reabre un issue. Opcionalmente especifica un motivo de cierre y deja un comentario.

gh issue close 123 --comment "Corregido en PR #456" --reason "not planned"
gh issue close 123 --duplicate-of 456
gh issue reopen 123

Motivos de cierre: completed (predeterminado), not planned, duplicate.

Estado

Muestra un resumen de issues relevantes para ti: asignados a ti, que te mencionan y que has abierto.

gh issue status

Para tipos de issues, sub-issues, relaciones padre-hijo, dependencias de bloqueo y sus campos JSON (requiere hosts de GitHub compatibles), consulta Issues reference.

Pull Requests

Usa estos comandos para ver e inspeccionar PRs. Para crear, fusionar, revisar y gestionar PRs, consulta Pull Requests reference.

Listar

Lista pull requests en un repositorio, filtrados por estado, autor, etiqueta o consulta de búsqueda. Por defecto solo muestra PRs abiertos.

gh pr list --repo owner/repo
gh pr list --repo owner/repo --state all --author @me --label "needs-review"
gh pr list --repo owner/repo --search "status:success review:required"
gh pr list --repo owner/repo --app dependabot

Banderas:

  • --state VALUE -- open (predeterminado), closed, merged, all
  • --draft -- Filtrar por estado de borrador
  • --author LOGIN / --assignee LOGIN -- Filtrar por autor o asignado
  • --label NAME -- Filtrar por etiqueta
  • --search QUERY -- Sintaxis de búsqueda de GitHub
  • --app NAME -- Filtrar por autor de GitHub App (por ejemplo, dependabot)

Campos JSON clave: number, title, state, author, headRefName, baseRefName, labels, reviewDecision, isDraft, statusCheckRollup, files, commits, reviews, url

Ver

Muestra el título, cuerpo, estado de revisión, comprobaciones y otros metadatos de un PR. Sin argumento, muestra el PR de la rama actual. Usa --comments para incluir el hilo de comentarios.

gh pr view 123
gh pr view 123 --comments
gh pr view 123 --json title,body,files,commits,reviews,reviewDecision

Estado

Muestra un resumen de PRs relevantes para ti: el PR de la rama actual, PRs que creaste y PRs donde se solicita tu revisión.

gh pr status

Discussions

Usa gh discussion para Discussions de repositorio (vista previa en gh 2.94). Comienza con comandos de lectura y verifica las banderas con --help porque el conjunto de comandos está en vista previa:

gh discussion list --repo owner/repo --limit 10
gh discussion view 123 --repo owner/repo --comments

Para crear, editar, comentar, hilos de respuesta, formas de salida JSON y patrones de fallback de GraphQL, consulta Discussions reference.

Búsqueda

Busca en GitHub issues, PRs, código, commits y repositorios. Usa gh issue list / gh pr list para un repositorio; usa gh search ... para consultas entre repositorios o de todo el propietario.

Para la sintaxis completa de consulta de búsqueda, consulta la documentación de búsqueda de GitHub. Para banderas específicas de cada subcomando, ejecuta gh search <subcommand> --help.

Límites de velocidad: Las APIs de búsqueda tienen límites de velocidad más estrictos que la API principal. La búsqueda de código es la más restrictiva (~10/min autenticado; requiere autenticación). Otros comandos de búsqueda permiten ~30/min autenticado o ~10/min no autenticado. Verifica la cuota actual con gh api rate_limit --jq '.resources | {search, code_search}'.

Cuándo clonar en su lugar: Consulta las Pautas para el agente para saber cuándo clonar en lugar de usar la API.

Bots y aplicaciones: Para autores de GitHub App como Dependabot, usa --app dependabot; --author dependabot filtra cuentas de usuario, no autores de aplicaciones.

Reconocimiento: Al buscar en un repositorio desconocido, primero verifica su lenguaje principal para seleccionar los valores correctos de --extension y --language:

gh repo view owner/repo --json primaryLanguage --jq '.primaryLanguage.name'

Issues

Busca issues entre repositorios usando palabras clave, etiquetas, estado o sintaxis de búsqueda de GitHub.

gh search issues "manejo de errores" --repo owner/repo
gh search issues --label bug --state open --assignee @me
gh search issues --app dependabot --repo owner/repo
gh search issues --involves username --comments ">10" --repo owner/repo

Banderas clave: --repo, --owner, --state, --label, --assignee, --author, --app, --involves, --comments, --match, --sort, --include-prs.

PRs

Busca pull requests entre repositorios. Soporta filtrado por autor, estado de revisión, estado de fusión y estado de borrador.

gh search prs "refactor" --repo owner/repo
gh search prs --review-requested @me --state open
gh search prs --app dependabot --repo owner/repo
gh search prs --author username --merged --repo owner/repo

Banderas clave: --repo, --owner, --state, --merged, --draft, --author, --assignee, --app, --label, --review, --review-requested, --base, --head, --checks, --sort.

Código

Busca dentro del contenido de archivos en repositorios de GitHub. Devuelve solo las líneas coincidentes (sin números de línea, sin contexto circundante). Útil para localizar archivos que contienen un patrón, pero luego lee los archivos o clona el repositorio para entender la lógica del código.

Limitaciones: Usa un motor de búsqueda heredado (los resultados pueden no coincidir con github.com). Solo busca en la rama predeterminada. Solo se indexan archivos de menos de 384 KB. Cada consulta debe incluir al menos un término de búsqueda (las búsquedas solo con calificadores como --extension ts solas fallarán). No soporta --sort ni --order; los resultados siempre se clasifican por relevancia.

gh search code "nombreDeFuncion" --repo owner/repo
gh search code "createServer" --repo owner/repo --extension ts
gh search code "lint" --repo owner/repo --filename package.json

Banderas clave: --repo, --owner, --extension, --filename, --language, --match, --size.

Campos JSON clave: path, repository, sha, textMatches, url.

El campo textMatches proporciona contexto de fragmento con posiciones de coincidencia a nivel de carácter: usa --json path,textMatches cuando necesites más contexto del que proporciona la salida de texto predeterminada.

Commits

Busca commits por texto del mensaje, autor, fecha del committer o hash.

gh search commits "corregir error" --repo owner/repo
gh search commits --author username --committer-date ">2024-01-01"
gh search commits --hash abc1234

Banderas clave: --repo, --owner, --author, --committer, --author-date, --committer-date, --author-name, --author-email, --hash, --merge, --sort.

Repositorios

Busca repositorios por palabra clave, lenguaje, tema, estrellas, licencia o propietario. Nota: --repo no está disponible en este subcomando; usa --owner para filtrar por propietario.

gh search repos "palabra clave" --language python --sort stars --order desc
gh search repos --topic cli --stars ">1000" --language go

Banderas clave: --owner, --language, --topic, --stars, --forks, --license, --created, --updated, --match, --sort, --include-forks, --visibility.

Exclusiones de calificadores (prefijo de guión)

Las consultas de búsqueda con exclusiones como -label:bug necesitan sintaxis especial para evitar la interpretación de banderas del shell. Todas las banderas (por ejemplo, --limit) deben aparecer antes de --; cualquier cosa después de -- se interpreta como texto de la consulta de búsqueda:

# Shells tipo Unix
gh search issues -- "mi consulta -label:bug"

# PowerShell
gh --% search issues -- "mi consulta -label:bug"

Skills relacionados