Skip to main content
skill CX Codex

github-cli — Claude Code skill: what it does, how to install

github-cli equips AI coding assistants with gh CLI workflows for pull requests, issues, Actions runs, releases, and API calls.

MIT 128 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill github-cli -a claude-code
Open on GitHub

What github-cli does

This skill supplies the agent with battle-tested patterns for the official gh command-line tool. It guides the model through opening pull requests with --fill, monitoring and rerunning failed CI jobs, verifying build attestations, and drafting releases with auto-generated release notes.

It focuses on structured terminal usage: extracting fields using --json and --jq, scoping repository secrets, and picking GraphQL queries via gh api graphql when nested data calls for it. General Git actions like local commits and branch strategies are kept outside this bundle in a separate skill.

Without a valid session in gh auth status or a token exported via GITHUB_TOKEN, operations fail immediately. Missing token permissions cause silent errors, so commands often rely on expanded scopes refreshed via gh auth refresh -s.

What it helps with

  • open pull requests populated from commit histories
  • rerun failed GitHub Actions jobs using their run ID
  • configure auto-merge with squash after CI checks succeed
  • query GitHub GraphQL and REST endpoints from the CLI

Example prompts for the agent

  • Open a draft PR for this branch and populate the description from commits
  • Check failing CI checks for PR 45 and rerun the failed jobs
  • Tag and publish release v1.0.0 with generated release notes

How to install github-cli

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill github-cli -a claude-code

2Manually: put the files in place

~/.claude/skills/github-cli/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/github-cli/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about github-cli

How to install github-cli in Claude Code?

Run npx skills add oakoss/agent-skills --skill github-cli -a claude-code in your terminal. This saves the skill configuration to ~/.claude/skills/github-cli/SKILL.md.

What does the github-cli skill do?

It gives your AI coding assistant recipes and syntax rules to manage GitHub repositories, Actions workflows, pull requests, and projects using the gh tool.

Why do commands fail quietly when using GitHub CLI?

Missing OAuth scopes cause silent failures in the gh tool. Verify active scopes with gh auth status and add missing ones via gh auth refresh -s scope.

Source text

SKILL.md · MIT
---
name: github-cli
description: 'GitHub CLI workflows for repositories, issues, pull requests, actions, releases, projects, and API calls. Use when creating PRs, reviewing code, triaging issues, triggering workflows, publishing releases, managing projects, verifying attestations, or querying the GitHub API. Use for gh cli, github automation, code review, release management.'
license: MIT
metadata:
  author: oakoss
  version: '1.0'
user-invocable: false
---

# GitHub CLI Skill

Provides patterns for the `gh` CLI to interact with GitHub repositories, services, and APIs directly from the terminal. Covers authentication, repository management, issues, pull requests, actions, releases, projects, search, and the REST/GraphQL API. Git workflow patterns (branching, commits, CI/CD) are handled by a separate skill.

## Quick Reference

| Area          | Key Commands                                                          |
| ------------- | --------------------------------------------------------------------- |
| Auth          | `gh auth status`, `gh auth login`, `gh auth token`                    |
| Repos         | `gh repo clone`, `gh repo create`, `gh repo fork`, `gh repo sync`     |
| Browse        | `gh browse`, `gh browse --settings`, `gh browse file.ts:42`           |
| Issues        | `gh issue list`, `gh issue create`, `gh issue edit`, `gh issue close` |
| Pull Requests | `gh pr create`, `gh pr review`, `gh pr merge`, `gh pr checkout`       |
| Actions       | `gh run list`, `gh run view`, `gh workflow run`, `gh cache list`      |
| Releases      | `gh release create`, `gh release list`, `gh release verify`           |
| Projects      | `gh project list`, `gh project create`, `gh project item-add`         |
| Search        | `gh search repos`, `gh search issues`, `gh search code`               |
| API           | `gh api repos/{owner}/{repo}`, `gh api graphql`                       |
| Security      | `gh attestation verify`, `gh ruleset list`, `gh secret set`           |
| Status        | `gh status`, `gh pr checks`, `gh pr status`                           |
| Codespaces    | `gh codespace create`, `gh codespace ssh`, `gh codespace code`        |

## Common Workflows

| Workflow             | Commands                                                                                      |
| -------------------- | --------------------------------------------------------------------------------------------- |
| Quick PR             | `git push -u origin feat` then `gh pr create --fill`                                          |
| Draft PR             | `gh pr create --draft --fill` then `gh pr ready` when done                                    |
| Review and merge     | `gh pr checkout 45` then `gh pr review --approve` then `gh pr merge --squash --delete-branch` |
| Auto-merge PR        | `gh pr merge --auto --squash` (waits for required checks to pass)                             |
| Check CI             | `gh pr checks` then `gh run watch`                                                            |
| Rerun failed CI      | `gh run rerun <run-id> --failed`                                                              |
| Create release       | `gh release create v1.0.0 --generate-notes`                                                   |
| Search code          | `gh search code "handleAuth" --repo owner/repo`                                               |
| Add issue to project | `gh project item-add 1 --owner @me --url <issue-url>`                                         |
| Verify artifact      | `gh attestation verify artifact.tar.gz --owner owner`                                         |
| Trigger workflow     | `gh workflow run deploy.yml -f environment=production`                                        |
| Revert merged PR     | `gh pr revert 45`                                                                             |
| Sync fork            | `gh repo sync` to update fork from upstream                                                   |

