github-cli-ops

github-cli-ops

概述

此技能可让 Agent 以 CLI 优先 的方式执行 任何 GitHub 操作：对于 gh CLI 能处理的所有操作，它都会使用 gh；这是一条更便捷的路径，还能加密机密并整理输出。只有在没有对应 gh 命令时，才会回退到 gh api（REST）；对于仅支持 GraphQL 的少数情况，则使用 gh api graphql。身份验证按 每次调用 进行：每次调用前都会加上 GH_TOKEN="$<token var>"，其值来自调用方注入的令牌，因此绝不会修改任何全局设置。gh 已负责管理基础 URL、分页和输出，所以 Agent 无需重新实现 HTTP 通信逻辑。对于 REST 的长尾操作，Agent 会通过 端点索引 + $ref 解析器，在随附的 OpenAPI 规范中查找端点，然后构建 gh api 调用。

何时启用

• ✅ 执行具有一流命令的 GitHub 操作——issues、pull requests、仓库、releases、labels、gists、Actions 运行/工作流、Projects、机密等（gh <command>）。
• ✅ 执行没有一流命令的 REST 操作——通过 gh api <endpoint> 构建调用。
• ✅ 处理仅支持 GraphQL 的需求（例如 Discussions）——使用 gh api graphql。
• ✅ 需要以编程方式在 github.com 上执行写入操作。

请勿在以下情况下启用：

• 任务是 本地/交互式 gh 操作——gh auth …、gh browse、gh repo clone、gh pr checkout、gh config、gh alias、gh extension、gh completion。这些是本地便捷功能，不是 API 操作；请直接使用 gh/git。
• 目标明确需要 GitHub Enterprise Server（此技能 v1 面向 github.com；Enterprise 主机可通过注入的 host 和 GH_HOST/GH_ENTERPRISE_TOKEN 路由，但尚未在此处测试）。
• 你只需要设置凭据——凭据由调用方提供；此技能不会创建或解析凭据（关于其使用的契约，请参阅 references/auth.md）。

工作流

步骤 1 — 接收注入的凭据

调用方已解析账户并注入此操作所需的内容——请直接 使用，不要 自行查找记录。从上下文中接收：

• host（以及该账户所依据的 权限能力）——作为上下文值提供，不从文件读取。
• 令牌，按有序加载规则获取：上下文会提供变量的 名称。按以下规则解析该名称：如果项目级 .env 文件存在 且定义了该变量，则使用其中的值；否则，使用同名的 环境变量——优先尝试项目 .env，因此项目 .env 可以覆盖全局环境变量。令牌 值 不会出现在上下文文本中——示例中只会出现变量名（$<token_env>）；只有 gh 子进程会读取该值。项目根目录由上下文提供；请勿执行 任何 范围解析或目录遍历来查找 .env。这里指的是项目 .env，不是 .envrc。

执行实际操作前，确认令牌有效：GH_TOKEN="$<token_env>" gh api user --jq .login。切勿使用 gh auth switch/gh auth login 来选择账户——它们会修改 gh 的全局活动账户（该账户在用户的 shell 之间共享）；身份验证通过 GH_TOKEN 按 每次调用 进行。完整契约和环境变量桥接说明：references/auth.md。

步骤 2 — 选择 CLI 还是 API

扫描 assets/cli-index.md（每个命令占一行），查找与操作匹配的 gh 命令。**决策规则：**只要存在 gh 命令，就优先使用；仅在缺少命令时使用 gh api；仅支持 GraphQL 的需求则使用 gh api graphql。注意：许多领域 没有 对应命令（teams、checks、packages、code-scanning/-security、dependabot、git 数据、reactions、apps、migrations 等）——对于这些领域，跳过扫描，直接使用 gh api（列表见 references/gh-api.md）。

步骤 3a — CLI 路径（首选）

从实时的 gh <cmd> --help 中读取命令的确切标志（始终与已安装的 gh 版本保持同步）。使用每次调用专用的令牌运行：

GH_TOKEN="$<token_env>" gh issue create --repo OWNER/REPO --title "…" --body "…"
GH_TOKEN="$<token_env>" gh repo view OWNER/REPO --json name,visibility,defaultBranchRef --jq '.defaultBranchRef.name'
GH_TOKEN="$<token_env>" gh secret set MYSECRET --repo OWNER/REPO --body "$VALUE"   # gh encrypts client-side

