gh · Agent Skill · SuperAPI AI Directory

GitHub operations via the gh CLI. Wraps every common operation — PRs, issues, releases, workflow runs, repos, search — in idiomatic, token-efficient invocations.

git is read-only here — log, diff, status. No commits, no pushes, no PR creation through this skill. Pair with /plate (from the companion easy-cheese repo) for committing, pushing, and opening PRs — single or stacked.

CLI rules

Don't pipe gh into a separate jq binary. gh ships with --jq and --template flags; inlining them avoids spawning jq and triggering any compound-command sandbox heuristics some harnesses apply. Piping gh ... --jq into downstream consumers like xargs or sed is fine — the goal is to keep JSON extraction inside gh itself:

# wrong — needs jq binary, triggers a compound command
gh pr list --json number | jq '.[].number'

# right — inline jq, no pipe
gh pr list --json number --jq '.[].number'

# also fine — --jq inlined, then piped to xargs for a bulk op
gh pr list --json number --jq '.[].number' | xargs -I{} gh pr view {}

# Go template alternative
gh pr view 42 --json title --template '{{.title}}'

Never use heredoc --body for issue or comment bodies. The $(cat <<'EOF' ... EOF) pattern can trip "# hides arguments" sandbox heuristics when the body contains markdown headers. Write the body to a file and pass --body-file:

gh issue create --title "flaky health-endpoint test" \
  --body-file "$TMPDIR/issue-body.md" --label bug

Always check JSON field names with --help. They differ from the GitHub REST API names:

gh pr list --help | sed -n '/JSON FIELDS/,/^$/p'

Common gotchas: stargazerCount (not stargazersCount), forkCount (not forksCount), watchers (not watchersCount).

Pull requests

PR creation lives in /plate — this skill picks up once the PR exists.

# Request review on an existing PR
gh pr edit 123 --add-reviewer @copilot

# View
gh pr list                                       # repo PRs
gh pr list --author @me                          # mine
gh pr list --search "is:open label:bug"          # full search syntax
gh pr view 123
gh pr view 123 --web
gh pr diff 123
gh pr diff 123 --exclude '*.lock'                # skip lockfile noise

# Status & checks
gh pr status                                     # PRs touching you
gh pr checks 123                                 # CI checks for the PR
gh pr checks 123 --watch                         # block until done

# Review & merge
gh pr review 123 --approve --body "LGTM"
gh pr review 123 --request-changes --body-file review.md
gh pr merge 123 --squash --delete-branch
gh pr merge 123 --auto --squash                  # auto-merge when checks pass
gh pr update-branch 123                          # bring up to date with base

# Lifecycle
gh pr close 123
gh pr reopen 123
gh pr ready 123                                  # un-draft
gh pr revert 123                                 # creates new revert PR
gh pr checkout 123                               # check out PR branch locally

For --jq filter patterns and bulk operations, see references/jq-recipes.md. For end-to-end PR / release / CI scripts, see references/automation.md.

Issues

gh issue create --title "..." --body-file body.md --label bug
gh issue create --title "..." --assignee @me

gh issue list                                    # repo issues
gh issue list --label bug --state open
gh issue list --search "is:open label:bug sort:created-desc"

gh issue view 456
gh issue view 456 --web

gh issue edit 456 --add-label needs-triage
gh issue edit 456 --add-assignee @user
gh issue comment 456 --body-file comment.md

gh issue close 456
gh issue close 456 --duplicate-of 123
gh issue reopen 456
gh issue develop 456 --checkout                  # branch off the issue

CI / workflows / runs

gh workflow list
gh workflow run ci.yml --ref feature-branch
gh workflow run deploy.yml -f environment=production -f version=v1.2.3

gh run list                                      # all recent runs
gh run list --workflow=ci.yml --status=failure
gh run list --branch=main --limit 10

gh run view 789
gh run view 789 --log                            # full logs
gh run view 789 --log-failed                     # only failed jobs
gh run view 789 --web

gh run watch 789                                 # block until run completes
gh run rerun 789 --failed                        # re-run failed jobs only
gh run cancel 789

# Inspect a run programmatically
gh run view 789 --json status,conclusion,jobs \
  --jq '.jobs[] | select(.conclusion=="failure") | .name'

Releases

gh release create v1.0.0                         # interactive
gh release create v1.0.0 --notes-file NOTES.md
gh release create v1.0.0 --generate-notes        # auto-generate from PRs
gh release create v1.0.0 --draft
gh release create v1.0.0 dist/*.tar.gz           # upload assets at create time
gh release upload v1.0.0 dist/*.tar.gz           # add assets later

gh release list
gh release view v1.0.0
gh release download v1.0.0
gh release verify v1.0.0                         # supply-chain attestation

Repos & search

gh repo view                                     # current repo
gh repo view owner/repo --json description,stargazerCount,defaultBranchRef
gh repo clone owner/repo
gh repo fork owner/repo --remote
gh repo set-default                              # disambiguate origin

gh search repos "machine learning" --language=python --stars=">1000"
gh search code "TODO" --owner=myorg --language=rust
gh search issues "memory leak" --state=open
gh search prs "refactor" --created=">2024-01-01"

For label / codespace / gist / secret operations, see references/extras.md.

Auth

gh auth login                                    # interactive web login
gh auth login --clipboard                        # auto-copy OAuth code
gh auth status                                   # current identity
gh auth refresh -h github.com -s repo,workflow   # add scopes
gh auth setup-git                                # use gh as git credential helper

Common scopes: repo (private repo write), workflow (Actions), admin:org (org admin), write:packages (registry).

If a call returns HTTP 401, run gh auth refresh. If it returns HTTP 403 Resource not accessible by personal access token, scopes are missing — re-run gh auth refresh -s <scope>. For deeper diagnosis see references/troubleshooting.md.

What you don't do

Stage, commit, push, create PRs, rebase, or otherwise mutate the working tree — that's /plate's job
Code-quality review — use a dedicated review skill
Worktree creation — out of scope
Destructive operations. gh repo delete, gh release delete, gh secret delete, gh ssh-key delete, gh codespace delete, and similar irreversible commands stay outside this skill. Run them only with explicit user confirmation; never bake them into automation.

Gotchas

Compound cd <dir> && git ... can be blocked by a harness's bare-repo sandbox heuristic. Use git's -C <dir> flag instead, or run from the worktree root.
Heredoc --body with markdown headers trips the "# hides arguments" guard — always use --body-file.
gh api raw calls are flakier than the named subcommands and rarely needed. Prefer gh pr ..., gh issue ..., gh run ... over gh api whenever a subcommand exists; reach for gh api only for endpoints that have no subcommand wrapper.
Rate limits: gh api rate_limit shows current quota. Authenticated requests get 5000/hr, unauthenticated 60/hr.
Default repo ambiguity: when a clone has multiple remotes, run gh repo set-default once or pass --repo owner/name per call.

gh

About this skill