Community写作与编辑github.com

MichaelYochpaz/agent-skills

精心制作、高效Token的Agent技能,实现可靠的Agent工作流程。

agent-skills 是什么?

这是一个为AI Agent(如Claude Code、Cursor、Codex)设计的工程化技能包,专注于提升与GitHub CLI(`gh`)交互时的可靠性和token效率。它通过结构化的指南和命令模板,帮助Agent在多种平台上(包括支持`gh`的任何环境)高效地执行仓库管理、Issue/PR操作、搜索和代码审查等任务。该技能特别强调了读写操作的区分,在执行创建、编辑、合并等修改GitHub状态的操作前需要用户确认,并提供了丰富的`--json`和`--jq`字段指南以及安全性考虑。其核心价值在于将GitHub CLI的常见操作封装成Agent易于理解和执行的模式,减少不必要的token消耗,并确保操作的正确性和安全性。

兼容平台~Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add MichaelYochpaz/agent-skills

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

GitHub CLI (gh)

通过命令行与GitHub交互:仓库、Release、Issue、PR、讨论、搜索、代码审查和Actions。

已在 gh 2.95.0 版本上验证。

Agent 指南

  • 对于已知的远程文件或目录,使用 gh repo read-file / gh repo read-dir(在 gh 2.95 中为预览功能)。对于较旧的 gh 版本或仅需 API 的情况,请使用 API 模式 中的内容 API 回退方案。
  • 当任务需要在文件间搜索或探索不熟悉的代码且路径未知时,克隆到临时目录(gh repo clone owner/repo <temp-dir> -- --depth 1)并使用本地文件读取和搜索工具。
  • 对于读取/查看操作,优先使用默认文本输出而非 --json——这更节省token。仅在需要以编程方式提取特定字段时,才使用带 --jq 的 --json。要发现支持的字段,先运行不带字段列表的 --json 命令,然后只请求你需要的字段。
  • 查看日志或差异时,在获取完整内容前先限定输出范围(例如 --name-only、--log-failed)。
  • 在已克隆的仓库内运行时,无需使用 --repo 标志——默认使用当前目录的仓库。对于 gh api,使用显式路径(repos/OWNER/REPO/...)或设置 GH_REPO 环境变量。
  • 将此技能用于已覆盖的工作流。当缺少某个需要的标志或字段、命令因未知/已更改的标志失败,或命令标记为预览时,请检查特定命令的帮助(例如 gh pr diff --help)。

安全性

  • 写操作(create、edit、comment、review、close、merge、delete、rerun、run cancel、workflow run/enable/disable、讨论变更)会修改 GitHub 状态。执行前请先与用户确认,尤其是在你并非所有者的仓库上。
  • gh api 配合 --method POST/PUT/PATCH/DELETE 会发送写请求。请仔细检查端点和载荷。默认方法为 GET(安全);添加 -f/-F 参数会将默认方法切换为 POST。
  • 破坏性操作(delete、close、merge --admin)可能是不可逆的。需要明确的用户确认。

前提条件

在运行命令前,验证 gh 已安装并认证:

gh --version
gh auth status

如果未认证,请引导用户通过 gh auth login 完成认证。

公共标志

这些标志在许多命令组中都可用,但支持情况因命令而异:

  • --repo OWNER/REPO —— 指定不同的仓库(默认:当前目录的仓库)。也接受完整 URL。
  • --json FIELDS —— 以 JSON 格式输出,包含指定字段。不传值可列出可用字段。
  • --jq EXPRESSION —— 使用 jq 语法过滤 JSON 输出。需要配合 --json。
  • --template STRING —— 使用 Go 模板格式化 JSON 输出(--jq 的替代方案)。
  • --web —— 在浏览器中打开资源,而非在终端中显示。
  • --limit N —— 列表命令的最大结果数(默认通常为 30)。

仓库

查看

显示仓库的描述、README、星标数、语言分布及其他元数据。

gh repo view owner/repo
gh repo view owner/repo --json name,description,defaultBranchRef,languages,stargazerCount

克隆

在本地克隆仓库。自动配置远程仓库,对于 fork 还会设置上游远程仓库。

gh repo clone owner/repo [target-directory]

读取远程仓库内容

对于已知文件或目录的快速读取,使用仓库读取命令(在 gh 2.95 中为预览功能):

# 已知文件
gh repo read-file src/main.py --repo owner/repo --ref main

# 已知目录
gh repo read-dir src --repo owner/repo --ref main

# 较旧 gh 版本的备选方案
gh api "repos/OWNER/REPO/contents/src/main.py?ref=main" -H "Accept: application/vnd.github.raw+json"

