community skill
GitHub CLI gh
GitHub CLI 官方仓库中的 gh 使用模式 skill，指导 agent 在非交互环境中调用 gh，处理 JSON 输出、分页、仓库定位、搜索与 gh api 回退。
communityskill packagegithubclighapiautomation
GitHub CLI gh
GitHub CLI gh 是 GitHub 官方 cli/cli 仓库中的 Agent Skill，记录 agent 在自动化环境中调用 gh 的可靠模式。它覆盖非交互执行、结构化 JSON 输出、分页限制、仓库定位、搜索语法，以及 typed command 无法暴露字段时如何回退到 gh api。
来源
- 上游 skill 目录：https://github.com/cli/cli/tree/trunk/skills/gh
- 上游 SKILL.md：https://github.com/cli/cli/blob/trunk/skills/gh/SKILL.md
- 上游仓库：https://github.com/cli/cli
- GitHub CLI 文档：https://cli.github.com/manual/
- 许可证：MIT
适合什么时候用
- 需要让 agent 读取或筛选 GitHub issue、PR、代码搜索、仓库、提交、用户等数据。
- 需要输出稳定可解析的 JSON，而不是依赖
gh的人类可读表格输出。 - 需要处理
gh issue list、gh pr list、gh search ...等命令的默认数量限制。 - 当前工作目录无法可靠推断仓库，必须用
--repo OWNER/REPO固定目标。 - typed command 没有提供所需字段，需要改用
gh api、REST 或 GraphQL。
核心规则
| 场景 | 推荐做法 | 原因 |
|---|---|---|
| 结构化读取 | gh ... --json field1,field2 --jq '<expr>' | 避免解析表格文本 |
| 探索字段 | 先运行带 --json 但不列字段的命令 | 获取该命令支持的字段集合 |
| 列表数量 | -L N 或 --limit N | 避免默认只返回约 30 条 |
| 固定仓库 | --repo OWNER/REPO 或 -R OWNER/REPO | 避免依赖 cwd git remote 推断 |
| 跨仓库查询 | gh search issues "is:open repo:owner/name ..." | 使用 GitHub 搜索语法 |
| API 回退 | gh api repos/{owner}/{repo}/... 或 gh api graphql ... | 获取 typed command 未暴露的数据 |
安装提示
这是 GitHub 官方仓库中的单个 skill 目录。本站只收录索引和中文说明，不镜像上游文件。可通过上游目录安装：
npx skills add https://github.com/cli/cli/tree/trunk/skills/gh
使用该 skill 前，本机或执行环境需要可用的 GitHub CLI：
gh --version
gh auth status
使用注意
gh在非 TTY 环境中会自动跳过 pager、去掉 ANSI 颜色，并在需要交互输入时快速报错；不需要额外设置不存在的--no-pager。gh pr create -T、gh issue create -T等少数命令中，-T可能不是模板输出参数，使用前应查看--help。gh issue list和gh pr list的 JSON 输出不包含真实总数；需要总数时应使用 GraphQL 的totalCount。- PR review thread comments 不等同于 issue-level comments；需要 review comments 时应调用
gh api repos/{owner}/{repo}/pulls/{n}/comments。 gh pr checkout <n>会切换分支；只读场景优先用gh pr diff <n>或gh pr view <n>。