如何为go-skills市场编写你自己的Agent Skill：模板、清单契约与CI校验全流程指南

go-skills 是由 spf13（Cobra、Viper 作者）维护的 Go Agent Skill 市场（marketplace），目前收录go、cobra-viper、go-release等 6 个技能。本文为新手写出一份可上架的 Agent Skill 的完整指南：从复制模板脚手架、遵守plugin.json清单契约，到本地跑通全部 CI 校验，每一步都有对应文件路径可查。

一、先搞清楚：一个 Skill 由哪三部分组成 🧩

在 go-skills 仓库中，每个技能 = 仓库根目录下的一个目录，目录名即技能名：

<your-skill>/ SKILL.md # 技能正文，含 YAML frontmatter（name + description） .claude-plugin/ plugin.json # 展示元数据的"唯一事实来源"

三个关键文件各司其职：

• SKILL.md：技能的"大脑"，被加载进模型上下文，决定技能如何触发、教什么。
• plugin.json：展示元数据（displayName、version、author、keywords 等）。
• marketplace.json：市场目录清单，列出全部技能，每个条目只有 4 个键。

templates/目录是脚手架而不是技能，不参与目录与条目的一一对应检查。

二、复制模板脚手架：最快起步方式 🚀

仓库已内置现成模板，两步即可起步：

cp -r templates/skill your-skill

1. 编辑 templates/skill/SKILL.md 的复制产物：先写 frontmatter 的name与description，再填正文（When this applies / Rules / Anti-patterns 三段式结构）。
2. 编辑.claude-plugin/plugin.json：把模板里的占位version: 0.0.0改成市场当前版本号——CI 会拒绝任何落后于最新v*tag 的版本号。
3. 把 templates/skill/marketplace-entry.json 的条目并入.claude-plugin/marketplace.json，替换全部占位符，只保留 4 个键：

{ "name": "your-skill", "source": "./your-skill", "category": "development", "tags": ["go"] }

💡 命名一致性是铁律：name必须三处相等——目录名 =plugin.json的name= frontmatter 的name，不一致 CI 直接报错。

三、写好 SKILL.md 的 frontmatter：触发质量的核心

frontmatter 只有两个必填字段，但要求不低：

description是模型自动触发技能的依据。参考 go/SKILL.md 的写法——它点名了具体场景（"writing, reviewing, debugging Go code"）、文件类型（go.mod、.go文件）和用户口头禅（"even if they don't ask for idiomatic code"），这就是"触发描述"的标准范式。

四、清单契约：为什么 marketplace 条目只有 4 个键 🔐

这是 go-skills 最容易踩坑的设计决策：

• plugin.json是唯一事实来源：description、version、author、homepage、license、keywords一律不写进marketplace.json条目里。Claude Code 会直接从plugin.json读取，重复的副本迟早会"漂移失同步"。
• tags必须与keywords完全相等：是同一份列表的两种写法，两边都不能有重复项。
• source必须写成./<目录名>：例如{"name": "go", "source": "./go", ...}。

对照 go/.claude-plugin/plugin.json 与 marketplace.json 中go的条目，即可看到"重字段在 plugin.json、轻条目在 marketplace.json"的标准形态。

分类只允许三选一

category必须且只能取以下之一，按"技能教什么"来选：

五、版本与发布：单一版本、打 tag、补 CHANGELOG

go-skills 采用全市场单一版本号，6 个插件同步升版，没有按技能单独的版本号。发布三部曲：

1. 把每个<skill>/.claude-plugin/plugin.json的version改成同一个新值；
2. 在 CHANGELOG.md 增加对应条目（必须匹配## [X.Y.Z]格式，CI 用正则校验）；
3. 在该提交上创建带注释的 tagvX.Y.Z。

CI 会断言：所有版本号一致、tag 指向的提交版本与vX.Y.Z完全匹配、版本号不落后于最新 tag、CHANGELOG 有条目。所以"先合并升版 PR、后打 tag"是合法的——被打 tag 的提交才是必须精确匹配的那个。

六、特色规则：Go 版本保鲜检查 📅

如果你的技能教 Go 语言，可以在description正文中声明覆盖版本，字面形式固定为：

current through Go X.Y

例如 go/SKILL.md 的 frontmatter 就写着current through Go 1.27。仓库内置的定时工作流 .github/workflows/go-release-check.yml 每月 1 号（以及手动触发时）从官方发布源抓取最新稳定版，运行 .github/scripts/check_go_release.py 比对：

• 没声明的技能直接通过——声明是可选的；
• 声明了就必须与最新稳定版一致，落后会点名"技能名 + 声明版本 + 实际版本"报红；
• 声明只允许在加入该版本特性的同一变更中升级，不许提前抢跑；
• 已声明的技能不允许悄悄删除声明，检查脚本中的CLAIMING_SKILLS常量就是这份"已知声明者"基线。

七、本地跑通 CI：提交前必做的 4 个检查 ✅

CONTRIBUTING.md 承诺：文档里写的每条规则，CI 都会检查。提交前先本地自测：

# 0. 准备依赖 python3 -m pip install --user jsonschema # 1. 清单对 schemastore 公共 schema 校验 python3 .github/scripts/validate_manifests.py # 2. 跨文件不变量（本文所有契约规则都在这里） python3 .github/scripts/check_invariants.py # 3. Go 版本保鲜（把抓取到的最新稳定版作为参数传入） python3 .github/scripts/check_go_release.py "1.27" # 4. README 与 CONTRIBUTING 的链接可达性 lychee README.md CONTRIBUTING.md

这些检查对应推送和 PR 时自动运行的工作流 .github/workflows/validate.yml，其中check_invariants.py还会额外校验：README 的技能表格必须每个技能恰好出现一行，且链接指向./<skill>/SKILL.md——新技能别忘了在 README.md 表格里加行。

八、新增 Skill 全流程清单（可直接照抄）

九、常见失败与速查 💊

• version 0.0.0被拒：模板占位版本落后于最新 tag，改成市场当前版本即可；
• tags != keywords：两边是同一份列表，逐字对齐且去重；
• README 表格报错：表格行必须"技能名 ↔ 目录名"一一对应，每个技能恰好一行；
• description 太短：不足 40 字符会被check_invariants.py明确点名，参考 go/SKILL.md 的长描述写法；
• 多写了一个键：marketplace 条目多出description等字段即失败——"条目键必须恰好是这 4 个"。

掌握"模板起步 → 契约对齐 → 本地校验"这条主线，你的 Agent Skill 就能像仓库里现存的 6 个技能一样，稳定地通过 go-skills 市场的 CI 门槛并上架发布。