Community寫作與編輯github.com

MichaelYochpaz/agent-skills

精心設計、token 高效的 Agent 技能,以實現可靠的代理工作流程。

agent-skills 是什麼?

此技能提供一套以 GitHub CLI (`gh`) 為基礎的全面性操作指南與指令範例,專為 AI Agent(如 Claude Code、Cursor、Codex)設計,使其能透過命令列介面與 GitHub 有效率且安全地互動。它涵蓋了儲存庫管理、版本發行、議題與拉取請求處理、討論區操作、跨平台搜尋(包括程式碼、提交紀錄與儲存庫)等核心功能。技能文件特別強調 token 使用效率,建議優先使用文字輸出而非 JSON,並在瀏覽日誌或差異時先縮小輸出範圍。為確保操作安全,文件明確列出具有修改狀態的「寫入操作」(如建立、編輯、刪除、合併等)以及可能無法回復的「破壞性操作」,要求 Agent 在使用者確認後才能執行。此外,此技能也整合了多種 API 與搜尋的速率限制資訊,並針對不同情境(如讀取已知檔案路徑 vs. 探索不熟悉的程式碼庫)提供了明確的策略選擇(使用 `gh repo read-file` 或 clone 到暫存目錄)。支援平台為 GitHub CLI `gh` 2.94 及更高版本。

相容平台~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 互動:儲存庫、版本發行、議題、PR、討論區、搜尋、程式碼審查和 Actions。

經驗證可在 gh 2.95.0 版本上使用。

Agent 指南

  • 對於已知的遠端檔案或目錄,請使用 gh repo read-file / gh repo read-dir(gh 2.95 中的預覽功能)。對於較舊的 gh 版本或僅需 API 的情況,請使用 API 模式 中的內容 API 後備方案。
  • 當任務需要跨檔案搜尋或探索路徑未知的不熟悉程式碼時,請 clone 到暫存目錄(gh repo clone owner/repo <temp-dir> -- --depth 1),然後使用本機檔案讀取和搜尋工具。
  • 對於讀取/檢視,偏好預設的文字輸出而非 --json——這在 token 使用上更有效率。僅在需要以程式化方式提取特定欄位時,才使用帶有 --jq 的 --json。若要發現支援的欄位,請在不帶欄位列表的情況下執行帶有 --json 的命令,然後僅請求您需要的欄位。
  • 檢視日誌或差異時,請先縮小輸出範圍(例如 --name-only、--log-failed),然後再擷取完整內容。
  • 在已 clone 的儲存庫內執行時,不需要 --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

Clone

本地端 Clone 儲存庫。會自動設定遠端,對於 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 模式。對於多檔案探索,請改為 clone(請參閱 Agent 指南)。

列出儲存庫

列出由使用者或組織擁有的儲存庫,可選語言和能見度篩選器。

gh repo list owner --limit 30

版本發行

列表

列出儲存庫中的版本發行,依建立日期排序(最新的在前)。預設顯示所有版本發行,包括預發行版和草稿。

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

旗標:

  • --exclude-pre-releases -- 排除預發行版
  • --exclude-drafts -- 排除草稿

關鍵 JSON 欄位:tagName、name、publishedAt、isLatest、isDraft、isPrerelease、isImmutable

檢視(變更日誌、資產)

顯示版本發行的變更日誌主體、標籤、資產和後設資料。省略標籤以檢視最新版本發行。

gh release view --repo owner/repo                         # 最新版本發行
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

議題

列表

列出儲存庫中的議題,可依狀態、標籤、指派對象或搜尋查詢進行篩選。預設僅列出開啟的議題。

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

檢視

顯示議題的標題、主體、標籤、指派對象和狀態。使用 --comments 以包含完整的留言串。

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

建立

建立新的議題,包含標題、主體、標籤和指派對象。

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

編輯

更新議題的標題、主體、標籤、指派對象或里程碑。所有旗標可以在一次呼叫中組合使用。

旗標:

  • --title TEXT / --body TEXT -- 更新標題或主體
  • --add-label NAME / --remove-label NAME -- 修改標籤
  • --add-assignee LOGIN / --remove-assignee LOGIN -- 修改指派對象
  • --milestone NAME / --remove-milestone -- 設定或移除里程碑

留言

在現有議題上新增留言。

gh issue comment 123 --body "Comment text"

關閉 / 重新開啟

關閉或重新開啟議題。可以選擇指定關閉原因並留下留言。

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。

狀態

顯示與您相關的議題摘要:指派給您的、提及您的以及由您開啟的議題。

gh issue status

有關議題類型、子議題、父關係、封鎖相依性及其 JSON 欄位(需要在支援的 GitHub 主機上),請參閱 Issues reference。

拉取請求

使用這些命令來檢視和檢查 PR。有關建立、合併、審查和管理 PR,請參閱 Pull Requests reference。

列表

列出儲存庫中的拉取請求,可依狀態、作者、標籤或搜尋查詢進行篩選。預設僅列出開啟的 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 App 作者篩選(例如 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 後備模式,請參閱 Discussions reference。

搜尋

跨 GitHub 搜尋議題、PR、程式碼、提交紀錄和儲存庫。對單一儲存庫使用 gh issue list / gh pr list;跨儲存庫或跨擁有者的查詢則使用 gh search ...。

有關完整的搜尋查詢語法,請參閱 GitHub search docs。有關每個子命令的特定旗標,請執行 gh search <subcommand> --help。

速率限制: 搜尋 API 的速率限制比核心 API 更嚴格。程式碼搜尋的限制最嚴格(~10/分鐘,已驗證;需要驗證)。其他搜尋命令允許已驗證 ~30/分鐘,或未驗證 ~10/分鐘。使用 gh api rate_limit --jq '.resources | {search, code_search}' 檢查目前配額。

何時該 Clone 而非搜尋: 請參閱 Agent 指南,了解何時該 Clone 而非使用 API。

Bot 與 App: 對於 GitHub App 作者(例如 Dependabot),請使用 --app dependabot;--author dependabot 會過濾使用者帳戶,而非 App 作者。

偵察: 在探索不熟悉的儲存庫時,請先檢查其主要語言,以選擇正確的 --extension 和 --language 值:

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

議題

使用關鍵字、標籤、狀態或 GitHub 搜尋語法,跨儲存庫搜尋議題。

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

跨儲存庫搜尋拉取請求。支援依作者、審查狀態、合併狀態和草稿狀態進行篩選。

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 儲存庫中搜尋檔案內容。僅回傳匹配的行(不含行號,不含周圍上下文)。對於定位包含特定模式的檔案很有用,但後續應透過讀取檔案或 Clone 儲存庫來理解程式碼邏輯。

限制: 使用舊版搜尋引擎(結果可能與 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 Shell
gh search issues -- "my query -label:bug"

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

…

[truncated for translation]

相關技能