Claude-skill-registry gh-cli-agentic

GitHub CLI commands optimized for AI agent workflows with JSON output and deterministic execution patterns.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/gh-cli-agentic" ~/.claude/skills/majiayu000-claude-skill-registry-gh-cli-agentic && rm -rf "$T"

manifest: skills/data/gh-cli-agentic/SKILL.md

GitHub CLI Agentic Patterns

Optimized

gh

commands for AI agent consumption using JSON output and structured field selection.

Core Principle

Always use

--json <fields>

for machine-readable output. The

--jq

filter is built-in (no jq installation required).

Pull Request Operations

Check Status

# Get all check statuses
gh pr checks $PR_NUMBER --json name,state,conclusion,detailsUrl

# Filter to failed only
gh pr checks $PR_NUMBER --json name,state,conclusion --jq '.[] | select(.conclusion == "FAILURE")'

Fields:

name

state

conclusion

detailsUrl

startedAt

completedAt

PR Details

# Essential PR info
gh pr view $PR_NUMBER --json number,title,state,mergeable,statusCheckRollup

# Full context
gh pr view $PR_NUMBER --json number,title,body,state,author,labels,assignees,reviewDecision,mergeable,statusCheckRollup

Key Fields:

Field Description

mergeable

MERGEABLE

CONFLICTING

UNKNOWN

reviewDecision

APPROVED

CHANGES_REQUESTED

REVIEW_REQUIRED

statusCheckRollup

Array of check statuses

List PRs

# Open PRs
gh pr list --json number,title,author,labels

# PRs by author
gh pr list --author @me --json number,title,state

# PRs needing review
gh pr list --search "review-requested:@me" --json number,title

Workflow Run Operations

Run Details

# Get run status with jobs
gh run view $RUN_ID --json conclusion,status,jobs,createdAt,updatedAt

# List recent runs
gh run list --json databaseId,status,conclusion,name,createdAt -L 10

Status Values:

queued

in_progress

completed

Conclusion Values:

success

failure

cancelled

skipped

neutral

Watch Run Until Completion

# Watch and wait for run to complete (blocking, no timeout needed)
gh run watch $RUN_ID --compact --exit-status

# Find and watch latest run
RUN_ID=$(gh run list -L 1 --json databaseId --jq '.[0].databaseId')
gh run watch $RUN_ID --compact --exit-status

See gh-workflow-monitoring skill for comprehensive workflow watching patterns.

Failed Logs

# Get only failed step logs (most useful for debugging)
gh run view $RUN_ID --log-failed

# Full logs (verbose)
gh run view $RUN_ID --log

Workflow Triggers

# Trigger workflow manually
gh workflow run $WORKFLOW_NAME

# Trigger with inputs
gh workflow run $WORKFLOW_NAME -f param1=value1 -f param2=value2

# List workflows
gh workflow list --json name,state,path

Issue Operations

Issue Details

# Full issue context
gh issue view $ISSUE_NUMBER --json number,title,body,state,labels,assignees,comments

# Minimal
gh issue view $ISSUE_NUMBER --json number,title,state,labels

List Issues

# Open issues
gh issue list --json number,title,labels,assignees

# By label
gh issue list --label "bug" --json number,title

# Assigned to me
gh issue list --assignee @me --json number,title,state

Repository Operations

# Get repo info
gh repo view --json nameWithOwner,defaultBranchRef,description

# Just owner/name
gh repo view --json nameWithOwner --jq '.nameWithOwner'

API Direct Access

For operations not covered by subcommands:

# Get specific data
gh api repos/{owner}/{repo}/actions/runs --jq '.workflow_runs[:5]'

# With pagination
gh api repos/{owner}/{repo}/issues --paginate --jq '.[].number'

Agentic Optimizations

Context	Command
CI diagnosis	`gh pr checks $N --json name,state,conclusion,detailsUrl`
Get failure logs	`gh run view $ID --log-failed`
PR merge status	`gh pr view $N --json mergeable,reviewDecision,statusCheckRollup`
Quick issue list	`gh issue list --json number,title,labels -L 10`
Workflow trigger	`gh workflow run $NAME`

Error Handling in Context

Always include fallback for context expressions:

- PR checks: !`gh pr checks $PR --json name,state,conclusion 2>/dev/null || echo "[]"`
- Run status: !`gh run view $ID --json status,conclusion 2>/dev/null || echo "{}"`

Field Reference

PR Fields

number

title

body

state

author

labels

assignees

reviewDecision

mergeable

statusCheckRollup

headRefName

baseRefName

isDraft

url

createdAt

updatedAt

Issue Fields

number

title

body

state

author

labels

assignees

comments

milestone

url

createdAt

updatedAt

closedAt

Run Fields

databaseId

name

status

conclusion

jobs

createdAt

updatedAt

url

headBranch

headSha

event

Job Fields (within runs)

name

status

conclusion

startedAt

completedAt

steps