gh-cli - SKILL.md Agent Skill

name: gh-cli description: Use when working with GitHub via the gh CLI - managing PRs, issues, releases, repos, workflows, searching code, or calling the GitHub API. Triggers on tasks involving GitHub operations, PR creation/management, issue tracking, release workflows, or any gh command usage. license: MIT compatibility: Requires gh CLI installed and authenticated (gh auth login). metadata: author: farm version: "1.0"

GH CLI

Quick reference for the GitHub CLI (gh). Covers the most common operations in the farm repo workflow.

Overview

gh is GitHub's official CLI tool. It wraps the GitHub API and Git operations into composable commands. Most commands accept --json for structured output and --jq for filtering.

Prerequisites

gh auth status                          # verify authenticated
gh auth login                           # authenticate if needed

Common Operations

Pull Requests

Operation	Command
List PRs	`gh pr list --state open`
List PRs for current branch	`gh pr list --head "$(git branch --show-current)" --json number,title,state,url`
Create from current branch	`gh pr create --fill`
Create with explicit title/body	`gh pr create --title "feat: ..." --body "...description..."`
Create with body from file	`gh pr create --title "..." --body-file body.md`
View PR details	`gh pr view [number]`
View PR by branch	`gh pr view --head "$(git branch --show-current)"`
Check PR out locally	`gh pr checkout <number>`
View CI checks	`gh pr checks [number]`
Merge PR	`gh pr merge <number> --squash`
Close PR	`gh pr close <number>`
Comment on PR	`gh pr comment <number> --body "..."`
Request review	`gh pr edit <number> --add-assignee @me --add-reviewer @user`
Draft PR	`gh pr create --draft --title "..." --body "..."`

Issues

Operation	Command
List issues	`gh issue list --state open --limit 20`
Create issue	`gh issue create --title "..." --body "..."`
Create with type	`gh api repos/{owner}/{repo}/issues -X POST -f title=... -f body=... -f type="Bug"`
View issue	`gh issue view <number>`
Close issue	`gh issue close <number>`
Reopen issue	`gh issue reopen <number>`
Comment on issue	`gh issue comment <number> --body "..."`
Edit issue labels	`gh issue edit <number> --add-label "bug" --remove-label "wip"`

Note: gh issue create does not support --type. Use gh api for issue types (see API section below).

Repositories

Operation	Command
Clone a repo	`gh repo clone owner/repo`
Fork a repo	`gh repo fork owner/repo`
View repo info	`gh repo view --json nameWithOwner,description,defaultBranch`
List releases	`gh release list`
View release	`gh release view v1.0.0`
Create release	`gh release create v1.0.0 --title "..." --notes "..."`

Workflows & CI

Operation	Command
List workflows	`gh workflow list`
View workflow runs	`gh run list --workflow "CI" --limit 10`
Watch a run	`gh run watch <run-id>`
View run logs	`gh run view <run-id> --log`
Re-run failed	`gh run rerun <run-id> --failed`
Cancel a run	`gh run cancel <run-id>`
Download artifacts	`gh run download <run-id>`

Search

Operation	Command
Search issues	`gh search issues "query" --owner org --repo repo`
Search PRs	`gh search prs "query" --owner org --repo repo`
Search code	`gh search code "term" --owner org --repo repo`

API Access

Call arbitrary GitHub REST endpoints:

gh api repos/{owner}/{repo}/issues \
  -X POST \
  -f title="Title" \
  -f body="Body in markdown" \
  -f labels[]="bug" \
  --jq '{number, html_url}'

For GraphQL:

gh api graphql -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      issues(first: 5, states: OPEN) {
        nodes { number title }
      }
    }
  }
' -f owner=org -f repo=repo

Key flags for gh api:

-X METHOD — HTTP method (GET, POST, PATCH, DELETE)
-f key=value — form field (repeat for multiple values; use -f key[]=val for arrays)
-F key=@file — file upload
--jq '...' — filter JSON output with jq syntax
--paginate — follow pagination automatically
-H "Header: value" — custom headers

Typical Patterns in Farm

Create a PR for the current branch

git push -u origin "$(git branch --show-current)"
gh pr create --fill

If --fill fails, provide explicit title/body:

gh pr create --title "feat: description" --body "Closes #123"

Check if a branch already has a PR

gh pr list --head "$(git branch --show-current)" --json number,title,state,url

Returns empty [] if no PR exists.

View CI status for a PR

gh pr checks
# or for a specific PR
gh pr checks <number>

Merge a PR with squash

gh pr merge --squash --delete-branch

JSON Output and Filtering

Most gh commands support --json and --jq:

# Get PR number and URL
gh pr list --head "my-branch" --json number,url --jq '.[0] | {number, url}'

# Get specific field
gh pr view --json title --jq '.title'

# List PR numbers only
gh pr list --state open --json number --jq '.[].number'

Tips

Use --json + --jq instead of parsing text output
gh pr create --fill uses branch commits for title/body — works best with conventional commits
gh api is the escape hatch when built-in commands lack features (e.g., issue types)
For GitHub Actions secrets: gh secret set NAME --body "value" --repo owner/repo
GH_TOKEN env var or GH_HOST can target different GitHub instances
Run gh <command> --help for full flag documentation on any command