home / skills / laurigates / claude-plugins / gh-cli-agentic

gh-cli-agentic skill

safe

This skill provides AI-friendly gh cli commands with JSON output and deterministic patterns to streamline code review, PR management, and workflow monitoring.

npx playbooks add skill laurigates/claude-plugins --skill gh-cli-agentic

Review the files below or copy the command above to add this skill to your agents.

Files (1)

skill.md

6.4 KB

---
model: haiku
name: gh-cli-agentic
description: GitHub CLI commands optimized for AI agent workflows with JSON output and deterministic execution patterns.
allowed-tools: Bash(gh pr *), Bash(gh run *), Bash(gh issue *), Bash(gh repo *), Bash(gh workflow *), Bash(gh api *), Read
created: 2025-01-16
modified: 2026-02-16
reviewed: 2026-02-16
---

# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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'
```

## GitHub URL Resolution

Translate GitHub URLs into `gh` API commands for programmatic access.

### URL → Command Mapping

| URL Pattern | Command |
|-------------|---------|
| `github.com/{owner}/{repo}/pull/{n}` | `gh pr view {n} --repo {owner}/{repo} --json number,title,body,state` |
| `github.com/{owner}/{repo}/issues/{n}` | `gh issue view {n} --repo {owner}/{repo} --json number,title,body,state` |
| `github.com/{owner}/{repo}/commit/{sha}` | `gh api repos/{owner}/{repo}/commits/{sha}` |
| `github.com/{owner}/{repo}/blob/{ref}/{path}` | `gh api repos/{owner}/{repo}/contents/{path}?ref={ref}` |

### File Contents by Ref

```bash
# Get decoded file content at a specific ref (branch, tag, or SHA)
gh api repos/{owner}/{repo}/contents/{path}?ref={ref} --jq '.content' | base64 -d

# Get raw file content directly (no JSON wrapper)
gh api repos/{owner}/{repo}/contents/{path}?ref={ref} -H "Accept: application/vnd.github.raw+json"
```

### Diff and Patch via API

Use Accept headers to get raw diff or patch output from PRs and commits:

```bash
# PR diff
gh api repos/{owner}/{repo}/pulls/{n} -H "Accept: application/vnd.github.diff"

# PR patch
gh api repos/{owner}/{repo}/pulls/{n} -H "Accept: application/vnd.github.patch"

# Commit diff
gh api repos/{owner}/{repo}/commits/{sha} -H "Accept: application/vnd.github.diff"

# Commit patch
gh api repos/{owner}/{repo}/commits/{sha} -H "Accept: application/vnd.github.patch"
```

## 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

Use `2>/dev/null` to suppress errors in context expressions (do NOT use `||` fallbacks - blocked by Claude Code 2.1.7+):

```markdown
- PR checks: !`gh pr checks $PR --json name,state,conclusion 2>/dev/null`
- Run status: !`gh run view $ID --json status,conclusion 2>/dev/null`
```

## 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`

Overview

This skill provides a collection of GitHub CLI (gh) command patterns optimized for AI agent workflows, producing deterministic JSON output for reliable parsing. It focuses on machine-readable fields, consistent status checks, and concise commands for PRs, workflows, issues, and repo access. Use these patterns when an agent must inspect, monitor, or act on GitHub resources programmatically.

How this skill works

Each command uses gh's --json output and built-in --jq filtering to return structured data suited for automated agents. The patterns include specific field selections (e.g., mergeable, statusCheckRollup, conclusion) and commands for viewing checks, watching runs, fetching logs, and resolving GitHub URLs to gh API calls. Error suppression (2>/dev/null) is recommended in context expressions to keep outputs clean for downstream parsing.

When to use it

When an agent needs deterministic, machine-readable GitHub data for decision making
To diagnose CI failures and collect failed-step logs programmatically
When listing or filtering PRs and issues for automated triage or review workflows
To trigger workflows or watch runs until completion from an agent loop
To fetch file contents, diffs, or raw patches for static analysis or patch application

Best practices

Always include --json with explicit fields to avoid unpredictable output
Prefer built-in --jq filters over installing external jq for portability
Select minimal fields necessary for the agent to reduce payload size
Use gh run watch with --compact and --exit-status for blocking completion checks
Suppress incidental errors with 2>/dev/null in context expressions; avoid || fallbacks

Example use cases

Agent collects failed CI checks: gh pr checks $PR --json name,state,conclusion,detailsUrl
Agent watches a workflow run and exits when done: gh run watch $RUN_ID --compact --exit-status
Agent fetches PR mergeability and review state for auto-merge decisions: gh pr view $N --json mergeable,reviewDecision,statusCheckRollup
Agent pulls decoded file contents at a ref for static analysis: gh api repos/{owner}/{repo}/contents/{path}?ref={ref} --jq '.content' | base64 -d
Agent triggers a workflow with inputs to run experiments: gh workflow run $WORKFLOW_NAME -f param1=value1

FAQ

Why use --json instead of plain text flags?

JSON provides predictable, machine-readable output that agents can parse reliably, avoiding brittle text parsing.

How do I get only failed workflow step logs?

Use gh run view $RUN_ID --log-failed to retrieve logs for failed steps without full verbose output.