GitHub CLI 有 Skill 吗？从安装到使用 Agent Skills 的完整指南

近期在研究各种 CLI 工具的 "Skill" 机制时发现，GitHub CLI（gh）不仅有官方内置的 gh skill 命令，还在 2025 年初随着 v2.67.0 版本正式开启了 Agent Skills 时代。本文整理从查阅资料、安装到上手验证的全流程，以及和飞书 CLI 的对比。

一、gh 确实有 Skill：从 v2.67.0 起

GitHub CLI 内置了一组 gh skill 子命令，专门用来给 AI 编程助手（Claude Code、GitHub Copilot、Cursor 等）安装"技能包"——也就是如何正确调用 gh 的说明书。

最常用的三条命令：

# 安装官方 gh 技能（用户级别）
gh skill install cli/cli gh --scope user

# 更新技能
gh skill update gh

# 查看已安装的所有技能
gh skill list

仓库引用格式是 OWNER/REPO，不能只写 cli。cli/cli 里的 cli 是 GitHub CLI 仓库的 owner，第二个 cli 是仓库名。

安装时的常用变体：

场景	命令
安装官方 gh 技能（用户级）	gh skill install cli/cli gh --scope user
安装到项目级（默认）	gh skill install cli/cli gh
强制覆盖已有技能	gh skill install cli/cli gh -f
从本地目录安装	gh skill install ./my-skill --from-local
安装所有技能（不逐个确认）	gh skill install cli/cli --all

二、安装时的交互选择

第一次执行 gh skill install 后，会进入一个全屏选择器，询问要把技能安装到哪个 AI Agent 上：

• 方向键：移动光标
• 空格键：选中/取消选中
• 右键：全选
• 左键：全部取消
• 回车：确认

根据自己用的编辑器选一个或多个即可：

用的 AI 工具	建议选择
VS Code 里的 GitHub Copilot	保持默认选中 GitHub Copilot，直接回车
Claude Code（命令行版 Claude）	空格选中 Claude Code，再回车
Cursor 编辑器	空格选中 Cursor，再回车
不确定	保持默认 GitHub Copilot，直接回车

安装器屏幕上会出现一段安全提示：技能未经过 GitHub 验证，可能包含提示注入、隐藏指令或恶意脚本。使用前请务必审查技能内容。 这是官方模板的标准提示，cli/cli 仓库是可信的，但养成"装完先看一眼内容"的习惯总没错。

三、技能装好之后，AI 能帮你做什么

技能包本质上是一份 Markdown "使用说明书"，告诉 AI 如何正确调用 gh。装好后，AI 会参考它自动拼出正确的命令。

想做的事	可以这样问 AI
看仓库的 Issue	"帮我看看这个仓库有哪些开放的 Issue"
创建一个 PR	"帮我创建一个 PR，标题是 xxx，内容是 xxx"
看 PR 状态	"我有哪些待审核的 PR？"
搜索特定 Issue	"搜索 repo:cli/cli 里标签是 bug 的 Issue"
读文件内容	"帮我看一下 README.md 的内容"

典型产出长这样：

gh issue list --limit 5 --json number,title,state,createdAt

不必再去背零散的命令，直接用人话提问就行。

四、技能文档里的几个关键点

官方技能包（SKILL.md，目前随 v2.96.0 release 发布）的核心要点：

1. 结构化输出优先

人类可读的列格式难以被程序解析，永远先考虑 --json：

# 查看全部可用字段
gh issue list --limit 1 --json

# 指定字段
gh issue list --json number,title,state,createdAt

# 直接按 jq 过滤
gh issue list --json number,title --jq '.[] | select(.title | contains("bug"))'

注意 --template/-T 在 gh pr create -T、gh issue create -T 上会和 body-template 撞名，用前先 --help 看一眼。

2. 分页必须显式指定

列表命令默认只返回 30 条，且 不暴露 totalCount（没有"全部共 N 条"这种字段）。需要总数就得退回 GraphQL：

gh api graphql -f query='
  query { repository(owner: "cli", name: "cli") {
    issues(first: 0) { totalCount }
  } }'

