gh skill：GitHub全新CLI命令，让AI智能体技能变身可安装、可组合的软件包

1 引言

数月来，我一直在本地 Claude Code、OpenCode、OpenClaw、Hermes等环境中使用SKILL.md文件。针对不同任务编写专属指令，分门别类存放，以此教会 AI 智能体适配特定工作流，效果十分出色。但一直有个恼人的问题——分发与复用。想在另一台设备上复用某个技能，我还得像回到 2012 年一样，手动拷贝文件，版本管理更是无从谈起。

显然，GitHub 也被同样的痛点困扰。就在上周，GitHub 正式推出gh skill—— 这一全新 GitHub CLI 命令，为 AI 智能体技能打造了一套类似npm之于 JavaScript、cargo之于 Rust 的标准化管理体系。它不仅解决了安装、更新、版本锁定等基础问题，更在供应链安全与可组合性上做出了前瞻设计。

本文将在介绍gh skill现有能力的基础上，结合其设计理念与生态缺口，给出一个面向未来的完善方案。如果你是 AI 应用开发者、DevOps 工程师或技术团队负责人，本文会帮助你提前布局智能体技能工程化。

2 到底什么是「智能体技能」

所谓智能体技能（Agent Skills），核心就是SKILL.md文件：一套包含元数据、指令、脚本与资源的文件夹，用来告诉 AI 智能体如何完成某一项具体任务。

例如：编写符合公司规范的提交信息、执行特定测试范式、按标准格式生成 API 文档等。

这类技能遵循 agentskills.io 开放规范，可兼容 GitHub Copilot、Claude Code、Cursor、Codex 以及 Gemini CLI 等多款工具。智能体本身不关心技能由谁加载，只关心文件结构是否符合约定。

一个典型的技能目录结构如下：

my-skill/

├── SKILL.md          # 核心指令文件，含 frontmatter 元数据

├── scripts/          # 可选：辅助脚本（Python、Shell等）

├── templates/        # 可选：输出模板

└── resources/        # 可选：静态资源（图片、配置文件）

SKILL.md的 frontmatter 示例：

---

name:documentation-writer

version:1.2.0

description:生成符合Google风格的Python文档字符串

dependencies:

- name:markdown-formatter

  source:github/awesome-copilot

  version:">=2.0"

author:github/hankxdev

tags: [docs, python, automation]

---

...具体指令内容（Markdown正文）...

3 核心功能（完善版）

使用前提：GitHub CLI 版本 ≥ v2.90.0，并建议升级至最新版以获得完整安全特性。

3.1 安装技能：清晰的作用域与路径

# 基本安装：从仓库安装指定技能

gh skill install github/awesome-copilot --skill documentation-writer

# 支持仓库中包含多个技能时，通过 --subpath 定位子目录

gh skill install github/foo/bar --skill pdf-parser --subpath skills/parsers

# 指定目标智能体与作用域

gh skill install github/awesome-copilot --skill code-reviewer \

  --agent claude-code --scope user

# 项目级安装（推荐）：将技能安装到当前项目的 .skills/ 目录

gh skill install github/awesome-copilot --skill test-runner --scope project

设计要点：

不再使用两个位置参数，而是显式的--skill选项，避免歧义。

支持--subpath用于非标准布局的仓库。

--scope

支持user（全局用户目录）、project（当前项目）、system（需特权），技能自动被对应智能体发现（见下文“技能发现协议”）。

3.2 技能发现协议：告别为每个智能体单独配置

不同智能体的技能加载路径千差万别。gh skill不再维护一个日益膨胀的--agent列表，而是定义了一套标准发现机制：

用户级技能：

$XDG_DATA_HOME/agent-skills/（默认~/.local/share/agent-skills/）

项目级技能：

<project-root>/.skills/

智能体只需按照规范，在启动时扫描上述目录（或通过环境变量AGENT_SKILL_PATH覆盖）即可自动加载所有已安装技能。gh skill install会自动创建符号链接（--link模式，默认）或复制文件，无需为每个智能体重复适配。

# 创建符号链接（节省空间，便于统一更新）

gh skill install github/foo/bar --skill linter --link

# 强制复制（用于离线环境或容器）

gh skill install github/foo/bar --skill linter --copy

3.3 版本锁定与签名验证

# 锁定到特定 Git tag（建议使用语义化版本）

gh skill install github/awesome-copilot --skill doc-writer --pin v1.2.0

# 锁定到提交哈希，实现完全可复现安装

gh skill install github/awesome-copilot --skill doc-writer --pin abc123def

# 同时验证发布者签名（需要技能仓库开启 Sigstore 或 GitHub Attestations）

gh skill install github/awesome-copilot --skill doc-writer --pin v1.2.0 --verify-signature

被锁定版本的技能，在执行gh skill update --all时会被跳过，升级操作完全自主可控。

3.4 依赖管理与锁定文件

技能可以在SKILL.md中声明对其他技能的依赖。gh skill install会自动解析并递归安装依赖，生成锁定文件.skill-lock.json，记录每个技能的来源、版本、哈希及签名。

# 安装技能及其所有依赖

gh skill install github/team-a/skills --skill data-pipeline

# 根据项目中的 .skill-lock.json 精确恢复环境

gh skill sync