## Output Formatting

Most `gh` list and view commands support structured output for scripting and automation.

| Flag         | Purpose                           |
| ------------ | --------------------------------- |
| `--json`     | Output specified fields as JSON   |
| `--jq`       | Filter JSON with jq expressions   |
| `-t`         | Format JSON with Go templates     |
| `--web`      | Open the resource in a browser    |
| `--comments` | Include comments (issues and PRs) |

## Scoping: Repo, Env, Org

Secrets and variables can be scoped to different levels.

| Scope        | Flag Example                                |
| ------------ | ------------------------------------------- |
| Repository   | `gh secret set KEY` (default)               |
| Environment  | `gh secret set KEY --env production`        |
| Organization | `gh secret set KEY --org name --visibility` |

Project commands always require `--owner @me` or `--owner org-name`.

## Authentication Prerequisites

The `gh` CLI requires authentication before most commands work. Run `gh auth status` to verify the current session. Missing scopes cause silent failures -- use `gh auth refresh -s scope` to add scopes without re-authenticating. For CI environments, set the `GITHUB_TOKEN` or `GH_TOKEN` environment variable instead of interactive login.

## Common Mistakes

| Mistake                                                         | Correct Pattern                                                          |
| --------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Running `gh pr create` without pushing the branch first         | Push with `git push -u origin branch` before creating a PR               |
| Using `gh pr merge` without checking CI status                  | Run `gh pr checks` first or use `gh pr merge --auto` to wait for checks  |
| Forgetting `--fill` when creating PRs from well-written commits | Use `gh pr create --fill` to auto-populate title and body from commits   |
| Using REST API when GraphQL is more efficient for nested data   | Use `gh api graphql` for queries needing related objects in one call     |
| Not authenticating with correct scopes                          | Run `gh auth status` to verify scopes, `gh auth refresh -s scope` to add |
| Using `gh project` commands without specifying `--owner`        | Always pass `--owner @me` or `--owner org-name` for project commands     |
| Manually downloading CI artifacts                               | Use `gh run download <run-id>` to download artifacts programmatically    |
| Not using `--json` for scripting                                | Add `--json field1,field2` and `--jq` for machine-readable output        |
| Merging without `--delete-branch`                               | Use `gh pr merge --squash --delete-branch` to clean up after merge       |
| Running `gh api` POST without `-f` fields                       | Use `-f key=value` for string fields, `-F` for typed fields              |

## Delegation

- **Search across repositories for code patterns or issues**: Use `Explore` agent with `gh search code` and `gh search issues`
- **Automate multi-step release workflows**: Use `Task` agent to coordinate branch creation, PR merge, and release publishing
- **Plan repository structure and access controls**: Use `Plan` agent to design team permissions, branch protection, and workflow architecture

## References

- [Repos & Auth](references/repos-auth.md) -- Authentication, repository management, configuration, extensions, aliases
- [Issues](references/issues.md) -- Issue CRUD, labels, assignments, pinning, transferring, development branches
- [Pull Requests](references/pull-requests.md) -- PR creation, review, merge, checkout, checks, diff, auto-merge
- [Actions](references/actions.md) -- Workflow runs, manual triggers, secrets, variables, caches, artifact downloads
- [Releases & Search](references/releases-search.md) -- Releases, attestation verification, search, gists, SSH/GPG keys
- [Projects & API](references/projects-api.md) -- Projects v2 management, REST API, GraphQL API, rulesets, status

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Git and GitHub →

From the same set106

The whole set →
knowledge-base-manager knowledge-base-manager is a Claude Code skill for choosing a document, graph, or hybrid knowledge-base design and planning its maintenance. It covers content curation, quality checks, and versioning. CX Codex +1 131installs secure-ai secure-ai — a skill that hardens the LLM layer of an app: injection defense, output validation, and zero-trust rules for agents that call tools. CX Codex +1 130installs python-uv python-uv teaches coding agents to manage Python projects with uv: initialization, dependencies, lockfiles, workspaces, and packaging. Useful when migrating from pip and poetry workflows. CX Codex +1 129installs rust This skill guides Rust work across ownership, async services, CLIs, terminal UIs, and testing. Use it when an agent needs Rust-specific patterns. CX Codex +1 128installs resend Guides AI agents in integrating the Resend email API, handling React Email templates, domain verification, and Svix webhooks. CX Codex +1 127installs tanstack-pacer Hands your agent a map of TanStack Pacer: debouncing, throttling, rate limits and async queues, with the matching React hooks. Useful when a handler fires too often. CX Codex +1 126installs tanstack-devtools tanstack-devtools guides AI coding agents in configuring Query cache, Router, and Form debugging panels across React applications. CX Codex +1 125installs seo-optimizer seo-optimizer — an SEO architecture skill: JSON-LD entities, E-E-A-T signals, topic clusters and a 30-point content audit. Runs in Claude, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. CX Codex +1 125installs

Project sponsors

Companies that keep this analytics open