gh skill:適用於 Copilot、Claude Code 與 Cursor 的 GitHub CLI 代理技能管理

GitHub 於 2026 年 4 月 16 日以公開預覽推出 gh skill 命令,它悄悄解決了 AI 輔助開發中最混亂的問題之一:當每個 AI 編碼助手有自己的目錄慣例、自己的安裝故事,以及自己對「技能」甚至是什麼的想法時,您如何分享與治理代理技能?

如果您一直在 .claude/skills、.agents/skills 與 ~/.copilot/skills 之間手動複製 SKILL.md 檔案,或僅為釘選您團隊信任的版本而 fork 存放庫,gh skill 就是您一直在等的命令。它對待代理技能的方式如同 npm 對待 JavaScript 套件、pip 對待 Python 程式庫——以搜尋、安裝、釘選、預覽、更新與發布作為第一級動詞。

本指南帶您走過 gh skill 實際做什麼、您日常會使用的乾淨使用模式,以及若您計畫跨團隊部署技能時重要的企業控制。

關鍵要點

  • **gh skill 是 AI 代理技能的套件管理員。**一個命令跨 GitHub Copilot、Claude Code、Cursor、Codex、Gemini CLI 與 Antigravity 運作。
  • **技能是標準,不是 GitHub 產品。**它們遵循開放的 Agent Skills 規範——一份 SKILL.md 檔案含 YAML frontmatter 加上選用的 scripts/、references/ 與 assets/ 目錄。
  • 來源追蹤內建。gh skill install 將來源、ref 與 tree SHA 寫入已安裝的 SKILL.md,讓 gh skill update 能無需猜測地偵測上游變更。
  • **版本釘選為第一級。**釘選至標籤(@v1.2.0)、commit SHA(@abc123def),或以 --pin 標記技能以保護它們免於例行更新。
  • **gh skill preview 是您的安全閘道。**在安裝前——尤其是在授予 shell 或 bash 存取權之前——閱讀技能的內容、指令稿與 allowed-tools。
  • **企業治理仍重要。**標籤保護、不可變發布、秘密掃描與程式碼掃描應在每個內部技能存放庫上啟用。

代理技能實際上是什麼

代理技能是一目錄的指示,教導 AI 代理如何做特定工作——產生 PR 描述、scaffold OpenAPI 規格、執行安全審查、強制執行編碼標準。生態系已收斂於簡單結構:

my-skill/
├── SKILL.md              # 必要:YAML frontmatter + 指示
├── scripts/              # 選用:代理可執行的可執行輔助程式
├── references/           # 選用:代理可載入的支援文件
└── assets/               # 選用:範本、提示、fixtures

SKILL.md 檔案同時攜帶指示與代理決定何時載入技能所需的中繼資料:

---
name: pr-description-writer
description: 撰寫結構化的 GitHub pull request 描述,含摘要、測試計畫與風險章節。在開啟或更新 PR 時使用。
license: MIT
allowed-tools:
  - read
  - write
---

# PR Description Writer

被叫用時,閱讀當前分支 diff,識別變更範圍,
並產生含三個章節的 pull request 描述:

1. **Summary** — 2-3 個描述意圖的項目符號。
2. **Test plan** — 變更如何被驗證的檢查清單。
3. **Risk** — 關於退回與爆炸半徑的一句話。

若 diff 超過 400 行,使用 `scripts/format-diff.sh`。

兩個細節在此重要。description 欄位(最多 1024 字元)是代理決定是否載入技能時閱讀的內容——因此像寫工具提示般寫它,而非 README。而 allowed-tools 預先核准工具叫用;將 shell 與 bash 從清單中省略,強制代理在執行終端機命令前詢問,這是您對任何未完全稽核內容應採取的姿態。

乾淨使用範例

這些是您實際會輸入的命令。每個範例假設 GitHub CLI v2.90.0 或更新且 gh skill 可用。

發現:搜尋生態系

# 跨公開存放庫搜尋符合關鍵字的技能
gh skill search mcp

# 直接瀏覽策展集合
gh skill install github/awesome-copilot

在不指定技能名稱的情況下執行 gh skill install OWNER/REPO 會將您帶入互動選擇器,列出存放庫中的每個技能。這是探索新集合最快的方式。

檢查:安裝前預覽

# 列印技能的 SKILL.md 而不安裝任何內容
gh skill preview github/awesome-copilot documentation-writer

