GitHub CLI (gh)

Overview

GitHub CLI (

gh

) is the official command-line tool for GitHub that brings pull requests, issues, releases, and other GitHub concepts to the terminal. This skill provides comprehensive guidance for using

gh

to streamline GitHub workflows, including PR management, issue tracking, repository operations, and API access.

When to Use This Skill

Invoke this skill when users:

Mention GitHub CLI (

gh

) commands or workflows

Ask about creating, viewing, or managing pull requests from the command line

Need help with GitHub issue management via CLI

Want to understand gh's mental model or command structure

Request guidance on GitHub automation or scripting

Ask about GitHub API access through gh

Need help with gh authentication or configuration

Request integration patterns between gh, git, and other tools (like erk)

Core Concepts

Before providing guidance, understand these key concepts:

Three-Layer Architecture:

High-Level Commands

(porcelain):

gh pr

,

gh issue

,

gh repo

- user-friendly workflows

API Access

:

gh api

- direct REST/GraphQL access with built-in auth

Git Integration

Smart repo detection from git remotes and current branch

Context Resolution:

gh

automatically detects repository from git remotes

Uses current branch to infer PR context

Falls back to interactive selection when ambiguous

Mental Model:

Think of

gh

as "GitHub workflows made CLI-native" - each command maps to a common GitHub workflow optimized for terminal use.

Using the Reference Documentation

When providing gh guidance, load the comprehensive reference documentation:

references/gh.md

This reference contains:

Complete mental model and terminology

Full command reference for PRs, issues, repos, releases, and more

Authentication and configuration patterns

Workflow patterns for common scenarios

Integration details (erk, git, CI/CD)

GitHub API access patterns

Practical examples for daily development

Loading Strategy:

Always load

references/gh.md

when user asks gh-related questions

The reference is comprehensive (~1480 lines) but optimized for progressive reading

Use grep patterns to find specific sections when needed:

gh pr

- Pull request commands

gh issue

- Issue management commands

gh repo

- Repository operations

gh api

- API access patterns

Pattern [0-9]:

- Workflow patterns

Authentication

- Auth setup

erk Integration

- Integration with erk

Common Operations

When users ask for help with gh, guide them using these patterns:

First-Time Setup

Check if gh is installed:

gh --version

Authenticate:

gh auth login

(interactive) or

gh auth status

(check current)

Configure defaults:

gh config set

Test connection:

gh repo view

(in a git repo)

Pull Request Operations

Load

references/gh.md

and search for "gh pr" section to provide:

Creating PRs:

gh pr create

(interactive or with flags)

Viewing PRs:

gh pr view

,

gh pr list

Checking out PRs:

gh pr checkout

Reviewing PRs:

gh pr review

,

gh pr diff

Merging PRs:

gh pr merge

PR status checks:

gh pr checks

Issue Management

Load

references/gh.md

and search for "gh issue" section to provide:

Creating issues:

gh issue create

Listing issues:

gh issue list

(with filters)

Viewing issues:

gh issue view

Updating issues:

gh issue edit

,

gh issue close

Issue assignment and labels

Repository Operations

Load

references/gh.md

and search for "gh repo" section to provide:

Viewing repos:

gh repo view

Cloning repos:

gh repo clone

Creating repos:

gh repo create

Forking repos:

gh repo fork

Repository settings and visibility

API Access

Load

references/gh.md

and search for "gh api" section to provide:

REST API calls:

gh api

GraphQL queries:

gh api graphql -f query='...'

Pagination handling

JSON processing with

--jq

Authentication details

For advanced GraphQL use cases

, load

references/graphql.md

:

Projects V2 management (no REST API exists)

Discussion API operations

Batch queries across multiple repos

Complex nested data retrieval

Advanced issue search

See

GraphQL API Reference

section below

Release Management

Load

references/gh.md

and search for "gh release" section to provide:

Creating releases:

gh release create

Listing releases:

gh release list

Downloading assets:

gh release download

Uploading assets:

gh release upload

Workflow Guidance

When users describe their workflow needs, map them to patterns in the reference:

Pattern 1: Daily PR Workflow

- Create, review, merge PRs

Pattern 2: Issue Triage

- List, filter, and manage issues

Pattern 3: Release Automation

- Script release creation and asset management

Pattern 4: PR Checks and Status

- Monitor CI/CD and review status

Pattern 5: Multi-Repo Operations

- Work across multiple repositories

Pattern 6: GitHub API Scripting

- Automate complex GitHub workflows

Pattern 7: Code Review Workflow

- Review PRs from command line

Load the appropriate pattern sections from

references/gh.md

based on user needs.

Output Formatting

When users need to parse or format gh output:

Load the Output Formatting section from

references/gh.md

Explain format options:

--json

,

--jq

,

--template

Show JSON field selection:

gh pr list --json number,title,state

Demonstrate jq filtering:

gh api /repos/{owner}/{repo}/pulls | jq '.[] | select(.draft==false)'

Provide template examples for custom output

Authentication and Configuration

When users need auth or config help:

Load the Authentication & Configuration section from

references/gh.md

Distinguish between:

Authentication:

gh auth login

, token management

Configuration:

gh config set

, per-command defaults

Explain authentication methods: browser, token, SSH

Show common config settings:

git_protocol

,

editor

,

pager

Handle multiple accounts and enterprise instances

Integration Guidance

Erk Integration

When users mention erk or worktree workflows:

