Agent-Skills.md

Agent Skills: GitHub `gh` CLI

Standardize all GitHub interactions via the GitHub CLI (`gh`) instead of ad-hoc URLs, UI clicks, or direct REST API calls. Use when you need to read or change GitHub state (repos, issues, pull requests, reviews, check status, Actions workflows/runs, releases, labels, milestones, discussions, gists) and want deterministic output (prefer `--json` + `--jq`). Also use when the user provides a GitHub URL, including deep links like `https://github.com/OWNER/REPO/pull/123`, `.../issues/123`, `.../pull/123/files`, or comment permalinks like `#issuecomment-...`, and you need to fetch the underlying PR/issue/thread and reply. Fall back to `gh api` only when there is no first-class `gh NOUN VERB` command.

UncategorizedID: strantalis/agent-skills/gh-cli

Repository

strantalis/agent-skills
strantalis

Install this agent skill to your local

pnpm dlx add-skill https://github.com/strantalis/agent-skills/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
Standardize all GitHub interactions via the GitHub CLI (`gh`) instead of ad-hoc URLs, UI clicks, or direct REST API calls. Use when you need to read or change GitHub state (repos, issues, pull requests, reviews, check status, Actions workflows/runs, releases, labels, milestones, discussions, gists) and want deterministic output (prefer `--json` + `--jq`). Also use when the user provides a GitHub URL, including deep links like `https://github.com/OWNER/REPO/pull/123`, `.../issues/123`, `.../pull/123/files`, or comment permalinks like `#issuecomment-...`, and you need to fetch the underlying PR/issue/thread and reply. Fall back to `gh api` only when there is no first-class `gh NOUN VERB` command.

GitHub gh CLI

Overview

Use gh for GitHub operations with explicit repo targeting, JSON output, and command help-driven discovery of flags/fields. Avoid scraping human-readable output and avoid raw REST calls unless you must (use gh api as the controlled fallback).

Quick start

  1. Verify gh is installed and authenticated:
gh --version
gh auth status
  1. Set explicit repo context (preferred patterns):
# One-off: target a repo explicitly
gh issue list -R OWNER/REPO --json number,title,url -q '.[] | "\(.number)\t\(.title)\t\(.url)"'

# Repeated work: set a default repo for this shell + directory context
gh repo set-default OWNER/REPO

Operating rules (do not skip)

  1. Prefer first-class commands over APIs.

    • Use gh issue, gh pr, gh repo, gh run, gh workflow, gh release, etc.
    • Use gh api only when the CLI lacks a dedicated command (document the endpoint and why).

  2. Avoid guessing flags/fields; discover them.

    • Use gh <command> --help to find flags and supported --json fields.
    • Use gh help formatting for --json, --jq, and --template patterns.

  3. Prefer machine-readable output.

    • Use --json <fields> -q '<jq>' instead of parsing table output.
    • When you need just one value, return only that value (not the full blob).

  4. Make repo targeting explicit.

    • Prefer -R OWNER/REPO when not operating in a known local checkout.
    • If you infer repo from the current directory, confirm it via gh repo view --json nameWithOwner -q .nameWithOwner.

  5. Treat state changes as production-impacting.

    • Ask for confirmation before creating/closing/merging/deleting.
    • When modifying settings (branch protections, permissions), make changes small and reversible.

Common tasks (command-first)

Use skills/gh-cli/references/gh-commands.md for a categorized command reference with examples for:

  • Repos (view/clone/fork/create, defaults, settings)
  • Issues (list/view/create/edit/comment/close/reopen)
  • PRs (list/view/create/checkout/review/merge/status/checks, review threads/comments, reply workflows)
  • Actions (workflows/runs: list/view/watch/rerun/cancel)
  • Releases (list/view/create/download)
  • Search patterns and deterministic selection
  • gh api fallback patterns (REST + GraphQL) when required

Tooling

Run a quick environment/context capture when debugging auth/repo targeting problems:

./skills/gh-cli/scripts/gh_context.sh

This prints gh version/auth status and tries to identify the active repo (when run inside a checkout).

Fetch a PR’s review feedback (reviews + PR comments + inline review comments + review threads) as JSON:

./skills/gh-cli/scripts/pr_feedback.sh -R OWNER/REPO 123

Reply back to review feedback:

# Reply to an inline review comment (REST)
./skills/gh-cli/scripts/pr_review_comment_reply.sh -R OWNER/REPO 123 987654321 --body "Thanks — fixed in 8c0ffee."

# Reply to a review thread (GraphQL)
./skills/gh-cli/scripts/pr_review_thread_reply.sh PRRT_kwDO... --body "Good catch — updated to handle nil."