Agent-Skills.md

Agent Skills: GitHub CLI (gh)

|

UncategorizedID: testacode/llm-toolkit/gh-cli

Repository

testacode/llm-toolkit
testacodeLicense: Apache-2.0

Install this agent skill to your local

pnpm dlx add-skill https://github.com/testacode/llm-toolkit/tree/HEAD/skills/gh-cli

Skill Files

Browse the full folder contents for gh-cli.

Download Skill

Loading file tree…

skills/gh-cli/SKILL.md

Skill Metadata

Name
gh-cli
Description
|

GitHub CLI (gh)

Referencia completa de GitHub CLI (gh) para trabajar con GitHub desde la terminal.

Version Check

Documentado para: v2.87.3 (February 2026)

Antes de usar esta referencia, verifica tu version:

gh --version

Si tu version difiere significativamente de v2.87.3, algunos comandos o flags pueden haber cambiado. Consulta gh help <command> para confirmar.

Top Commands (por frecuencia de uso real)

# PRs — el grupo mas usado
gh pr view 123                         # Ver PR (con --web para browser)
gh pr comment 123 --body "LGTM!"      # Comentar PR
gh pr create --draft --title "feat: X" # Crear PR
gh pr diff 123                         # Ver diff
gh pr checks 123 --watch               # Watch CI checks
gh pr review 123 --approve             # Aprobar PR
gh pr merge 123 --squash --delete-branch
gh pr list --author @me --json number,title

# API — segundo mas usado
gh api repos/owner/repo --jq '.stargazers_count'
gh api /user --jq '.login'
gh api graphql -f query='{ viewer { login } }'

# Repos
gh repo view                           # Info del repo actual
gh repo create my-repo --public --clone
gh repo clone owner/repo

# Runs (CI)
gh run view 123456 --log               # Ver logs del run
gh run list --workflow ci.yml --limit 5
gh run watch 123456 --exit-status      # Watch con exit code
gh run rerun 123456                    # Re-ejecutar run fallido

# Search
gh search prs "is:open review:required"
gh search issues "label:bug state:open"
gh search commits "fix critical"

# Auth
gh auth status                         # Ver cuenta activa
gh auth switch                         # Cambiar cuenta
gh auth login                          # Login interactivo

Quick Start

# Instalar
brew install gh          # macOS
# Ver references/auth-config.md para Linux/Windows

# Autenticarse
gh auth login

# Configurar git
gh auth setup-git

# Verificar
gh auth status

CLI Structure

gh
├── auth                    # Autenticacion
│   ├── login, logout, refresh, setup-git, status, switch, token
├── browse                  # Abrir en browser
├── repo                    # Repositorios
│   ├── create, list, clone, view, edit, delete, fork, sync
│   ├── archive, unarchive, rename, set-default
│   └── autolink, deploy-key, gitignore, license
├── issue                   # Issues
│   ├── create, list, view, edit, close, reopen, comment, delete
│   └── develop, lock, unlock, pin, unpin, transfer, status
├── pr                      # Pull Requests
│   ├── create, list, view, checkout, diff, merge, close, reopen
│   ├── edit, comment, review, ready, checks, status
│   └── lock, unlock, revert, update-branch
├── project                 # Projects v2
│   ├── create, list, view, edit, delete, close, copy
│   ├── field-create, field-delete, field-list
│   └── item-add, item-create, item-edit, item-delete, item-list, item-archive
├── release                 # Releases
│   ├── create, list, view, edit, delete, download, upload
│   └── delete-asset, verify, verify-asset
├── run                     # Workflow Runs (Actions)
│   ├── list, view, watch, rerun, cancel, delete, download
├── workflow                # Workflows (Actions)
│   ├── list, view, run, enable, disable
├── cache                   # Actions Caches
│   ├── list, delete
├── secret                  # Actions Secrets
│   ├── list, set, delete
├── variable                # Actions Variables
│   ├── list, get, set, delete
├── gist                    # Gists
│   ├── create, list, view, edit, delete, rename, clone
├── codespace               # Codespaces
│   ├── create, list, view, ssh, code, stop, delete, logs, ports, cp
├── search                  # Busqueda
│   ├── code, commits, issues, prs, repos
├── org                     # Organizaciones
│   └── list
├── label                   # Labels
│   ├── create, list, edit, delete, clone
├── api                     # Requests directos a la API
├── alias                   # Aliases de comandos
│   ├── set, list, delete, import
├── extension               # Extensiones
│   ├── install, list, search, upgrade, remove, create, browse
├── config                  # Configuracion
│   ├── get, set, list, clear-cache
├── ssh-key / gpg-key       # Claves SSH/GPG
├── ruleset                 # Rulesets
│   ├── list, view, check
├── attestation             # Atestaciones de artefactos
├── completion              # Shell completion
├── status                  # Overview de notificaciones
└── agent-task              # Agent tasks (preview)

Que Comando Usar