使用 --json <fields> [--jq <expr>] 获取机器可读的输出。参见 references/cli-reference.md。

步骤 3b — API 备用方案

如果没有对应命令：在 assets/endpoint-index.md 中查找相应操作，使用 python3 scripts/endpoint.py <operationId> 解析其结构（解析 $ref 后的参数／请求体／响应 + 框架），然后构造：

GH_TOKEN="$<token_env>" gh api repos/{owner}/{repo}/traffic/views --jq '.count'
GH_TOKEN="$<token_env>" gh api -X PATCH repos/{owner}/{repo} -f description='…'
GH_TOKEN="$<token_env>" gh api graphql -f query='{ viewer { login } }'

{owner}／{repo}／{branch} 占位符会从当前仓库或 GH_REPO 填充。标志 + 分页 + GraphQL 详情：references/gh-api.md。

步骤 4 — 处理响应

• 输出：--jq／--json（CLI）或 --jq／--template（gh api）。
• 分页（gh api）：--paginate 会自动跟随 Link 标头；--slurp 会将所有页面包装为一个数组。GraphQL 分页需要在查询中包含 $endCursor + pageInfo{hasNextPage,endCursor}。
• 错误：非零退出码／HTTP 4xx 就是 API 的答复——最常见的原因是令牌范围问题。生成具有所需范围的令牌（参见 references/auth.md）；这不是技能错误。

规则

硬性规则（绝不违反）：

• 仅使用每次调用专用的 GH_TOKEN。 每次调用都使用 GH_TOKEN="$<token_env>" gh … 进行身份验证。绝不使用 gh auth switch／gh auth login（它们会修改全局状态）。对于非默认主机，使用 GH_HOST／GH_ENTERPRISE_TOKEN。
• 绝不读取或打印令牌值。 只能通过 $<token_env> 引用；gh 子进程会从环境中读取它。令牌仅保存在 .env 中（已加入 gitignore）。
• CLI 优先。 如果存在对应的 gh 命令，优先使用该命令；gh api 用于补足缺口，gh api graphql 用于仅支持 GraphQL 的操作。对于 gh 原生支持的操作，不要手动构造 gh api 调用。
• 构造 gh api 调用前先解析。 根据经过 $ref 解析的架构（步骤 3b）构建参数／请求体，而不是凭猜测或记忆确定字段集合。
• 通过 gh secret set 处理密钥。 它会在客户端加密；绝不要自行编写 libsodium 代码，也不要自行 PUT 原始密钥值。
• 此技能绝不写入凭据。 凭据由调用方提供；此技能绝不配置或解析凭据。

偏好（可覆盖）：

• 仅请求所需字段（命令使用 --json <fields>；使用 --jq／-q 进行筛选），以减少输出。
• 优先使用一等命令的结构化输出（--json），而不是解析人类可读文本。
• 对于大型 gh api 集合，使用 --paginate（需要合并成单个数组时使用 --slurp）。

注意事项

• gh auth switch 会影响全局。 它会更改所有 shell 的活动账号，而不只是本次调用——这正是此技能要避免的问题。请始终为每次调用单独传递 GH_TOKEN。
• gh api 中的 -f 与 -F。 -f／--raw-field 会发送字符串；-F／--field 会进行智能类型转换（true／false／null／整数会转换为 JSON 类型，@file 会读取文件，{owner} 占位符会被填充）。将 -f 用于布尔值／整数会发送字面字符串，导致 API 拒绝请求。
• 添加字段会将方法切换为 POST。 任何 -f／-F 都会自动将 gh api 从 GET 切换为 POST；要使用带查询参数的 GET，请使用 -X GET（否则参数会放入查询字符串）。
• 是令牌范围问题，不是错误。 对有效调用返回 4xx，通常是缺少令牌范围（例如 repo、delete_repo、read:org）。说明问题并生成具有适当范围的令牌；不要盲目重试。
• 占位符需要仓库上下文。 {owner}／{repo} 只能从当前 git 仓库或 GH_REPO 填充；如果不在仓库中，请传入完整路径（repos/OWNER/REPO/…）。
• 设置了 GH_TOKEN 时运行 gh auth status 会报告环境令牌并禁用 login／switch——这是预期行为，表示每次调用的身份验证已生效。

反模式

