Agent skill

mastering-github-cli

GitHub CLI (gh) command reference for repository search, code discovery, CI/CD monitoring, workflow authoring, and automation. Triggers on "gh" commands, "github cli", searching repos for files/directories (.skilz, .cursor, .codex, Dockerfile), monitoring GitHub Actions workflows, checking PR CI status, downloading artifacts, creating PRs/issues/repos from command line, triggering workflows, forking repos, batch operations, "write a workflow", "github actions", "CI/CD pipeline", "workflow yaml", and "matrix builds". Use for gh search, gh run, gh pr, gh issue, gh repo, gh workflow, gh api, workflow authoring, and automating GitHub operations.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/devops/mastering-github-cli-spillwavesolutions-mastering-github-age

SKILL.md

Mastering GitHub CLI

Command-line interface for GitHub operations: search, monitoring, resource creation, workflow authoring, and automation.

Contents

Quick Start

Find repos with specific files/directories

bash
gh search code "path:.skilz" --json repository --jq '.[].repository.fullName'
gh search code --filename SKILL.md
gh search code --filename Dockerfile --language python

Monitor CI/CD

bash
gh run list --workflow=CI --status=failure --limit 10
gh run watch 12345 --exit-status      # Block until complete
gh run view 12345 --log-failed        # Failed logs only
gh pr checks 123 --watch              # PR CI status

Create resources

bash
gh pr create --title "Feature" --body "Description" --reviewer @user
gh issue create --title "Bug" --label bug,urgent --assignee @me
gh repo fork owner/repo --clone

Trigger and monitor workflow

bash
gh workflow run deploy.yml -f environment=staging
sleep 5
RUN_ID=$(gh run list --workflow=deploy.yml --limit 1 --json databaseId --jq '.[0].databaseId')
gh run watch "$RUN_ID" --exit-status

Command Reference

Task Command Reference
Find repos with file gh search code --filename FILE search.md
Find repos with directory gh search code "path:DIR" search.md
List failed runs gh run list --status=failure monitoring.md
Watch run gh run watch ID --exit-status monitoring.md
Download artifacts gh run download ID -n NAME monitoring.md
Create PR gh pr create --fill resources.md
Check PR CI gh pr checks --watch monitoring.md
Trigger workflow gh workflow run NAME.yml automation.md
Fork repo gh repo fork REPO --clone resources.md
REST/GraphQL API gh api repos/{owner}/{repo} api.md

JSON Output

bash
gh pr list --json                              # Discover fields
gh pr list --json number,title,author,labels   # Select fields
gh run list --json status --jq '.[] | select(.status=="completed")'

Environment & Auth

Variable Purpose
GH_TOKEN Authentication token
GH_REPO Default owner/repo
GH_HOST GitHub Enterprise host
GH_PROMPT_DISABLED=1 Disable prompts (CI)

Rate Limits

Endpoint Limit Notes
REST API 5,000/hour Per authenticated user
Search API 30/minute All search endpoints
Code Search 10/minute More restrictive
Search results 1,000 max Use date partitioning for more

Workflow Authoring

GitHub Actions workflow YAML patterns for CI/CD pipelines.

Basic Structure

yaml
name: CI Pipeline
on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: make build
      - run: make test

Caching Patterns

yaml
# Python/Poetry
- uses: actions/setup-python@v5
  with:
    python-version: '3.11'
- uses: actions/cache@v4
  with:
    path: .venv
    key: venv-${{ runner.os }}-${{ hashFiles('poetry.lock') }}

# Node.js
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'

Matrix Builds

yaml
strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [18, 20]
  fail-fast: false

OIDC Authentication (AWS/GCP)

yaml
permissions:
  id-token: write
  contents: read

steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
      aws-region: us-east-1

Full reference: references/workflow-authoring.md

Advanced Patterns

For enterprise CI/CD pipelines:

  • Ephemeral PR Environments - Auto-create/destroy per PR
  • Release Please - Automated semantic versioning
  • PR Cleanup - Resource cleanup on close
  • Testing Patterns - pytest, Gradle, Jest with coverage
  • Deployment Status Checks - Wait for stack readiness
  • Separate Build/Deploy Roles - Fine-grained OIDC permissions
  • Multi-Stack Ordering - Foundation → Schemas → Application

Additional References:

  • Workflow Summaries - Rich markdown output with $GITHUB_STEP_SUMMARY
  • Container Security - Multi-stage builds, Trivy scanning, image tagging
  • Security Scanning - CodeQL, Dependabot, IaC scanning (Checkov, tfsec)
  • Troubleshooting - Debug mode, flaky tests, common issues
  • Performance - Limits, runner specs, optimization tips

Scripts

Pre-built automation scripts with error handling and rate limit awareness.

Script Purpose Usage
find-repos-with-path.sh Find repos containing specific paths ./scripts/find-repos-with-path.sh .skilz [owner]
wait-for-run.sh Block until workflow completes ./scripts/wait-for-run.sh RUN_ID [timeout]
batch-search.sh Search >1000 results via date partitioning ./scripts/batch-search.sh "query" START END

Exit Codes

Script 0 1 2 3
wait-for-run.sh success failure cancelled timeout
find-repos-with-path.sh success error - -
batch-search.sh success error - -

Validation Checklist

Before completing a GitHub CLI task, verify:

- [ ] gh authenticated (`gh auth status`)
- [ ] Command syntax matches documentation
- [ ] Exit codes checked and handled appropriately
- [ ] Rate limits considered (code search: 10/min, repo search: 30/min)
- [ ] JSON output parsed correctly (if using --json)
- [ ] Artifacts downloaded to correct directory (if applicable)
- [ ] PR/Issue created with proper labels and assignees (if applicable)
- [ ] Workflow triggered and monitored to completion (if applicable)

When Not to Use

This skill covers gh CLI and GitHub Actions workflow authoring. Do not use for:

  • Git commands: git push, git commit, git pull (use git directly)
  • GitHub web UI: Questions about github.com interface navigation
  • GitHub Desktop: Different application entirely
  • Direct curl/HTTP: API calls without gh wrapper
  • GitHub mobile app: Mobile-specific features

Didn't find tool you were looking for?

Be as detailed as possible for better results