Load the Erk Integration section from

references/gh.md

Explain how gh detects repos in worktrees

Show PR operations across multiple worktrees

Guide on using

--repo

flag when needed

Reference erk documentation for worktree-specific patterns

Git Integration

When users need to understand gh + git workflows:

Load the Git Integration section from

references/gh.md

Explain repo detection from git remotes

Show how current branch affects PR commands

Demonstrate combined git + gh workflows

Clarify when to use git vs gh commands

CI/CD Integration

When users want to integrate gh with CI/CD:

Load the CI/CD patterns from

references/gh.md

Show authentication in CI environments:

GH_TOKEN

Provide examples of automated PR creation/merging

Demonstrate status check monitoring

Guide on release automation

Scripting and Automation

When users want to script GitHub workflows:

Load the Scripting section from

references/gh.md

Show how to use

gh

in shell scripts

Demonstrate error handling:

--jq

, exit codes

Explain pagination for large datasets

Provide examples of common automation patterns:

Bulk operations across PRs/issues

Custom notifications

Release workflows

Repository management

Advanced Features

When users need advanced capabilities:

Aliases

Custom commands via

gh alias set

Extensions

Third-party gh extensions

GraphQL

Complex queries beyond REST API (see

GraphQL API Reference

)

Webhooks

Trigger workflows (via API)

GitHub Actions

Interact with workflows via

gh workflow

Load the relevant sections from

references/gh.md

for each advanced feature.

GraphQL API Reference

When standard

gh

commands are insufficient, use GraphQL via

gh api graphql

. Load

references/graphql.md

for comprehensive GraphQL guidance.

When to Use GraphQL:

Use GraphQL when the porcelain commands (

gh pr

,

gh issue

, etc.) cannot accomplish the task:

Projects V2

No REST API exists - all operations require GraphQL

Create/update projects

Add items and update field values

Query custom fields and project data

Discussions

No porcelain commands available

Create/manage discussions

Add comments and replies

Query discussion categories

Batch Operations

Query multiple resources in one API call

Compare multiple repositories

Aggregate data across repos

Reduce rate limit consumption

Complex Queries

Fetch nested data efficiently

PR with reviews, comments, and status checks in one call

Issue with timeline, reactions, and linked PRs

Repository with open issues, PRs, and contributors

Advanced Search

Complex filtering beyond basic commands

Multi-criteria issue/PR searches

Boolean logic and date ranges

Advanced sorting options

Custom Fields

Precise field selection

Request only needed fields

Optimize for performance

Build custom data aggregations

GraphQL Resources:

references/graphql.md

- Complete GraphQL guide including:

Use cases requiring GraphQL

Common patterns (variables, pagination, batching, etc.)

Complete examples (Projects V2, Discussions, batch queries)

Best practices and troubleshooting

references/graphql-schema-core.md

- Core schema types (load only when needed):

Detailed field information for Repository, Issue, PullRequest, etc.

Projects V2 field types and mutations

Discussion types and operations

Input types and enums

Loading Strategy:

Start with

references/graphql.md

for use cases and patterns

Load

references/graphql-schema-core.md

only when detailed schema info is needed

Use grep patterns to find specific sections:

Projects V2

- Project automation examples

Discussion

- Discussion API examples

Batch

- Batch query patterns

Pagination

- Cursor-based pagination

Example [0-9]

- Complete working examples

Rate Limits and API Backend

When users encounter rate limit issues or need to optimize API usage:

Load

references/api-backend-audit.md

for complete command-to-API mapping

Understand the difference:

REST

5,000 requests/hour, counted per request

GraphQL

5,000 points/hour, cost based on query complexity

Search

30 requests/minute (separate limit) Key insights: PR/Issue commands use GraphQL (query cost varies) Run/Workflow/Gist commands use REST (predictable cost) Project commands require GraphQL exclusively Search always uses REST with stricter limits Check current limits: gh api rate_limit --jq '.resources' Troubleshooting When users encounter issues: Check authentication: gh auth status Verify repository detection: gh repo view Test API access: gh api user Review configuration: gh config list Check rate limits: gh api rate_limit Enable debug mode: GH_DEBUG=api gh Load the Troubleshooting section from references/gh.md for specific error patterns. Command Discovery When users ask "what can gh do?": Start with overview of main commands: pr , issue , repo , release , workflow Show command help: gh --help Demonstrate interactive mode: most commands work interactively Point to gh api for anything not covered by porcelain commands Reference the full command reference in references/gh.md Resources references/ gh.md - Comprehensive GitHub CLI mental model and command reference (~1480 lines) Load for all standard gh command guidance Full workflow patterns and examples Integration patterns (erk, git, CI/CD) graphql.md - GitHub GraphQL API comprehensive guide (~1000 lines) Load when porcelain commands are insufficient Use cases requiring GraphQL (Projects V2, Discussions, batch queries) Complete patterns and examples Best practices and troubleshooting graphql-schema-core.md - Core GraphQL schema types (~500 lines) Load only when detailed schema info needed Detailed field definitions for core types Mutation input types and examples api-backend-audit.md - REST vs GraphQL API backend audit (~850 lines) Load when understanding which API type a command uses Rate limit guidance and optimization strategies Complete mapping of all gh commands to their API backends Batch operation alternatives and caching strategies These references should be loaded as needed to ensure accurate, detailed information. Use progressive disclosure: start with the main reference, then load specialized GraphQL docs when needed.