---
name: github-gh-skill
description: 使用 GitHub CLI（`gh`）处理认证、仓库、Issue、Pull Request、Actions、Release，以及通过 JSON/JQ 调用 API 查询数据。适用于用户提到 `gh`、GitHub CLI、终端里的 GitHub、PR、Issue、Actions、Release，或需要不打开浏览器直接获取 GitHub 数据的场景。
---

# GitHub CLI（gh）技能

## 何时启用

用户提到：`gh`、GitHub CLI、命令行操作 GitHub、PR/Issue/Release/Actions、或需要从终端拉取 GitHub 信息时，优先按本技能执行。

## 前置检查（一次性）

1. **检查 `gh` 是否已安装**：执行 `gh --version`。
   - 若命令不存在，**自动安装最新版**：根据系统包管理器执行安装（如 `apt install gh -y`、`yum install gh -y`、`brew install gh`）。
   - 安装失败再**提示用户手动安装**（参考官网 <https://cli.github.com/>）。
2. 若需私有资源，执行 `gh auth status`；未登录则 `gh auth login`（非 CI 场景由用户完成交互）。
3. 需要脚本化检测时，运行跨平台脚本：`python scripts/check_gh.py`（或 `python3 ...`，仅需 Python 3.8+ 与标准库）。

## 高效原则（给 Agent）

- **优先机器可读**：能用 `--json` 就用；需要筛选时用 `--jq`（避免解析人类表格输出）。
- **减少交互**：批量操作用 `--yes` / `-y`；需要合并且非交互时用环境变量或文档中的标志位（见 [reference.md](reference.md)）。
- **先定目标再选子命令**：issue / pr / repo / workflow / release / api —— 不要猜，缺参数时 `gh <cmd> --help`。
- **API 兜底**：`gh` 子命令缺能力时用 `gh api`，路径以官方 REST 为准。

## 模块索引（按场景跳转）

| 模块 | 内容 |
|------|------|
| A. 认证与上下文 | `gh auth`，默认仓库 |
| B. 仓库 | `gh repo clone/view/create` |
| C. Issue | `gh issue list/create/view/close` |
| D. PR | `gh pr list/create/view/diff/merge/checkout` |
| E. Actions | `gh run list/view/watch/rerun` |
| F. Release | `gh release list/create` |
| G. 高级 | `gh api`，GraphQL |

**详细命令与模板**见 [reference.md](reference.md)。

## A. 认证与上下文

- 查看登录：`gh auth status`
- 设置默认仓库（减少重复 `-R`）：在仓库目录内 `gh repo set-default`

## B. 仓库

- 克隆：`gh repo clone owner/name`
- 当前仓库信息（JSON）：`gh repo view --json name,owner,url,defaultBranchRef`

## C. Issue

- 列表（JSON）：`gh issue list --json number,title,state,author,labels`
- 创建：`gh issue create --title "..." --body "..."`

## D. Pull Request

- 列表：`gh pr list --json number,title,state,headRefName`
- 检出本地分支：`gh pr checkout <number>`
- 查看差异：`gh pr diff <number>`

## E. GitHub Actions（workflow / run）

- 运行列表：`gh run list --limit 20`
- 单次运行详情 + 日志：`gh run view <run-id> --log`

## F. Release 与标签

- 列表：`gh release list --limit 20`
- 创建（需明确 tag 与说明）：`gh release create <tag> --notes "..."`

## G. `gh api`（REST）

- GET 示例：`gh api repos/{owner}/{repo}/issues --jq '.[0].title'`
- 占位符：`{owner}` `{repo}` 在已关联 git remote 时常可自动解析；不确定时显式传 `-R owner/repo`。

## 错误处理

- **401/403**：检查 `gh auth status`、token 权限（repo、workflow 等）。
- **未找到命令**：升级 `gh` 或改用 `gh api`。
- **交互阻塞**：CI/自动化中避免会打开编辑器的命令；为 `pr merge` 等加 `--merge`/`--squash`/`--rebase` 等非交互选项。

## 附加资源

- 完整命令表与 JSON 字段提示：[reference.md](reference.md)
- 环境检查脚本（模块化，中文注释；跨平台，仅标准库）：[scripts/check_gh.py](scripts/check_gh.py)