# 在互動終端機中,preview 開啟檔案選擇器讓您
# 可個別審查 scripts/ 與 references/
gh skill preview github/awesome-copilot security-review

gh skill preview 是安全閘道。在對任何接觸生產程式碼的專案安裝前使用它,並仔細閱讀 allowed-tools——預先核准 bash 的技能可在代理叫用它的瞬間執行任意命令。

安裝:專案範圍、使用者範圍、特定版本

# 安裝最新版本至當前專案(.agents/skills、.claude/skills 等)
gh skill install github/awesome-copilot documentation-writer

# 安裝至您的使用者設定檔,讓它跨每個專案可用
gh skill install github/awesome-copilot documentation-writer --scope user

# 釘選至特定 release tag
gh skill install github/awesome-copilot documentation-writer@v1.2.0 --pin

# 釘選至特定 commit SHA 以獲最大可重現性
gh skill install github/awesome-copilot documentation-writer@abc123def --pin

# 僅為一個代理主機安裝(在技能依工具分歧時有用)
gh skill install github/awesome-copilot documentation-writer --agent claude-code

gh skill 知道每個代理期望其技能的位置。安裝時,它寫入 Copilot 與 Cursor 的 .agents/skills、Claude Code 的 .claude/skills,以及每個其他支援主機的同等路徑——根據機器上設定的內容自動進行。

更新:先乾跑,再向前推進

# 掃描每個已安裝技能並顯示哪些有上游變更——不寫入
gh skill update --dry-run

# 互動式更新,針對每個變更提示
gh skill update

# 非互動式更新(在 CI/CD 中使用)
gh skill update --all

# 包含先前被釘選的技能
gh skill update --all --unpin

更新機制讀取 gh skill install 寫入每個 SKILL.md 的 tree SHA,並將其與上游存放庫比較。這就是為何來源追蹤不是可選的——它是讓安全更新成為可能的基本要素。

發布:出貨您自己的技能

從包含一或多個技能目錄的存放庫開始:

# 針對 agentskills.io 規範驗證一切而不發布
gh skill publish --dry-run

# 自動修正常見問題(從已提交檔案剝離安裝中繼資料等)
gh skill publish --dry-run --fix

# 互動式發布:標記 release 並開啟 GitHub Releases
gh skill publish

發布驗證技能名稱(小寫、連字號、64 字元上限)、確認必要 frontmatter 存在,並檢查 allowed-tools 是正確型別。它也推動您啟用 agent-skills 存放庫主題,並建議標籤保護、秘密掃描與程式碼掃描——這些是他人會安裝的任何技能存放庫上您想要的最小控制。

CI/CD:在 GitHub Actions 工作流程中安裝技能

name: Release notes with Copilot CLI

on:
  push:
    tags:
      - 'v*'

jobs:
  release-notes:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4

      - name: Install GitHub CLI skills
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh skill install github/awesome-copilot release-notes-writer@v1.2.0 --pin

      - name: Generate release notes
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh copilot run "Write release notes for $GITHUB_REF_NAME using the release-notes-writer skill" \
            --allow-all-paths \
            > RELEASE_NOTES.md

      - name: Publish release
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh release create "$GITHUB_REF_NAME" --notes-file RELEASE_NOTES.md

此模式——釘選技能、透過 Copilot CLI 叫用它、提交輸出——可推廣至 changelog 產生、安全摘要、合規報告與入門 scaffolding。

企業:大量 bootstrap 開發人員環境

#!/usr/bin/env bash
# bootstrap-skills.sh — 在新筆電或 Codespaces 上執行

set -euo pipefail

SKILLS=(
  "myorg/skills security-review@v2.1.0"
  "myorg/skills pr-description-writer@v1.4.0"
  "myorg/skills terraform-reviewer@v3.0.1"
  "github/awesome-copilot documentation-writer@v1.2.0"
)

for spec in "${SKILLS[@]}"; do
  gh skill install $spec --scope user --pin
done

gh skill update --dry-run

釘選每個技能並以 --pin 再次釘選意味 bootstrap 指令稿是確定性的:每位開發人員確切獲得您安全團隊核准的版本,且在您更新指令稿前沒有東西悄悄改變。

為何 gh skill 對企業團隊重要

在 gh skill 之前,大型組織內的「分享技能」通常看起來像 Slack 訊息、zip 檔案,或沒有 release tag 的 fork 存放庫。這在一個團隊的規模下有效,在一家公司的規模下崩潰。以下是當您採用 gh skill 作為規範分發機制時改變的內容。