关于输出格式、文件大小限制和目录列表注意事项,请参阅 API 模式。对于多文件探索,请改用克隆(参见 Agent 指南)。

列出仓库

列出用户或组织拥有的仓库,可设置语言和可见性过滤器。

gh repo list owner --limit 30

Releases

列出

按创建日期(最新在前)列出仓库中的 Releases。默认显示所有 Releases,包括预发布和草稿。

gh release list --repo owner/repo --limit 10

标志:

  • --exclude-pre-releases —— 排除预发布
  • --exclude-drafts —— 排除草稿

关键 JSON 字段:tagName、name、publishedAt、isLatest、isDraft、isPrerelease、isImmutable

查看(更新日志、资产)

显示 Release 的更新日志正文、标签、资产和元数据。省略标签可查看最新 Release。

gh release view --repo owner/repo                         # 最新 Release
gh release view v1.2.0 --repo owner/repo                  # 特定标签
gh release view v1.2.0 --json tagName,body,assets,publishedAt

关键 JSON 字段:tagName、name、body、assets、author、publishedAt、isDraft、isPrerelease、isImmutable、url

Issues

列出

列出仓库中的 Issue,可按状态、标签、分配人或搜索查询进行过滤。默认仅显示打开的 Issue。

gh issue list --repo owner/repo
gh issue list --repo owner/repo --state all --label bug --assignee @me
gh issue list --repo owner/repo --search "error no:assignee sort:created-asc"

标志:

  • --state VALUE —— open(默认)、closed、all
  • --label NAME —— 按标签过滤(可重复使用)
  • --assignee LOGIN —— 按分配人过滤(@me 为自己)
  • --search QUERY —— GitHub 搜索语法

关键 JSON 字段:number、title、state、stateReason、author、labels、assignees、createdAt、updatedAt、url

查看

显示 Issue 的标题、正文、标签、分配人和状态。使用 --comments 可包含完整评论线程。

gh issue view 123
gh issue view 123 --comments
gh issue view 123 --json title,body,labels,comments,state

创建

使用标题、正文、标签和分配人创建一个新 Issue。

gh issue create --title "Bug: description" --body "Details..." --label bug --assignee user1

编辑

更新 Issue 的标题、正文、标签、分配人或里程碑。所有标志可在一次调用中组合使用。

标志:

  • --title TEXT / --body TEXT —— 更新标题或正文
  • --add-label NAME / --remove-label NAME —— 修改标签
  • --add-assignee LOGIN / --remove-assignee LOGIN —— 修改分配人
  • --milestone NAME / --remove-milestone —— 设置或移除里程碑

评论

在现有 Issue 中添加评论。

gh issue comment 123 --body "Comment text"

关闭 / 重新打开

关闭或重新打开 Issue。可选地指定关闭原因并留下评论。

gh issue close 123 --comment "Fixed in PR #456" --reason "not planned"
gh issue close 123 --duplicate-of 456
gh issue reopen 123

关闭原因:completed(默认)、not planned、duplicate。

状态

显示与你相关的 Issue 摘要:分配给你的、提及你的以及你创建的。

gh issue status

关于 Issue 类型、子 Issue、父级关系、阻塞依赖项及其 JSON 字段(需要支持的 GitHub 主机),请参阅 Issue 参考。

Pull Requests

使用这些命令来查看和检查 PR。对于创建、合并、审查和管理 PR,请参阅 Pull Requests 参考。

列出

列出仓库中的 Pull Request,可按状态、作者、标签或搜索查询进行过滤。默认仅显示打开的 PR。

gh pr list --repo owner/repo
gh pr list --repo owner/repo --state all --author @me --label "needs-review"
gh pr list --repo owner/repo --search "status:success review:required"
gh pr list --repo owner/repo --app dependabot

标志:

  • --state VALUE —— open(默认)、closed、merged、all
  • --draft —— 按草稿状态过滤
  • --author LOGIN / --assignee LOGIN —— 按作者或分配人过滤
  • --label NAME —— 按标签过滤
  • --search QUERY —— GitHub 搜索语法
  • --app NAME —— 按 GitHub 应用作者过滤(例如 dependabot)

关键 JSON 字段:number、title、state、author、headRefName、baseRefName、labels、reviewDecision、isDraft、statusCheckRollup、files、commits、reviews、url

查看

显示 PR 的标题、正文、审查状态、检查和其他元数据。不传参数时,显示当前分支的 PR。使用 --comments 可包含评论线程。

gh pr view 123
gh pr view 123 --comments
gh pr view 123 --json title,body,files,commits,reviews,reviewDecision

状态

显示与你相关的 PR 摘要:当前分支的 PR、你创建的 PR 以及需要你审查的 PR。

