Agent skill

gh

Install and configure the GitHub CLI (gh) for AI agent environments where gh may not be pre-installed and git remotes use local proxies instead of github.com. Provides auto-install script with SHA256 verification and GITHUB_TOKEN auth with anonymous fallback. Use when gh command not found, shutil.which("gh") returns None, need GitHub API access (issues, PRs, releases, workflow runs), or repository operations fail with "failed to determine base repo" error. Documents required -R flag for all gh commands in proxy environments. Includes project management: GitHub Projects V2 (gh project), milestones (REST API), issue stories (lifecycle and templates), and label taxonomy management.

View SKILL.md on GitHub Repository
Stars 33
Forks 4

Install this agent skill to your Project

npx add-skill https://github.com/Jamie-BitFlight/claude_skills/tree/main/.claude/skills/gh

SKILL.md

GitHub CLI (gh) — Setup and Usage

Purpose

Ensures the GitHub CLI (gh) is available and provides correct usage patterns for AI agents operating in environments where gh may not be pre-installed and where git remotes point to local proxies instead of github.com.

When to Use

  • gh command not found or shutil.which("gh") returns None
  • Need to interact with GitHub API (issues, PRs, releases, workflows)
  • Repository remote does not point to github.com (proxy environments)
  • Need authenticated GitHub operations with GITHUB_TOKEN
  • Managing GitHub Issues, Projects V2, Milestones, or Labels

Installation

If gh is not installed, run the setup script:

bash
uv run .claude/skills/gh/scripts/setup_gh.py

The script:

  1. Checks if gh is already installed via shutil.which
  2. Detects platform (Linux, macOS, Windows) and architecture
  3. Fetches the latest release from https://github.com/cli/cli/releases/latest
  4. Downloads the correct archive with SHA256 verification from checksums file
  5. Extracts and installs the binary to a writable PATH directory
  6. Uses GITHUB_TOKEN for authenticated requests; falls back to anonymous if auth fails (401/403)

CLI options:

text
--force     Reinstall even if already at latest version
--dry-run   Show what would happen without installing
--bin-dir   Override install directory (default: auto-detect from PATH)

Authentication

GITHUB_TOKEN environment variable provides automatic authentication. No manual gh auth login needed.

bash
# Verify authentication
gh auth status

If GITHUB_TOKEN is set, gh authenticates automatically for all API calls.

Repository Detection

<repo_detection>

Git remote points to a local proxy (127.0.0.1), NOT github.com. Every gh command fails without explicit repo specification:

text
failed to determine base repo: none of the git remotes configured for this
repository point to a known GitHub host.

RULE: Pass -R (or --repo) on EVERY gh command:

bash
gh <command> -R Jamie-BitFlight/claude_skills

This applies to ALL gh subcommands: pr, issue, run, api, release, project, etc.

</repo_detection>

Common Commands (v2.87.0)

<gh_commands>

Pull Requests

bash
# List open PRs
gh pr list -R Jamie-BitFlight/claude_skills

# View PR details
gh pr view <number> -R Jamie-BitFlight/claude_skills

# Check PR CI status
gh pr checks <number> -R Jamie-BitFlight/claude_skills

# Create PR
gh pr create -R Jamie-BitFlight/claude_skills --title "title" --body "body"

# View PR comments
gh api repos/Jamie-BitFlight/claude_skills/pulls/<number>/comments

Issues

bash
# List issues
gh issue list -R Jamie-BitFlight/claude_skills

# List by label
gh issue list -R Jamie-BitFlight/claude_skills --label "priority:p1" --state open

# Create issue with labels and milestone
gh issue create -R Jamie-BitFlight/claude_skills \
  --title "feat: add feature X" \
  --label "priority:p1" --label "type:feature" \
  --milestone "v1.0"

# View issue
gh issue view <number> -R Jamie-BitFlight/claude_skills

# Close issue with comment
gh issue close <number> -R Jamie-BitFlight/claude_skills --comment "Implemented in PR #N"

# Edit labels on issue
gh issue edit <number> -R Jamie-BitFlight/claude_skills \
  --add-label "status:in-progress" \
  --remove-label "status:needs-grooming"

Labels

bash
# List all labels
gh label list -R Jamie-BitFlight/claude_skills

# Create label
gh label create "priority:p1" --color "E99695" \
  --description "High priority" -R Jamie-BitFlight/claude_skills

# Setup full label taxonomy (automation script)
uv run .claude/skills/gh/scripts/github_project_setup.py labels \
  --repo Jamie-BitFlight/claude_skills

See labels.md for the full taxonomy and color codes.

Projects V2

bash
# List projects
gh project list --owner Jamie-BitFlight

# Create project
gh project create --owner Jamie-BitFlight --title "claude_skills Backlog"

# Add issue to project
gh project item-add 1 --owner Jamie-BitFlight \
  --url https://github.com/Jamie-BitFlight/claude_skills/issues/42

# Full project setup (automation script)
uv run .claude/skills/gh/scripts/github_project_setup.py setup \
  --repo Jamie-BitFlight/claude_skills

See projects-v2.md for field creation and item editing commands.

Milestones

gh has no native milestone subcommand — use gh api with the REST endpoint:

