前言¶
在仓库里做协作动作——看 PR 状态、查一遍检查、提 issue、发评论——如果每一步都让人去翻网页，上下文很快被 HTML 占满。用 gh CLI 直接走 GitHub API 更省，但命令多、参数杂，网关环境下的认证目录、异步合并的状态机这些细节也容易踩坑。
下面介绍的这个 Skill，就是把这类操作整理成一份可执行的参考工作流，覆盖认证、PR、异步合并、议题、CI 排查和 gh api 查询。
这是什么¶
一句话定位：基于 gh CLI 操作 GitHub 的命令参考工作流。
- 名称：GitHub 命令行仓库协作
- 坐标：
@clawhub_steipete/github（SkillHub 页面显示名称为 Github） - 版本：1.0.0
- 来源：clawhub，上游仓库 https://clawhub.ai/steipete/github
- 发布者：steipete（Peter Steinberger）
- 许可：MIT-0
- 分类：dev-programming
- SkillHub 页面数据：评分 100000，下载 463371 次，安装 35756 次
解决什么问题：让 Agent 在用户要求查看或创建 issue、PR、CI/检查日志、评论、评审、release、仓库查询，或执行任何 gh api 操作时，有一份明确的命令与状态处理约定可循。
认证：先确认 gh 登录状态¶
Skill 给出的第一步是认证，而不是直接发命令。
gh auth status
gh auth login
第一条用来确认当前环境是否已登录、登录的是哪个 host 和 account；第二条在未登录时完成交互式登录。
一个容易踩的坑：网关服务跑在容器里时，HOME 可能和宿主机不同，gh 读不到宿主机上已缓存的 token，表现就是「明明登录过却提示未认证」。Skill 的处理方式是在网关环境里显式指定配置目录并重启服务：
export GH_CONFIG_DIR=/path/to/gh-config
设置后需要重启网关服务，gh 才会在新的目录里读写认证信息。
PR 全操作¶
Skill 覆盖 PR 的 list / view / checks / diff / create 五类操作。
gh pr list --repo owner/repo
gh pr view 55 --repo owner/repo
gh pr checks 55 --repo owner/repo
gh pr diff 55 --repo owner/repo
gh pr create --repo owner/repo --title "..." --body "..."
不在 git 目录里时要显式带 --repo owner/repo。Skill 同时说明 PR 的 URL 可以直接使用，不必先解析成数字。
创建 PR 时还有一个针对网关环境的约定：按 Runtime 供给的 sessionUrl，在 PR 正文里恰当地追加会话页脚。也就是说正文不要写成固定模板，要把当前会话的链接按约定位置放进去。
异步合并：完整协议¶
合并不是一条命令就结束的。Skill 描述的是通过 gh api 走异步合并 API 的完整协议，要点如下。
gh api repos/owner/repo/pulls/55/merge \
-H "X-Octopool-Require: ..." \
-f commit_id=<head-sha>
X-Octopool-Require这个守护头必须紧跟api子命令，位置写错会被忽略。- 提交的
head SHA必须是已经评审过的那个 SHA，不能换成本地最新的。
响应处理：接口返回 202 不代表失败，要把响应里的 details.uuid 保留下来，用它轮询状态。
gh api repos/owner/repo/octopool/merge/<uuid> --jq '.status'
需要处理的状态有四种：pending、merged、enqueued、failed。merge_action 字段与合并队列的实际行为相关，要根据它判断当前这一步是排队中还是已提交。
一条硬规则：绝不未经授权启用 bypass_rules。跳过分支保护规则需要显式授权，Skill 明确禁止在没有授权的情况下使用该参数。
landing ownership：跟进到 MERGED 才算完¶
Skill 里有一个原则叫 landing ownership：合并动作发出后，负责的人或 Agent 要持续跟进，直到 gh pr view 证实 state 为 MERGED。
gh pr view 55 --repo owner/repo --json state --jq '.state'
在确认 MERGED 之前，评审意见、冲突、失败的检查都属于延续工作，不是「已经合并了」就可以收尾。
议题管理¶
gh issue list --repo owner/repo
gh issue view 12 --repo owner/repo
gh issue create --repo owner/repo --title "..." --body "..."
gh issue comment 12 --repo owner/repo --body "..."
gh issue close 12 --repo owner/repo
覆盖 list / view / create / comment / close。
CI 运行排查¶
gh run list --repo owner/repo --limit 10
gh run view <run-id> --repo owner/repo
gh run view <run-id> --repo owner/repo --log-failed
gh run rerun --failed --repo owner/repo
--log-failed 只输出失败步骤的日志，排查时比整份日志省上下文。gh run rerun --failed 只重跑失败的步骤。
gh api 与结构化查询¶
gh api 用于访问其他子命令没有覆盖的数据。
gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
多数命令支持 --json 做结构化输出，再叠 --jq 过滤。
两个实用约定：
- 正文里含反引号、环境变量展开或用户自己写的文本时，用
--body-file从文件读，避免 shell 转义把内容改掉。
gh pr create --repo owner/repo --body-file /tmp/pr-body.md
--cache可以缓存 API 响应，减少重复请求。
安装与启用¶
上游 ClawHub 页面给出的安装命令：
openclaw skills install @steipete/github
Skill 页面同时提供 CLI 与 Prompt 两种使用方式。SkillHub 上的镜像地址是 https://api.skillhub.cn/org-b6kzcl68/github，对应页面 https://www.skillhub.cn/skills/clawhub_steipete/github。
标签里有 requires_api_key=true，意味着使用前需要有可用的 GitHub 认证：要么 gh auth login 完成，要么网关环境配好 GH_CONFIG_DIR。
适用场景与注意¶
触发时机（Skill 自述）：用户要求查看或创建 issue、PR、CI/检查日志、评论、评审、release、仓库查询，或任何 gh api 操作。对应关键词包括 GitHub CLI、gh命令、PR管理、issue管理、CI日志、异步合并、release发布、gh api。
注意：
- 运行环境必须能执行
ghCLI，且认证可用。 - 网关/容器环境下先处理
GH_CONFIG_DIR，否则认证会「看起来像登录过但不可用」。 - 异步合并要按协议轮询
details.uuid，不能只看202就当成功。 - 未经授权不要启用
bypass_rules。 - Skill 简介里另提到：如需编程开发的完整工作流套件，可在淘宝搜索「AI灵匣」店铺获取完整版。这条属于 Skill 自带的导流说明，是否采用由使用者自己判断。
结尾¶
这个 Skill 的价值在于，把 gh CLI 的高频仓库操作和容易出错的状态处理（认证目录、异步合并轮询、landing ownership）写成了明确约定，让 Agent 执行时有据可依，而不是每次现查命令。
官方地址：
- SkillHub：https://api.skillhub.cn/org-b6kzcl68/github
- 上游仓库：https://clawhub.ai/steipete/github