# 查看依赖树

gh skill tree data-pipeline

依赖声明示例：

dependencies:

-name:yaml-validator

source:github/validators/skills

version:"~1.0"

-name:log-formatter

source:https://github.com/logging/skills

version:"2.x"

3.5 检查与更新技能

gh skill update          # 交互式更新，展示每个技能的变更日志

gh skill update --all    # 批量更新所有技能（跳过锁定项）

gh skill update --dry-run # 预览更新，不实际执行

3.6 校验与发布技能：完整的 CI/CD 集成

发布技能不再是简单的校验，而是完整的交付流程。

# 本地校验是否符合 agentskills.io 规范

gh skill validate

# 自动修复元数据问题（如缺少版本号、描述等）

gh skill validate --fix

# 发布到官方注册表（或指定私有注册表）

gh skill publish --registry https://skills.mycompany.com

publish命令会执行以下操作：

运行validate确保技能合规。

询问是否创建 Git tag（如skill-name/v1.0.0），并强制禁止 force push（通过仓库设置或 GitHub API）。

将技能打包并上传到注册表，同时生成签名证明（使用 Sigstore）。

若选择--immutable，则技能发布后内容永不可变，即便是仓库管理员也无法篡改。

为了融入团队工作流，建议在 GitHub Actions 中配置自动发布：

name:PublishSkill

on:

push:

tags:

-'skill/*/v*'

jobs:

publish:

runs-on:ubuntu-latest

steps:

-uses:actions/checkout@v4

-run:ghskillvalidate--fix

-run:ghskillpublish--immutable--sign

env:

GH_TOKEN:${{secrets.GH_TOKEN}}

4 供应链安全：从源头到运行时的多重防线

智能体技能本质是指令集，直接决定 AI 在代码仓库中的行为。被恶意篡改的技能，就像被植入后门的 npm 包，是实打实的安全攻击面。gh skill通过以下机制构筑纵深防御：

4.1 可验证的溯源元数据

安装技能时，工具会将源仓库、引用标识、Git 树哈希、签名证书写入独立的元数据文件.skill-meta/<skill-name>.json，而不是直接塞进SKILL.md（因为后者可能被技能自身修改）。每次执行gh skill verify，都会重新计算当前技能目录的哈希并与元数据比对，同时验证签名链。

4.2 不可变发布 + 签名

发布者通过gh skill publish --immutable创建只读的 Git tag，并利用 GitHub 的attestations功能生成一个不可伪造的签名证书。

安装时使用--verify-signature要求验证签名，确保技能确实来自声称的发布者，且内容未被篡改。

锁定到某个 tag 后，即便远程仓库被攻破，只要用户保留本地元数据并定期验证，就能抵御替换攻击。

4.3 依赖完整性校验

锁定文件.skill-lock.json不仅记录顶级技能，还递归记录所有依赖的来源、版本和哈希。gh skill sync会强制校验每个依赖的完整性，若发现哈希不匹配则拒绝加载，并提示用户执行gh skill audit进行安全审计。

4.4 离线审计与策略

# 审计所有已安装技能的安全性（检查已知漏洞库、过时依赖等）

gh skill audit

# 生成 SBOM（软件物料清单），用于合规扫描

gh skill sbom --format spdx

5 生态展望：从文件拷贝到真正的技能工程化

近几个月，SKILL.md模式已在业内悄然普及：

Anthropic 官方推出参考技能仓库

GitHubawesome-copilot社区技能库持续壮大

VS Code、Cursor 原生支持技能加载

Claude Code 可自动识别并加载技能

但此前整个生态缺少专业化工具链：分享靠传文件，更新靠记路径，没有依赖管理、没有版本历史、没有完整性校验。

gh skill正是这个生态急需的包管理器，而且通过本文提出的完善设计，它超越了简单的安装器，成为一个完整的技能工程化平台：

项目级隔离：

不同项目可使用同一技能的不同版本，避免冲突。

依赖管理：

技能可组合，复用现有能力，避免重复造轮子。

可复现构建：

锁定文件 + 签名确保任何环境都能获得完全一致的技能行为。

安全默认：

从发布到安装，签名验证、哈希校验贯穿始终。

目前生态仍处于早期：规范还在迭代，社区仓库规模有限，但底层设计已足够扎实。如果你为团队或个人维护技能库，现在就是最佳切入点——提前建立发布流水线、锁定策略和安全审计流程，待生态爆发时，你已是先行者。

# 升级至最新版本

gh extension upgrade --all

# 快速体验：安装一个文档编写技能并验证签名

gh skill install github/awesome-copilot --skill documentation-writer --verify-signature

# 查看已安装技能及其依赖树

gh skill list --tree

未来，我们期待 GitHub 官方技能注册表上线，支持搜索、评分、推荐，让优秀的技能能被全球开发者发现。而作为开发者，你现在就可以开始行动：

将团队内部常用的 Prompt 片段、测试脚本、代码生成模式封装为符合规范的技能。

在公司私有仓库中托管技能，并使用gh skill publish --registry搭建内部技能商店。

在 CI 中强制gh skill audit，确保供应链安全。

AI 智能体的能力，将不再局限于模型本身，而由可自由组合、安全可信的技能生态无限扩展。gh skill正是这一愿景的基石。