bash
# List milestones
gh api repos/Jamie-BitFlight/claude_skills/milestones

# Create milestone
gh api repos/Jamie-BitFlight/claude_skills/milestones \
  -X POST -f title="v1.0" -f due_on="2026-03-31T00:00:00Z"

# Assign milestone to issue
gh api repos/Jamie-BitFlight/claude_skills/issues/42 \
  -X PATCH -F milestone=1

See milestones.md for full CRUD reference.

Workflow Runs

bash
# List recent runs
gh run list -R Jamie-BitFlight/claude_skills --limit 5

# View specific run
gh run view <run-id> -R Jamie-BitFlight/claude_skills

# View failed job logs
gh run view <run-id> -R Jamie-BitFlight/claude_skills --log-failed

Releases

bash
# List releases
gh release list -R Jamie-BitFlight/claude_skills

# View latest release
gh release view --repo <owner>/<repo>

API (Direct)

bash
# GET request
gh api repos/<owner>/<repo>

# POST with fields
gh api repos/<owner>/<repo>/issues -f title="Bug" -f body="Details"

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

# Paginated results
gh api repos/<owner>/<repo>/contributors --paginate

Repository

bash
# Clone
gh repo clone <owner>/<repo>

# View repo info
gh repo view -R <owner>/<repo>

</gh_commands>

Output Formatting

bash
# JSON output
gh pr list -R Jamie-BitFlight/claude_skills --json number,title,state

# JQ filtering
gh pr list -R Jamie-BitFlight/claude_skills --json number,title --jq '.[].title'

# Template formatting
gh pr list -R Jamie-BitFlight/claude_skills --json number,title \
  --template '{{range .}}#{{.number}} {{.title}}{{"\n"}}{{end}}'

Automation — Python Script

For multi-step operations (label setup, milestone creation, project init, issue import), use:

bash
# Full project setup
uv run .claude/skills/gh/scripts/github_project_setup.py setup

# Labels only
uv run .claude/skills/gh/scripts/github_project_setup.py labels

# Milestone management
uv run .claude/skills/gh/scripts/github_project_setup.py milestone list
uv run .claude/skills/gh/scripts/github_project_setup.py milestone create --title "v1.0" --due 2026-03-31

# Issue management
uv run .claude/skills/gh/scripts/github_project_setup.py issue list --priority p1
uv run .claude/skills/gh/scripts/github_project_setup.py issue create --title "feat: X" --priority-label priority:p1

The script delegates all GitHub operations to the authenticated gh CLI — no separate API tokens or Python HTTP clients needed.

Reference Files

  • labels.md — Label taxonomy (priority, type, status), color codes, bulk setup
  • milestones.md — Milestone CRUD via REST API, naming conventions
  • projects-v2.md — GitHub Projects V2 commands, custom fields, GraphQL queries
  • issue-stories.md — Issue as story format, body template, lifecycle, backlog item field mapping

Sources

Recommended Agent Skills

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

Jamie-BitFlight/claude_skills

ccc

This skill should be used when code search is needed (whether explicitly requested or as part of completing a task), when indexing the codebase after changes, or when the user asks about ccc, cocoindex-code, or the codebase index. Trigger phrases include 'search the codebase', 'find code related to', 'update the index', 'ccc', 'cocoindex-code'.

33 4
Explore
Jamie-BitFlight/claude_skills

agent-browser

Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.

33 4
Explore
Jamie-BitFlight/claude_skills

delegate

Quick delegation template for sub-agent prompts. Use when assigning work to a sub-agent, before invoking the Agent tool, or when preparing prompts for specialized agents. Provides the WHERE-WHAT-WHY framework. For comprehensive delegation guidance, activate the agent-orchestration how-to-delegate skill.

33 4
Explore
Jamie-BitFlight/claude_skills

swarm-spawning

Spawn agents and teammates in Claude Code swarms. Use when choosing between subagents vs teammates, selecting agent types (Explore, Plan, general-purpose, plugin agents), configuring spawn backends (in-process, tmux, iterm2), or setting environment variables for spawned agents.

33 4
Explore
Jamie-BitFlight/claude_skills

knowledge-explorer

Manage the research/ knowledge base (KB) of tool and library research entries. Use when browsing KB topics, adding new research entries, updating existing entries with dated revisions, fetching GitHub repo metadata into a draft KB entry, or migrating old-format entries to skill-spec frontmatter. Triggers on tasks like "what do we have on X", "add this to the KB", "update the KB entry for Y", "fetch github info for owner/repo", or "migrate old entries".

33 4
Explore
Jamie-BitFlight/claude_skills

design-anti-patterns

Enforce anti-AI UI design rules based on the Uncodixfy methodology. Use when generating HTML, CSS, React, Vue, Svelte, or any frontend UI code. Prevents "Codex UI" — the generic AI aesthetic of soft gradients, floating panels, oversized rounded corners, glassmorphism, hero sections in dashboards, and decorative copy. Applies constraints from Linear/Raycast/Stripe/GitHub design philosophy: functional, honest, human-designed interfaces. Triggers on: UI generation, dashboard building, frontend component creation, CSS styling, landing page design, or any task producing visual interface code.

33 4
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results