# Gh CLI

> Operate GitHub repositories, pull requests, issues, and releases via the `gh` CLI. Use when the user asks to push, create PR, manage issues, edit repo metadata, view repo, or any GitHub workflow operation, including Chinese requests such as “推送”“提 PR”“创建 issue”“改仓库描述”“查看仓库信息”.

- Skill: `morningstar0709/gh-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add morningstar0709/gh-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/morningstar0709/gh-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: MorningStar0709 (https://skillmd.com/u/morningstar0709)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/morningstar0709/gh-cli

---


# Gh CLI

Use `gh` CLI for GitHub operations.

## Use This Skill

- Push, commit, or any git remote operation needing GitHub interaction
- Create / list / view / close issues or pull requests
- Edit repository metadata (description, topics, homepage)
- Search across repos for issues, PRs, code, or users
- View repository details or authentication status
- "推送" / "提 PR" / "创建 issue" / "改仓库描述" / "查看仓库信息"

## Do Not Use

- Operations that do not involve GitHub (local git, other forges)
- Raw `git` operations that do not need GitHub API interaction
- Managing Agent Skills (use `gh skill` subcommand, not this skill)

## Input Contract

**Required Inputs:**
- A GitHub operation intent (create PR, list issues, edit repo, etc.)

**Optional Inputs:**
- Target repo (`owner/repo`) — if omitted, inferred from cwd's git remotes
- Issue or PR number
- Flags specific to the operation

**Missing input handling:**
- **No specific repo**: Use git remote from cwd. If no remote found, ask user.
- **No PR/issue number for view**: List recent items first, then ask which one.
- **Ambiguous intent**: Run `gh <command> --help` to clarify options.

## Execution Protocol

1. **Verify authentication**: `gh auth status`. If unauthenticated, report and stop.
2. **Choose the right command path**:
   - Typed commands (`gh pr`, `gh issue`, `gh repo`) for standard operations.
   - `gh search` for cross-repo queries.
   - `gh api` for anything typed commands do not expose.
3. **Use structured output**: Always prefer `--json` + `--jq` over parsing human-readable text.
4. **Handle pagination**: Pass `-L N` to control result count. For `totalCount`, use `gh api graphql`.
5. **Target repo**: Override with `--repo OWNER/REPO` (`-R`) when not operating on cwd's repo.
6. **Execute and validate**: Run the command. If it fails, interpret the error and retry with adjusted parameters.

### Core Patterns

#### Structured output

- `--json field1,field2,...` for structured JSON.
- Run with `--json` and **no field list** to see available fields first.
- `--jq '<expr>'` for filtering inline, no separate `jq` pipe.
- `--template '<go-template>'` for shaped text output.

#### Pagination

List commands cap results. Default is usually 30. Pass `-L N` (`--limit N`) to control count. `gh issue list` / `gh pr list` do not expose `totalCount` via `--json`. For a true total, use `gh api graphql`. For raw API pagination: `gh api --paginate <path>` + `--jq` + optionally `--slurp`.

#### Repo targeting

`gh` infers repo from cwd's git remotes. Override with `--repo OWNER/REPO` (`-R`).

#### Search vs list

- `gh search issues|prs|code|repos|commits|users` — cross-repo, full search syntax. Prefer for cross-repo or author/label filtering.
- `gh issue list --search "..."` / `gh pr list --search "..."` — same syntax but scoped to one repo.

#### Fall back to `gh api`

When typed commands don't expose the data you need. `{owner}/{repo}` placeholders auto-filled from repo remotes.

#### Interactivity

In non-TTY contexts `gh` already skips the pager, strips ANSI, and errors with clear messages instead of prompting.

When not sure about flags or available fields, run `gh <command> --help` before searching elsewhere.

### Common Operations

`gh repo edit <owner/repo>` — edit metadata. Flags: `--description`, `--homepage`, `--add-topic`, `--remove-topic`, `--default-branch`.
`gh repo view <owner/repo>` — view details.

`gh pr create` — create. Flags: `--title`, `--body`, `--draft`, `--base`.
`gh pr list` — list. Flags: `--state open/closed/merged`, `--author`, `--assignee`, `--draft`, `-L`.
`gh pr view <number>` — view details. `--comments` for issue-level comments.
`gh pr diff <number>` — read diff without switching branches.
`gh pr checkout <number>` — switch to PR branch locally.

`gh issue create` — create. Flags: `--title`, `--body`, `--label`, `--assignee`.
`gh issue list` — list. Flags: `--state`, `--label`, `--author`, `--assignee`, `-L`, `--search`.
`gh issue view <number>` — view details.
`gh issue close <number>` — close.
`gh issue reopen <number>` — reopen.

## Failure Handling

- **Not authenticated**: `gh auth status` fails. Report to user and ask them to run `gh auth login`.
- **404 / not found**: Repo or resource does not exist. Verify `owner/repo` spelling and user's access.
- **API rate limited**: Wait and retry, or inform user if limit is exceeded.
- **Command not found**: `gh` not installed. Ask user to install GitHub CLI.
- **Network error**: Report the exact error. Do not guess the output.
- **Ambiguous result from no field list**: Re-run with explicit fields.

## Output Contract

When using this skill, include in your response:
- What command was executed (or attempted)
- The structured result (key fields, not raw JSON dump)
- If failed, the exact error and suggested next step