關注在 gh skill 之前有 gh skill
發現部落知識、Slack 釘選gh skill search + 策展的組織存放庫
版本控制「最新 main」或手動複製Git 標籤、commit SHA、--pin 旗標
更新偵測手動 diffSKILL.md 中繼資料中的 tree SHA 比較
可攜性每代理一技能,重複一技能,六代理,自動放置
安全審查臨時gh skill preview + 發布時掃描
稽核無frontmatter 中的來源、ref 與 tree SHA

稽核列是企業安全團隊最在乎的。因為來源存放庫、git ref 與 tree SHA 直接寫入已安裝的 SKILL.md,您可以走過開發人員的筆電,以簡單的 find 命令回答「安裝了哪些技能,從哪裡,什麼版本?」——無需單獨清冊系統。

可良好推廣的安全模式

三個實務從單一開發人員擴展到企業而無需新工具。

**1. 每次安裝前預覽。**讓 gh skill preview OWNER/REPO skill-name 成為您審查清單的一部分。兩分鐘閱讀 SKILL.md 加 scripts/ 目錄可捕捉大多紅旗——提示注入、未預期的網路呼叫、任何在工作樹外寫入的內容。

**2. 對 allowed-tools 無情。**除非您已稽核技能參考的每個指令稿,否則從 allowed-tools 省略 shell 與 bash。強制代理在執行命令前詢問,是您對抗攻擊者控制技能或提示注入負載的最大單一控制。

**3. 硬化您的內部技能存放庫。**當 gh skill publish 推動您啟用標籤保護、秘密掃描與程式碼掃描時,對三者都說是。標籤保護特別使發布不可變,這是讓下游消費者信任 --pin 至標籤的基礎。

如果您想要這些控制如何融入企業 AI 計畫——包括模型治理、MCP 伺服器政策與代理預算控制——的更廣框架,請見我們的企業 AI 代理諮詢指南與我們的 Copilot CLI 企業鷹架文章。相同原則適用:技能是新攻擊面,答案是治理,而非禁止。

gh skill 在更廣生態系中的位置

gh skill 是快速移動版圖的一塊。如果您正在建構技能策略,這些相關部分值得一起了解:

  • Agent Skills 規範於 agentskills.io——gh skill 針對其驗證的開放標準。
  • Claude Code 與 Gemini CLI 技能撰寫——涵蓋於我們的跨 Claude Code 與 Gemini CLI 技能建立工具文章中。
  • Model Context Protocol (MCP)——技能與 MCP 伺服器互補。技能攜帶指示;MCP 伺服器攜帶能力。最強大的代理配置使用兩者。
  • Windows 365 + Intune 治理——當開發人員筆電是雲端電腦時,技能部署變成 Intune 諮詢問題,而非僅開發人員工具問題。

gh skill 變更記錄明確指出該命令在公開預覽期間可能變更,因此預期介面在接下來幾次發布中演進。基本要素——SKILL.md、來源中繼資料、標籤與 SHA 釘選——是穩定的賭注。

開始使用清單

  1. 升級 GitHub CLI至 v2.90.0 或更新(gh --version)。
  2. **執行 gh skill --help**以確認命令可用。
  3. **安裝前預覽。**讓 gh skill preview 成為肌肉記憶。
  4. **在生產中釘選一切。**對任何在 CI/CD 中執行的技能使用 --pin 與特定標籤或 SHA。
  5. **建立內部技能存放庫。**新增 agent-skills 主題,啟用標籤保護,啟用秘密與程式碼掃描,並使用 gh skill publish 出貨您的第一個內部技能。
  6. **記錄您的治理模型。**誰核准新技能?誰擁有內部登錄?誰審查 allowed-tools?

如果您的團隊想要協助將技能治理作為更廣企業 AI 推出的一部分建立起來,Big Hat Group 的 OpenClaw 諮詢實務涵蓋完整堆疊——技能、MCP 伺服器、代理治理、Windows 365 交付與 Intune 政策。

跨 GitHub 2026 年 4 月發布——VS Code 1.116 中內建的 Copilot、更嚴格的個人方案、Claude Opus 4.7 推出,以及 gh skill 本身——的更廣故事,涵蓋於最新的 Copilot 週報中。

技能終於是第一級成品。像成品般出貨它們。