• 用 gh auth switch 选择账户。 绝对不要这样做——它会修改全局状态。这里只能通过每次调用时设置 GH_TOKEN 来选择账户。
• 回显令牌。 绝不要执行 echo $TOKEN，绝不要把令牌粘贴到会打印出来的命令中，也绝不要将其值写入任何文件。只能引用环境变量。
• 用 gh api 做 gh 原生支持的操作。 如果有 gh issue create，就不要手动构造 gh api repos/{owner}/{repo}/issues -f title=…——这样会失去易用性和验证功能。
• 手动处理密钥加密。 不要获取公钥后自行使用 libsodium 加密；gh secret set 会完成此操作。
• 猜测 gh api 请求体。 解析 schema（步骤 3b）；不同端点的字段要求各不相同。
• 加载整个规范。 不要将数 MB 的 OpenAPI JSON 用 cat 加载到上下文中——先扫描索引，再解析单个操作。

输出

此技能会产生 GitHub 副作用（执行所请求的操作），并将解析后的结果返回给调用 Agent。它不会自行写入文件（只会 使用 调用方注入的凭据）。对于写入操作，它会报告已创建或更新的资源（编号、URL、ID）；对于读取操作，它会按需分页并返回结果集。抽象消费者是需要执行该操作的调用 Agent（或子 Agent）；令牌绝不会进入该输出。

相关内容

• references/auth.md — 此技能使用的凭据约定（调用方注入的主机 + 按顺序加载令牌的规则）、每次调用时设置的 GH_TOKEN、验证探测，以及妥善处理密钥。
• CLI 优先、gh api 备用的模式（包含打包的 OpenAPI 规范）可推广到其他提供官方 CLI 的服务商。

渐进式披露

大量内容存放在子文件夹中，仅在需要时加载：

• references/auth.md — 此技能使用的凭据约定：调用方注入的主机、按顺序加载令牌的规则、每次调用时设置的 GH_TOKEN、验证探测，以及示例脚本的环境变量桥接。在步骤 1 加载。
• references/cli-reference.md — CLI 优先模式的详细说明：决策规则、--json/--jq 输出、gh secret set（客户端加密）、使用 cli-index.md 和实时 gh --help。在步骤 2–3a 加载。
• references/gh-api.md — 备用方案：gh api 标志（-X、-f/-F、-H、--paginate、--slurp、--jq、--input、--hostname）、索引与解析工作流、GraphQL、错误和作用域。在步骤 3b 加载。
• references/sources.md — 来源信息（gh 手册和打包的规范版本）。

在扩充阶段（Phase 2.C）新增，见上文：

• assets/cli-index.md — 每条 gh 命令各占一行，用于发现（步骤 2）。
• assets/github-openapi.json — 打包的 GitHub REST OpenAPI 规范（权威来源；通过查询使用，绝不整体加载）。
• assets/endpoint-index.md — 每个 REST 操作各占一行，用于发现（步骤 3b）。
• scripts/endpoint.py + scripts/endpoint.py.validation.md — python3 $ref 解析器（步骤 3b）。
• scripts/<example>.sh + .validation.md — 已验证的 gh/gh api 调用示例。

独立使用（可选，非必需）

这是为在 Agent 流程之外手动运行此技能的人类提供的便利方式，并非此技能的依赖项。此技能的规范约定是由调用方注入（步骤 1）；本附录仅提供手动操作的桥接方式。

如需手动运行，请自行根据 .service-accounts.yaml 记录及其 .env 令牌设置 GH_TOKEN（以及可选的 GH_HOST / GH_REPO），然后运行脚本。示例记录：

accounts:
  - name: github-personal
    provider: github
    host: github.com
    token_env: GH_PERSONAL_TOKEN     # the var holding the token value; value lives in .env (gitignored)

set -a; source .env; set +a                 # loads $GH_PERSONAL_TOKEN, never prints it
export GH_TOKEN="$GH_PERSONAL_TOKEN"
export GH_REPO="OWNER/REPO"                  # optional: fills {owner}/{repo}
bash scripts/create-issue.sh "My title" "My body"

只按名称引用该值，绝不打印；每次调用时设置 GH_TOKEN 的规则仍然适用（不要使用 gh auth switch）。

正文篇幅限制

• description ≤ 1,024 个字符（agentskills.io 上限）。
• 正文 ≤ 约 500 行 / 5,000 个令牌——每轮都会保留在上下文中；详细内容放在 references/ 中。
• assets/github-openapi.json 文件较大（在磁盘上查询，绝不加载到上下文中）。