Agent skill

gh-cli

GitHub CLI (gh) command reference. Use when working with GitHub repositories, PRs, issues, actions, `gh api`, or any GitHub operations from the command line.

View SKILL.md on GitHub Repository
Stars 213
Forks 6

Install this agent skill to your Project

npx add-skill https://github.com/fredrikaverpil/dotfiles/tree/main/stow/shared/.claude/skills/gh-cli

SKILL.md

GitHub CLI Quick Reference

The gh CLI is GitHub's official command-line tool. This is a quick reference for common workflows—for comprehensive docs, see https://cli.github.com/manual

Getting Help

bash
gh --help                    # List all commands
gh <command> --help          # Help for specific command
gh auth status               # Check authentication

Discovery Patterns

bash
gh <command> --web           # Open in browser
gh <command> --json FIELDS   # JSON output for scripting
gh <command> <subcommand> -h # Quick help for any command
gh <command> list --limit N  # Limit results to avoid large output (default: 20-30)

Use tab completion to explore available commands and flags.

Important: Always use --limit when querying lists to avoid overwhelming output, especially with pr list, issue list, run list, etc.

Common Workflows

PR Workflow

bash
# Create PR
gh pr create --fill          # Use commit messages for title/body
gh pr create --web           # Open browser to create PR

# View and checkout
gh pr list                   # List PRs
gh pr view [NUMBER]          # View PR details
gh pr checkout NUMBER        # Checkout PR locally

# Review (simple, no line comments)
gh pr review NUMBER --approve
gh pr review NUMBER --comment -b "feedback"
gh pr review NUMBER --request-changes -b "needs work"

# Merge
gh pr merge --squash --delete-branch

Review Workflow

When reviewing a PR, follow this process:

  1. Inspect the PR diff and understand the changes
  2. Submit the review with line-level comments and an overall summary

Always ask the user whether to submit the review as "approve", "request changes", or "comment" (default to "comment").

Step 1: Inspect the PR

bash
# Find PRs needing your review
gh pr list --search "review-requested:@me"

# View PR details and diff
gh pr view NUMBER
gh pr diff NUMBER

Step 2: Submit the review with line-level comments

Use gh api to submit a review with inline comments and an overall summary in a single call. Set event to COMMENT, APPROVE, or REQUEST_CHANGES.

bash
gh api repos/{owner}/{repo}/pulls/NUMBER/reviews \
  --input - <<'EOF'
{
  "commit_id": "LATEST_COMMIT_SHA",
  "event": "COMMENT",
  "body": "Overall: solid changes with a few suggestions.",
  "comments": [
    {
      "path": "src/example.go",
      "line": 42,
      "side": "RIGHT",
      "body": "This variable is unused."
    },
    {
      "path": "src/example.go",
      "line": 55,
      "side": "RIGHT",
      "body": "Consider using a constant here:\n\n```suggestion\nconst maxRetries = 3\n```"
    }
  ]
}
EOF

Comment field reference:

Field Description
path Relative file path in the repo
line Line number in the file (for single-line comments)
side RIGHT (additions) or LEFT (deletions)
start_line Starting line (for multi-line comments)
start_side Starting side (for multi-line comments)
body Comment text (supports markdown and code suggestions)

Code suggestions use GitHub's suggestion syntax inside the body:

markdown
```suggestion
replacement code here
```

CI/CD Debugging

bash
# Check recent runs
gh run list --limit 5
gh run list --status failure

# View logs
gh run view RUN_ID --log-failed

# Rerun after fix
gh run rerun RUN_ID --failed

Issue Triage

bash
gh issue list
gh issue list --assignee @me
gh issue create --title "Title" --body "Description"
gh issue view NUMBER
gh issue comment NUMBER -b "Comment"
gh issue close NUMBER

Core Commands Quick Reference

Pull Requests

bash
gh pr list [--state open|closed|merged] [--author @me]
gh pr create [--draft] [--title "..."] [--body "..."]
gh pr view [NUMBER] [--web]
gh pr checkout NUMBER
gh pr diff [NUMBER]
gh pr merge [NUMBER] [--squash|--merge|--rebase]

Issues

bash
gh issue list [--assignee @me] [--label "bug"]
gh issue create [--title "..."] [--body "..."]
gh issue view NUMBER [--web]
gh issue close NUMBER

Workflows & Runs

bash
gh run list [--workflow "CI"] [--status failure]
gh run view RUN_ID [--log] [--log-failed]
gh run watch RUN_ID
gh workflow run WORKFLOW_FILE [--ref branch]

Repositories

bash
gh repo clone OWNER/REPO
gh repo view [--web]
gh repo fork OWNER/REPO
gh repo create NAME [--public|--private]

Power User Tips

JSON Output

bash
# Get structured data
gh pr list --json number,title,author

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

API Access

bash
# Direct API calls
gh api repos/OWNER/REPO
gh api repos/OWNER/REPO/pulls -f title="PR Title" -f head=branch -f base=main

# GraphQL
gh api graphql -f query='{ viewer { login } }'

Aliases

bash
gh alias set pv 'pr view'
gh alias set co 'pr checkout'
gh alias list

Environment Variables

  • GH_TOKEN: Authentication token
  • GH_REPO: Default repository (OWNER/REPO format)
  • GH_EDITOR: Preferred editor for interactive commands
  • GH_PAGER: Pager for output (e.g., less)

Finding Your Work

bash
gh pr list --author @me
gh issue list --assignee @me
gh search prs "author:username is:open"
gh search issues "assignee:username is:open"

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

fredrikaverpil/dotfiles

golangci-lint

When linting is failing.

213 6
Explore
fredrikaverpil/dotfiles

git-commit

This skill should be used BEFORE running any git commit command. Triggers when about to run `git commit`. Ensures commit messages follow Conventional Commits specification and prompts for Jira ticket number.

213 6
Explore
fredrikaverpil/dotfiles

neovim

213 6
Explore
fredrikaverpil/dotfiles

gh-pr

This skill should be used when creating a GitHub pull request via `gh pr create`. Defines PR body format with Why/What/Notes sections, ensures proper assignment, and prompts for Jira ticket number.

213 6
Explore
fredrikaverpil/dotfiles

git-commit

This skill should be used BEFORE running any git commit command. Triggers when about to run `git commit`. Ensures commit messages follow Conventional Commits specification.

213 6
Explore
fredrikaverpil/dotfiles

aip

Google API Improvement Proposals (AIP) reference. Use BEFORE designing or reviewing APIs, protobuf definitions, or any work involving Google API design standards. Fetches relevant AIP rules from https://google.aip.dev for the task at hand.

213 6
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results