smy-skills/github-gh-skill/SKILL.md

name, description

name	description
github-gh-skill	使用 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）。
• 先定目标再选子命令：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。

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
• 环境检查脚本（模块化，中文注释；跨平台，仅标准库）：scripts/check_gh.py