gh pr status

讨论

使用 gh discussion 进行仓库讨论(在 gh 2.94 中为预览功能)。以读取命令开始,并使用 --help 验证标志,因为命令集是预览的:

gh discussion list --repo owner/repo --limit 10
gh discussion view 123 --repo owner/repo --comments

关于创建、编辑、评论、回复线程、JSON 输出格式和 GraphQL 回退模式,请参阅 讨论参考。

搜索

跨 GitHub 搜索 Issue、PR、代码、提交和仓库。对于单个仓库,使用 gh issue list / gh pr list;对于跨仓库或所有者范围的查询,使用 gh search ...。

有关完整的搜索查询语法,请参阅 GitHub 搜索文档。有关每个子命令特有的标志,请运行 gh search <subcommand> --help。

速率限制: 搜索 API 的速率限制比核心 API 更严格。代码搜索限制最严格(已验证身份约 10 次/分钟;需要身份验证)。其他搜索命令允许已验证身份约 30 次/分钟,未验证身份约 10 次/分钟。使用 gh api rate_limit --jq '.resources | {search, code_search}' 检查当前配额。

何时改用克隆: 请参阅 Agent 指南了解何时克隆而非使用 API。

机器人和应用: 对于 GitHub 应用作者(如 Dependabot),使用 --app dependabot;--author dependabot 过滤用户账户,而非应用作者。

侦察: 当搜索不熟悉的仓库时,首先检查其主要语言以选择正确的 --extension 和 --language 值:

gh repo view owner/repo --json primaryLanguage --jq '.primaryLanguage.name'

Issues

使用关键字、标签、状态或 GitHub 搜索语法跨仓库搜索 Issue。

gh search issues "error handling" --repo owner/repo
gh search issues --label bug --state open --assignee @me
gh search issues --app dependabot --repo owner/repo
gh search issues --involves username --comments ">10" --repo owner/repo

关键标志:--repo、--owner、--state、--label、--assignee、--author、--app、--involves、--comments、--match、--sort、--include-prs。

PR

跨仓库搜索 Pull Request。支持按作者、审查状态、合并状态和草稿状态过滤。

gh search prs "refactor" --repo owner/repo
gh search prs --review-requested @me --state open
gh search prs --app dependabot --repo owner/repo
gh search prs --author username --merged --repo owner/repo

关键标志:--repo、--owner、--state、--merged、--draft、--author、--assignee、--app、--label、--review、--review-requested、--base、--head、--checks、--sort。

代码

跨 GitHub 仓库搜索文件内容。仅返回匹配的行(不包含行号,不包含周围上下文)。适用于定位包含特定模式的文件,但随后应通过文件读取或克隆仓库来理解代码逻辑。

限制: 使用旧版搜索引擎(结果可能与 github.com 不匹配)。仅搜索默认分支。仅索引小于 384 KB 的文件。每个查询必须至少包含一个搜索词(仅限限定符的搜索,如 --extension ts 单独使用会失败)。不支持 --sort 或 --order —— 结果始终按相关性排序。

gh search code "functionName" --repo owner/repo
gh search code "createServer" --repo owner/repo --extension ts
gh search code "lint" --repo owner/repo --filename package.json

关键标志:--repo、--owner、--extension、--filename、--language、--match、--size。

关键 JSON 字段:path、repository、sha、textMatches、url。

textMatches 字段提供带有字符级别匹配位置的片段上下文——当需要比默认文本输出更多上下文时,使用 --json path,textMatches。

提交

按提交消息文本、作者、提交者日期或哈希值搜索提交。

gh search commits "fix bug" --repo owner/repo
gh search commits --author username --committer-date ">2024-01-01"
gh search commits --hash abc1234

关键标志:--repo、--owner、--author、--committer、--author-date、--committer-date、--author-name、--author-email、--hash、--merge、--sort。

仓库

按关键字、语言、主题、星标数、许可或所有者搜索仓库。注意:此子命令上不可使用 --repo —— 使用 --owner 按所有者过滤。

gh search repos "keyword" --language python --sort stars --order desc
gh search repos --topic cli --stars ">1000" --language go

关键标志:--owner、--language、--topic、--stars、--forks、--license、--created、--updated、--match、--sort、--include-forks、--visibility。

排除限定符(连字符前缀)

包含排除项的搜索查询(如 -label:bug)需要特殊语法,以避免 shell 标志解释。所有标志(例如 --limit)必须出现在 -- 之前;-- 之后的所有内容都被解释为搜索查询文本:

# Unix-like shells
gh search issues -- "my query -label:bug"

# PowerShell
gh --% search issues -- "my query -label:bug"

…

[已截断用于翻译]

相关技能