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 产品。 它们遵循开放的智能体技能规范——一个带 YAML frontmatter 的 SKILL.md 文件加上可选的 scripts/、references/ 和 assets/ 目录。
  • 出处内置。 gh skill install 将 source、ref 和 tree SHA 写入已安装的 SKILL.md，使 gh skill update 可无需猜测地检测上游变更。
  • 版本固定是一等公民。 固定到标签（@v1.2.0）、提交 SHA（@abc123def），或用 --pin 标记技能以保护它们免受例行更新。
  • gh skill preview 是你的安全门。 在安装前阅读技能的内容、脚本和 allowed-tools——尤其是在授予 shell 或 bash 访问权限之前。
  • 企业治理仍然重要。 标签保护、不可变发布、密钥扫描和代码扫描应在每个内部技能仓库上启用。

智能体技能究竟是什么

智能体技能是一个指令目录，教 AI 智能体如何做一项特定工作——生成 PR 描述、搭建 OpenAPI 规范、运行安全审查、强制执行编码标准。生态系统已收敛到一个简单结构：

my-skill/
├── SKILL.md              # required: YAML frontmatter + instructions
├── scripts/              # optional: executable helpers the agent can run
├── references/           # optional: supporting docs the agent can load
└── assets/               # optional: templates, prompts, fixtures

SKILL.md 文件既承载指令也承载智能体决定何时加载技能所需的元数据：

---
name: pr-description-writer
description: Writes structured GitHub pull request descriptions with summary, test plan, and risk sections. Use when opening or updating a PR.
license: MIT
allowed-tools:
  - read
  - write
---

# PR Description Writer

When invoked, read the current branch diff, identify the scope of changes,
and produce a pull request description with three sections:

1. **Summary** — 2-3 bullets describing the intent.
2. **Test plan** — checklist of how the change was verified.
3. **Risk** — one sentence on rollback and blast radius.

Use `scripts/format-diff.sh` if the diff exceeds 400 lines.

这里有两个细节重要。description 字段（最多 1024 个字符）是智能体决定是否加载技能时阅读的内容——所以像写工具提示一样写它，而非 README。allowed-tools 预批准工具调用；将 shell 和 bash 排除在列表外会强制智能体在运行终端命令之前询问，这正是你对任何未完全审计的内容想要的姿态。

干净用例示例

这些是你实际会输入的命令。每个示例假定 GitHub CLI v2.90.0 或更新版本且 gh skill 可用。

发现：搜索生态系统

# Search across public repositories for skills matching a keyword
gh skill search mcp

# Browse curated collections directly
gh skill install github/awesome-copilot

运行 gh skill install OWNER/REPO 而不带技能名称会让你进入交互式选择器，列出仓库中的每个技能。这是探索新集合的最快方式。

检查：安装前预览

# Print a skill's SKILL.md without installing anything
gh skill preview github/awesome-copilot documentation-writer

# In an interactive terminal, preview opens a file picker so you
# can review scripts/ and references/ individually
gh skill preview github/awesome-copilot security-review

gh skill preview 是安全门。在向触及生产代码的项目进行任何安装之前使用它，并仔细阅读 allowed-tools——预批准 bash 的技能可在智能体调用它的瞬间运行任意命令。

安装：项目范围、用户范围、特定版本

# Install the latest version to the current project (.agents/skills, .claude/skills, etc.)
gh skill install github/awesome-copilot documentation-writer

# Install to your user profile so it's available across every project
gh skill install github/awesome-copilot documentation-writer --scope user

# Pin to a specific release tag
gh skill install github/awesome-copilot documentation-writer@v1.2.0 --pin

# Pin to a specific commit SHA for maximum reproducibility
gh skill install github/awesome-copilot documentation-writer@abc123def --pin

# Install only for one agent host (useful when skills diverge per tool)
gh skill install github/awesome-copilot documentation-writer --agent claude-code

gh skill 知道每个智能体期望其技能在哪里。安装时，它会自动根据机器上配置的内容写入 .agents/skills（用于 Copilot 和 Cursor）、.claude/skills（用于 Claude Code）以及每个其他受支持主机的等效路径。

更新：先空运行，再推进

# Scan every installed skill and show which have upstream changes — no writes
gh skill update --dry-run

# Update interactively, prompting for each change
gh skill update

# Non-interactive update (use in CI/CD)
gh skill update --all

# Include skills that were previously pinned
gh skill update --all --unpin

更新机制读取 gh skill install 写入每个 SKILL.md 的 tree SHA 并将其与上游仓库比较。这就是为什么出处不是可选的——它是使安全更新成为可能的基础原语。

发布：交付你自己的技能

从包含一个或多个技能目录的仓库开始：

# Validate everything against the agentskills.io spec without publishing
gh skill publish --dry-run

# Auto-fix common issues (strips install metadata from committed files, etc.)
gh skill publish --dry-run --fix

# Interactive publish: tags a release and opens 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 调用它、提交输出——可推广到变更日志生成、安全摘要、合规报告和入门脚手架。

企业：批量引导开发者环境

#!/usr/bin/env bash
# bootstrap-skills.sh — run on new laptops or in 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 固定意味着引导脚本是确定性的：每个开发者获得你安全团队批准的确切版本，在你更新脚本之前一切都静默不变。

为什么 gh skill 对企业团队重要

在 gh skill 之前，大型组织内"共享技能"通常看起来像一条 Slack 消息、一个 zip 文件，或一个没有发布标签的 fork 仓库。这在一个团队的规模下可行，在一家公司的规模下破裂。以下是当你采纳 gh skill 作为规范分发机制时改变的事情。

关注点gh skill 之前使用 gh skill
发现部落知识、Slack 置顶gh skill search + 策划的组织仓库
版本控制“最新 main"或手动复制Git 标签、提交 SHA、--pin 标志
更新检测手动差异比较SKILL.md 元数据中的 Tree SHA 比较
可移植性每个智能体一个技能，重复一个技能，六个智能体，自动放置
安全审查临时gh skill preview + 发布时扫描
审计无frontmatter 中的 source、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 是快速移动的图景中的一块。如果你正在构建技能战略，这些相关部分值得一起理解：

  • 智能体技能规范位于 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 周报中涵盖。

技能终于成为一等公民制品。像交付制品一样交付它们。