需要下一页用 --paginate：

gh api --paginate repos/cli/cli/issues

3. Repo 定位别含糊

gh 默认从当前目录的 git remote 推断仓库。要明确指定：

gh issue list --repo cli/cli
# 简写
gh issue list -R cli/cli

4. Search vs List 的语义差异

场景	用什么
跨仓库搜索、按 author/label 过滤	gh search issues|prs|code|repos|commits|users
当前仓库内的列表	gh issue list / gh pr list

搜索语法里多个 qualifier 要分多个 token 写：

# ✅ 正确
gh search issues repo:cli/cli is:open author:monalisa

# ❌ 错误，会被当成一个关键字解析
gh search issues "repo:cli/cli is:open"

bot 作者（如 dependabot）要写 --app dependabot，--author dependabot 会找不到。

5. Issue 高级关系（子 Issue、阻塞）

gh issue 新版本支持类型化与层级化：

# 创建时指定类型、父 issue、阻塞关系
gh issue create --type Bug --parent 23 --blocked-by 24,25

# 编辑多个 issue 的关系
gh issue edit 23 34 \
  --add-sub-issue 100,101 \
  --add-blocked-by 200

# 查看结构化字段
gh issue view 23 --json issueType,parent,subIssues,blockedBy,blocking

返回的 subIssues、blockedBy、blocking 形状是 {"nodes": [...], "totalCount": N},nodes 会被截断（subIssues 100 条，blockedBy/blocking 各 50 条）。要判断是否被截，看 nodes.length 是否等于 totalCount。

GHES 自托管版本：Issue 类型/子 Issue 需要 3.17+，阻塞关系需要 3.19+。

6. 看不下去就用 gh api

一些 --json 没暴露的字段，直接打 REST/GraphQL：

# PR 的 review thread 评论（gh pr view --comments 不显示这种）
gh api repos/cli/cli/pulls/1234/comments

# 任意 GraphQL
gh api graphql -f query='...' -F var=value

{owner}/{repo} 占位符只在 git remote 推断得到时才会被替换，要确定性的话显式写。

7. 认证状态

gh auth status         # 人类可读
gh auth status --json  # 结构化

五、和飞书 CLI 的"技能"对比

维度	飞书 CLI	GitHub CLI (gh skill)
官方支持	飞书办公场景专属（消息/文档/日历）	通用 GitHub 操作（Issues/PRs/Discussions）
命令规模	200+ 命令，19 个官方 Agent Skills	内置 gh 子命令 + 1 套 gh 技能包
第三方协议	飞书自研	MCP（mcp-gh 等社区实现把 gh 包装成 MCP 工具）
AI 适配	官方优先	官方 + 社区双轨

两者本质理念一致——让 AI 能直接操作系统，而不是让人来回搬运粘贴。在 AI 编程工具上，先试内置的 gh skill install cli/cli gh --scope user，通常是最快的路径。

六、一个验证脚本

装完跑一下，看有没有装上：

gh skill list

然后让 AI 帮你执行一条命令，验证它确实在用技能文档：

帮我用 gh 查看当前仓库最近的 5 个 Issue。

正常会得到类似 gh issue list --limit 5 --json number,title,state,createdAt 这种带 --json 的结构化命令，而不是 gh issue list | head -5 这种纯文本管道——后者说明 AI 还没读懂技能文档。

小结

• gh skill 是 GitHub CLI v2.67.0+ 的官方 Agent Skills 管理子命令，本质是一份 Markdown "使用说明书"装给 AI 看。
• 安装格式是 gh skill install OWNER/REPO SKILL_NAME（cli/cli gh），用 --scope user 装到用户级。
• 装好后，AI 在调用 gh 时会自动参考技能文档，用 --json、-L N 等"AI 友好"的方式拿到数据。
• 看不下去 --json 没覆盖的字段，直接 gh api 或者 gh api graphql。
• GitHub CLI 和飞书 CLI 是同一思路（给 AI 直接操作系统）的两种生态实现，先试官方的 gh skill install 通常最省事。