| Necesidad | Comando | Ejemplo | |-----------|---------|---------| | Crear PR desde branch actual | gh pr create | gh pr create --title "feat: X" --draft | | Ver estado de mis PRs/issues | gh pr status / gh issue status | gh pr status | | Checkout PR de otro dev | gh pr checkout | gh pr checkout 123 | | Mergear PR | gh pr merge | gh pr merge 123 --squash --delete-branch | | Crear issue con labels | gh issue create | gh issue create --title "Bug" --labels bug | | Crear branch desde issue | gh issue develop | gh issue develop 123 --branch fix/123 | | Ver CI status de un PR | gh pr checks | gh pr checks 123 --watch | | Trigger workflow manual | gh workflow run | gh workflow run deploy.yml --ref main | | Ver logs de un run | gh run view | gh run view 123 --log | | Buscar codigo en GitHub | gh search code | gh search code "TODO" --repo owner/repo | | Hacer request a la API | gh api | gh api /repos/owner/repo --jq '.stargazers_count' | | Crear release con assets | gh release create | gh release create v1.0 --notes-file CHANGELOG.md *.tar.gz | | Gestionar secrets de CI | gh secret set | echo "$TOKEN" \| gh secret set MY_SECRET | | Fork + sync | gh repo fork + gh repo sync | gh repo fork owner/repo --clone |

Common Workflows

PR desde Issue

gh issue develop 123 --branch feature/issue-123
# ... hacer cambios, commit, push
gh pr create --title "Fix #123" --body "Closes #123"

Bulk Operations con jq

# Cerrar issues stale
gh issue list --search "label:stale" --json number --jq '.[].number' | \
  xargs -I {} gh issue close {} --comment "Closing as stale"

# Agregar label a PRs pendientes de review
gh pr list --search "review:required" --json number --jq '.[].number' | \
  xargs -I {} gh pr edit {} --add-label needs-review

CI/CD Watch

gh workflow run ci.yml --ref main
gh run list --workflow ci.yml --limit 1 --json databaseId --jq '.[0].databaseId' | \
  xargs -I {} gh run watch {} --exit-status  # exit-status: non-zero si falla (util para scripts)

Nota: Para crear archivos YAML de GitHub Actions, ver la skill github-actions. Esta skill cubre los comandos CLI para interactuar con workflows y runs existentes.

Setup de Repo Nuevo

gh repo create my-project --public --clone --gitignore node --license mit
cd my-project
gh label create bug --color "d73a4a"
gh label create enhancement --color "a2eeef"

Global Flags

| Flag | Uso | |------|-----| | --json FIELDS | Output JSON con campos especificos | | --jq EXPR | Filtrar JSON output (syntax jq) | | --template STR | Formatear con Go template | | --web | Abrir en browser | | --repo OWNER/REPO | Seleccionar otro repo | | --hostname HOST | GitHub Enterprise hostname | | --paginate | Paginar resultados grandes |

JSON + jq Patterns

# Listar campos disponibles
gh pr list --json 2>&1 | head -5

# Filtrar por condicion
gh pr list --json number,title --jq '.[] | select(.number > 100)'

# Extraer valores anidados
gh repo view --json owner,name --jq '.owner.login + "/" + .name'

# Tab-separated output
gh issue list --json number,title --jq '.[] | [.number, .title] | @tsv'

Best Practices

  1. Set default repo para evitar --repo repetido: gh repo set-default
  2. Usar --json + --jq para scripting — nunca parsear output de texto
  3. GH_TOKEN env var para CI/automation: export GH_TOKEN=$(gh auth token)
  4. --paginate para datasets grandes (default: 30 items)
  5. Shell completion: eval "$(gh completion -s zsh)" en .zshrc
  6. Aliases para comandos frecuentes: gh alias set prview 'pr view --web'

Environment Variables

| Variable | Uso | |----------|-----| | GH_TOKEN | Token de autenticacion (CI/automation) | | GH_HOST | Hostname (default: github.com) | | GH_REPO | Override repo default | | GH_EDITOR | Editor para mensajes | | GH_PAGER | Pager para output largo | | GH_PROMPT_DISABLED | Deshabilitar prompts interactivos |

Reference Files

Para referencia detallada de cada grupo de comandos:

  • references/auth-config.md — Autenticacion, configuracion, env setup
  • references/repos.md — Repositorios: create, clone, list, view, edit, fork, sync
  • references/issues.md — Issues: CRUD, labels, pins, locks, transfer, develop
  • references/pull-requests.md — Pull Requests: create, merge, review, checks, diff
  • references/actions.md — GitHub Actions: workflow, run, cache, secret, variable
  • references/projects-releases.md — Projects v2 y Releases
  • references/advanced.md — Gist, codespace, org, search, api, extensions, aliases, rulesets

Help

gh --help              # Ayuda general
gh pr --help           # Ayuda de un comando
gh issue create --help # Ayuda de un subcomando
gh help formatting     # Topics: formatting, environment, exit-codes

Links

  • Manual oficial: https://cli.github.com/manual/
  • GitHub Docs: https://docs.github.com/en/github-cli
  • REST API: https://docs.github.com/en/rest
  • GraphQL API: https://docs.github.com/en/graphql