GitHub CLI 的 gh skill 命令实战:Agent Skills 的搜索、预览、安装、更新与发布
GitHub CLI 的 gh skill 命令实战Agent Skills 的搜索、预览、安装、更新与发布【免费下载链接】cliGitHub’s official command line tool项目地址: https://gitcode.com/GitHub_Trending/cli/cli本文基于 GitHub CLIcli/cli仓库中的 skills/gh-skill/SKILL.md 展开系统讲解gh skill命令族search/preview/install/update/publish的完整用法并结合 pkg/cmd/skills/ 与 internal/skills/ 下的源码实现说明版本解析顺序、技能发现约定、安装元数据注入与原子化更新等底层机制。读完后你既能以开发者身份完成技能的安装维护与发布也能让 Agent 自主管理其可用的技能集。一、命令总览与定位gh skill用于从 GitHub 仓库安装、预览、搜索、更新和发布 Agent Skills。Agent 可以借助它把自己的技能集与一个或多个 GitHub 仓库保持同步。该命令也注册了复数别名gh skills在脚本与文档中推荐优先使用规范的单数形式gh skill。从顶层命令的源码 pkg/cmd/skills/skills.go 可以看到几个关键事实命令的 Short 描述标注为 Install and manage agent skills (preview)即技能管理功能处于预览状态行为可能在不另行通知的情况下变化通过Aliases: []string{skills}注册了复数别名通过cmd.AddCommand(...)挂载了六个子命令install、list、preview、publish、search、update分别实现在 pkg/cmd/skills/install/install.go、pkg/cmd/skills/list/list.go 等文件中PersistentPreRunE中调用telemetry.SetSampleRate(ghtelemetry.SAMPLE_ALL)即技能类命令的遥测采样率为全量这与其预览阶段的特性收集需求相呼应。二、搜索gh skill searchgh skill search query # 自由文本搜索 gh skill search query --owner org # 限定到某个 owner gh skill search query --limit 20 --page 2 gh skill search query --json skillName,repo,descriptiongh skill search会跨所有公开的 GitHub 仓库搜索名称或描述匹配查询词的技能底层调用 GitHub Code Search API以filename:SKILL.md为固定条件检索。实现位于 pkg/cmd/skills/search/search.go--limit短参-L默认 15--page默认 1--owner将结果限定到指定用户或组织源码中以user:owner修饰查询--json支持六个字段repo、skillName、namespace、description、stars、path见 SkillSearchFields。排序与去重的源码细节。搜索结果并非直接返回而是经过多轮处理searchRun先按相关性预排序再截断工作集、并发抓取每个技能的 frontmatter 描述与仓库 star 数做富化然后过滤、再排序最后按技能名去重。评分函数 relevanceScore 的权重设计是信号分值技能名与查询词完全相等含连字符归一化3000技能名包含查询词1000namespace 包含查询词500描述包含查询词100仓库 star 数√n × 30此外deduplicateByName 对同名技能最多保留 3 条防止聚合类仓库照搬热门技能刷屏。多词查询还会自动补发一次连字符形式的检索如输入 mcp apps 时同时搜 mcp-apps。交互模式下搜索结果会进入多选器可直接选择技能并链式调用gh skill install完成安装。三、安装前预览gh skill previewgh skill preview owner/repo skill-name gh skill preview owner/repo skill-namev1.2.0 # 固定某个版本preview从仓库拉取技能文件并在终端渲染SKILL.md不安装任何东西先打印技能目录的文件树再输出渲染后的正文YAML frontmatter 会被剥离后按 Markdown 渲染。交互运行时若技能包含脚本、参考资料等附加文件还会弹出文件选择器逐个浏览。实现见 pkg/cmd/skills/preview/preview.go版本语法在技能名后追加VERSION版本可解析为 git tag、分支或 commit SHApreview.go 文档说明批量限制非交互模式下额外文件最多渲染 20 个、总量 512KB超出部分跳过renderAllFiles与 install 相同支持--allow-hidden-dirs来纳入.claude/skills/等点目录中的技能。四、安装gh skill installgh skill install owner/repo skill-name gh skill install owner/repo skill-namev1.2.0 gh skill install owner/repo skills/scope/skill-name # 精确路径最快 gh skill install ./local-skills-repo --from-localowner/repo与skill-name都是必填项交互模式下可改为提示选择。核心参数定义于 install.go参数说明--agent id目标 Agent 宿主如github-copilot、claude-code、cursor、codex、gemini-cli可重复指定多个非交互模式默认github-copilot。作为 Agent 使用时应知道自己是哪个宿主据此显式设置--scope project\|userproject默认写入当前 git 仓库内user写入主目录、全局生效--pin ref固定到 tag、分支或 commit SHA。与--from-local及内联version语法互斥--allow-hidden-dirs同时发现.claude/skills/等点目录下的技能有被他人内容污染的风险非必要不用--force-f覆盖已存在的安装--dir指定自定义目录覆盖--agent与--scope--all安装仓库中发现的全部技能不与技能名参数同用--from-local把参数当作本地目录路径安装文件被复制而非符号链接并在 frontmatter 注入本地路径追踪元数据版本解析顺序。当技能名不带版本时CLI 按以下优先级解析install.go 帮助文本 与 discovery.ResolveRef 一致仓库中最新的带 tag 的 release默认分支 HEAD。需要特别注意的是只有确实没有 release404才会回退到默认分支403、500、网络错误等会直接报错防止静默使用了意外的 ref。显式版本则先按分支、再按 tag、最后按 commit SHA 解析resolveExplicitRef。路径式安装的加速原理。技能名既可以是名称、命名空间名author/skill也可以是仓库内精确路径如skills/author/skill、packages/agent-skills/code-review或以SKILL.md结尾的任意路径。当传入精确路径时installRun 走discovery.DiscoverSkillByPath直接取单个 blob避免对整个仓库 git tree 的完整遍历——在大仓库中这是显著的性能优化源码注释中明确将其标注为 Performance tip。多 Agent 共享目录。从 internal/skills/registry/registry.go 可以看到DefaultAgentID为github-copilot而sharedProjectSkillsDir为.agents/skills。GitHub Copilot、Cursor、Codex、Gemini CLI、Antigravity、Amp、Cline、OpenCode、Warp 等多个宿主在 project 作用域下共用.agents/skills目录如果一次选择多个解析到同一目标的宿主每个技能只会写入一次buildInstallPlans按目标目录聚合安装计划。各宿主的 project/user 目录映射表就维护在Agents变量中例如 Claude Code 的 project 与 user 目录都是.claude/skills。安装后的元数据注入。安装完成后CLI 会向SKILL.md的 frontmatter 注入来源追踪元数据包括metadata.github-repo、metadata.github-tree-sha安装时的目录树 SHA、metadata.github-pinned、metadata.github-path等键。接受性测试 acceptance/testdata/skills/skills-install.txtar 验证了这一点安装后文件里能 grep 到github-repo与github-tree-sha且锁文件$HOME/.agents/.skill-lock.json被写入并记录了技能条目。正是这些元数据让后续的gh skill update能够检测变更、完成自更新。另外源码中还实现了上游溯源机制若被安装技能的 frontmatter 指向了另一个原始来源仓库re-published 场景CLI 会记录skill_upstream_redirect事件并自动改为从上游安装--upstream标志可显式启用该行为installRun。五、更新gh skill updategh skill update --all # 更新所有已安装技能 gh skill update skill # 更新单个 gh skill update skill --force gh skill update --unpin # 解除 pin 并移到最新版实现见 pkg/cmd/skills/update/update.go要点自动扫描所有已知 Agent 宿主目录Copilot、Claude、Cursor、Gemini 等的 project 与 user 两种作用域共享目录只扫一次scanAllAgents更新判据是目录树 SHA 对比从本地SKILL.mdfrontmatter 读出github-tree-sha与远端重新发现的结果比较不同才更新以--pin安装的技能默认跳过并打印提示用--unpin清除 pin 值后才会参与更新--force即使远端与本地 SHA 一致也强制重新下载会用原始内容覆盖本地改动的文件但不会删除本地额外新增的文件--dry-run只报告可用更新不修改任何文件。原子化更新机制值得单独一提。updateSkillInPlace 先把新版本装到与技能目录同文件系统的 staging 临时目录再通过 swapDirectoryContents 把旧内容移入备份目录、新内容原子 rename 进来任一步失败则从备份还原保证既有技能目录的 inode 不变符号链接、挂载等外部引用持续有效失败时原有内容也完整保留。六、发布gh skill publish发布会把仓库变成一个可被搜索发现技能源。技能按以下约定被发现与 install 完全一致见 publish.go 帮助文本skills/name/SKILL.mdskills/scope/name/SKILL.mdname/SKILL.md仓库根级plugins/scope/skills/name/SKILL.md每个SKILL.md需要 YAML frontmatter--- name: my-skill # 必须等于目录名 description: One sentence... # 必填推荐不超过 1024 字符 license: MIT # 可选但推荐 ---校验、然后发布gh skill publish --dry-run # 仅校验不发布 gh skill publish --dry-run ./path/to/repo # 校验指定目录 gh skill publish --fix # 自动剥离安装元数据 gh skill publish --tag v1.0.0 # 非交互发布 gh skill publish # 交互式发布流程--fix与--dry-run互斥publish.go 中的 MutuallyExclusive 校验。--fix只重写安装时注入的metadata.github-*键、不执行发布修复后应提交结果并重新运行 publish。源码中的校验清单publishRun比帮助文档更细name必填且必须与目录名一致名称须符合 agentskills.io 严格命名规范——小写字母数字加连字符、不以连字符开头/结尾正则见 discovery.godescription必填超过 1024 字符给出 warningallowed-tools必须是空格分隔的字符串而非数组存在未剥离的metadata.github-*安装元数据时报 error 并提示用--fix缺少推荐的license字段、正文超过 500 行影响 Agent 上下文效率给出 warning仓库中若存在已安装技能目录如.claude/且未加入.gitignore会警告可能把他人内容一并发布出去。发布流程四步对应 runPublishRelease为仓库添加agent-skillstopic搜索可发现的前提使用--tag指定的 tag或在 TTY 下交互式询问建议 semver源码会用 suggestNextTag 基于最新 tag 自动递增 patch 版本自动推送未推送的提交与gh pr create的行为一致ensurePushed创建带自动生成的 release notes 的 GitHub release。脚本化使用时务必传--tag否则会落入交互流程而失败。源码中还内置了若干仓库安全体检非阻塞的 warning/info是否启用 immutable releases、tag 保护 ruleset 是否缺失、secret scanning 及其 push protection 是否开启、技能含代码/依赖清单时 code scanning 与 Dependabot 是否配置等checkSecuritySettings、checkTagProtection。七、Agent 自我管理模式对于让 Agent 自我管理技能的场景skills/gh-skill/SKILL.md 给出的合理闭环是gh skill search topic --json skillName,repo,namespace发现候选技能非交互、可解析输出gh skill preview repo skill审查SKILL.md内容gh skill install repo skill --agent host --pin ref做可复现安装——注意这里显式指定--agentAgent 应知道自己是哪个宿主并用--pin固定版本定期执行gh skill update --all保持技能集刷新。配合第四节提到的元数据注入机制这一闭环完全不需要人工维护安装时写入的来源与 tree SHA 信息既是更新检测的依据也是溯源审计的基础。八、适用前提与限制功能状态skill命令族整体标注 preview帮助文本明确可能在不另行通知的情况下变化主机限制安装、搜索、预览路径都会先做source.ValidateSupportedHost校验远端操作面向受支持的 GitHub 主机本地目录安装走--from-local且--from-local与--pin、--upstream互斥大仓库限制当仓库 git tree 超过 GitHub API 截断上限时完整发现会返回 TreeTooLarge 错误并提示改用路径式安装install.go点目录技能.claude/skills/等隐藏目录中的技能默认被排除且被提示可能是其他发布者的复制品需--allow-hidden-dirs显式纳入验证入口仓库的 acceptance/testdata/skills/ 目录下有整套 txtar 验收测试安装、预览、发布、更新等场景可作为行为基线参考。【免费下载链接】cliGitHub’s official command line tool项目地址: https://gitcode.com/GitHub_Trending/cli/cli创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考