[玩转大模型] 第十篇：开源自己的 Skill——从「我自己能用」到「别人能装上就跑」，中间到底差哪五件事

💡前九篇一路写下来，我自己的 Skill 已经攒到十二个：写博客的、出封面的、发草稿的、跑每日打卡的、把 CSDN 同步到公众号的。它们在我这台机器上跑得很好，好到我一度以为"这就是可以拿出去的东西了"。

然后我做了一件很简单的事：把它们复制到一个干净的目录，用另一个账号、另一台机器的方式装上去。结果一半直接没被识别，识别出来的那几个，有两个装完就把我内置的同名 Skill 顶掉了，还有一个的执行脚本报了缺依赖。

这件事让我意识到，"我能用"和"别人能装上就跑"之间隔着一整套工程要求——而这套要求，规范里其实写得明明白白，只是我从来没按它检查过自己的东西。

所以这一篇就干一件事：把"开源一个 Skill"拆成可以逐条打勾的动作。我先把自己那个不合格的仓库摊开给大家看，再讲规范卡了哪些硬线，然后是从自用变成公开要补的五件事、许可证怎么选、发到哪里，最后是发出去之后真正麻烦的部分。

一、先摊开我自己的仓库：体检结果很难看

这一章回答：一个"我自己用得很爽"的 Skill 仓库，按公开标准检查会漏在哪。

我把自己那个 skills 镜像目录整个扫了一遍，逐个读 frontmatter、数正文行数、看子目录。结果如下（数字都是脚本实测的，不是我估的）：

三个最要命的问题：

一、目录名和name不一致。gen-blog这个目录里声明的 name 是tech-blog-writer-260921bak，img-creator声明的是prism-studio，skill-nexus干脆没有 name 字段。这三个 Skill 在别人机器上要么装不上，要么装上了但按目录名调不到。我自己一直没发现，因为在我这台机器上我是靠"记得它在哪"来用的，不是靠 name 检索的。

二、Skill 里套 Skill。img-creator/下面直接放着一个完整的blog-cover-studio/和skill-style-studio/，各自带自己的 SKILL.md；doc-ink/下面放着一个tech-blog-writer/和一个tech-blog-writer-260921bak/。这是我图省事的产物——复制目录时把依赖一起拷了。公开出去，别人的加载器会看见一堆来源不明的重复 Skill。

三、备份文件当源码管。gen-blog/SKILL 2.0.md这个文件名（中间那个空格是访达"拷贝"留下的）就躺在仓库里，tech-blog-writer-260921bak整个目录也是。它们既不是版本也不是文档，只是我没清理的垃圾。

还有两个"缺失项"同样说明问题：整个目录树里LICENSE 只有 1 个，而且藏在doc-ink/的子目录里；CHANGELOG 一个都没有；git 历史是这样的：

ff39b85 vault backup: 2026-09-28 00:06:30 c1adecd vault backup: 2026-09-27 00:11:18 5eecf52 vault backup: 2026-09-26 00:09:35

全是笔记软件每天自动打的备份点。也就是说：我没有任何一次是"因为改了什么而提交"的。别人拿到这份东西，无法知道哪个版本能配哪版脚本，也无法回滚。

体检图我画成一张，红黄绿一目了然：

二、规范到底卡了什么：三条硬线加一条建议线

这一章回答：Agent Skills 的开放规范里，哪些是"超了就废"的硬限制，哪些只是建议。

第八篇我讲过 Skill 的三级披露，那一节是为"要不要选 Skill"服务；这一节是为"怎么写才不会翻车"服务，所以数字要抠得更细。以下按 agentskills.io 的 specification 页核对（核实时间 2026-09-29）：

这里有一个坑我踩得莫名其妙：我想在 frontmatter 里加version，结果校验器不认。后来才搞清楚——规范里没有顶层version字段，官方的做法是把版本号塞进可选的metadata（一个字符串到字符串的映射）里。我自己的opcs-order-assistant就是因为同时写了version和identity两个规范外的顶层键，才在另一个工具上被警告。规范允许扩展，但你得知道哪些字段是标准会读的、哪些只是写给自己看的。

我这边description实测最长 597 字符（blog-cover-studio），全部在 1024 以内，这项是合格的。不合格的是正文行数：tech-blog-writer1063 行、gen-blog912 行，是建议上限的两倍。

为什么这条值得当真？因为 Skill 的成本模型是分层的：

L1 name + description 常驻，约 100 token 量级 L2 SKILL.md 正文 命中才加载，规范建议 < 5000 token L3 scripts/ references/ 正文指到哪才读哪

规范自己给这三级的叫法是Metadata / Instructions / Resources，对应的阶段叫Discovery / Activation / Execution（发现、激活、执行）。我上面用 L1/L2/L3 只是为了说话省事，你去查文档要用它那套词。另外它还有一条容易被忽略的约定：引用只往下一层，references/a.md可以，a.md再去指b.md就不建议了——层级一深，模型很可能读到一半就不追了。

我那个 1063 行的tech-blog-writer，等于把 L2 当成 L3 用：只要它被命中，一整篇写作规范就全量进上下文，而我实际需要的可能只是其中"结尾只用一段"那一条。

拆法其实很机械，我自己动手改了一遍：

拆前：SKILL.md 1063 行 （全部规则平铺） 拆后：SKILL.md ~180 行 （触发条件 + 决策路径 + "去哪读"） references/format.md 一级标题 / 表格 / 代码块规范 references/qa.md 问答体与示例写法 references/meta.md MetaData 与 BLOG_COVER 注释块约定

关键不在"拆"这个动作，在于正文里要留下明确的指路句——“写结尾时读 references/meta.md”。模型不会因为文件存在就去读，它只会被你指过去。

三级各自花多少、超出的部分往哪挪，一张图说得完：

还有一点容易被忽略：description是唯一的召回入口。它不是给人看的简介，是给检索用的查询命中串。我改过一次实测很明显的例子——

前者我写了"什么时候用"的语义务力，模型经常在该用的时候没想起它；后者把任务动词和文体名词都堆进去，命中率立刻稳了。这不是玄学，检索就是在比这些词。

三、从"我能跑"到"别人能装"：中间那五件事

这一章回答：自用和公开之间，具体差哪五道工程要求。

我把这五件事按"缺了它别人会怎么失败"来排，不按难度排。

第一件：可复现。我的blog-cover-studio依赖一个template.json和 7 个 Python 脚本，还依赖系统里有/System/Library/Fonts/STHeiti Medium.ttc这个字体。前两项我拷了，字体没写。结果在另一台机器上，中文全部渲染成豆腐块，而报错信息只说"字体加载失败"，不会告诉你要装哪个字体。

所以公开版本必须在compatibility里写清运行前提，而且字体、二进制、系统版本这类"环境自带的东西"要一并打包或给出替代路径。我自己的处理是把必需字体换成"找不到就退回系统默认并明确告警"，而不是静默出豆腐。

第二件：依赖声明。我这边其实有两种做法并存：opcs-order-assistant/里有一个skill-dependencies.json，gen-blog/里有一个.codex-plugin/plugin.json。这两个都是我在不同时期试的东西，格式互不兼容。公开之前必须收敛成一种，并且在 README 里说明"这个 Skill 依赖另一个 Skill 时怎么装"。

Skill 套 Skill 那种物理拷贝不算依赖声明，只能算复制粘贴。

第三件：边界与安全。这条最容易被跳过，因为它不影响"能不能跑"。我的打卡类 Skill 会驱动浏览器去点按钮、会往外部站点发帖。自用我知道分寸，公开之后别人不知道。所以公开版本里必须写死：

只读什么 --> 哪些站点、哪些页面只允许看 可写什么 --> 允许提交的动作清单，一条一条列 绝不做 --> 删除、支付、发消息给第三方、改权限 凭据怎么来 --> 只从用户自己的配置读；仓库里一个真实 token 都不许有

最后一条我是有教训的：早先有一篇技术稿里我直接把内网数据库地址和口令写进了正文，本地自用没人看见，发出去就是事故。公开之前要跑一遍扫描，扫 IP、token、口令、邮箱、私钥头，这类字段。注释块也不是保险箱——HTML 注释在平台上会被渲染器丢掉，但仓库里的原文谁都翻得到。

第四件：版本。没有 CHANGELOG、没有 tag、提交信息全是自动备份，等于告诉别人"这份东西没有版本可言"。我现在的要求很低，但很硬：

最后一行是我这轮才补上的。官方规范自带一个校验命令，形态是skills-ref validate ./my-skill，它能查出字段缺失、命名不合规这类问题；而 Anthropic 那个官方插件仓库的 CI 里有九条 workflow，其中三条正好对应我这一节：校验 frontmatter、校验许可证、扫描插件内容。也就是说，我上面这三个坑（字段、许可、来源）是官方认为值得用自动化拦住的，不是我个人洁癖。我的镜像仓库里那条 CI 配置文件从头到尾被注释掉了——它原本是用来构建一个 Go 工具的，跟 Skill 一点关系没有。

第五件：文档。README 不是 SKILL.md 的复制。SKILL.md 是给模型读的指令，README 是给人读的说明。至少要四段：它解决什么问题（一句话 + 一个真实例子）、怎么装、装完怎么验证成功、什么情况下不该用它。

第四段最值钱。我自己写 Skill 时最常见的误用就是"它明明不该被触发却触发了"，而公开的东西如果不写清不适用场景，别人只会来问你是不是坏了。

这五件事补完之后，仓库的形状大概是这样：

my-skill/ ├── SKILL.md frontmatter：name / description / compatibility ├── README.md 给人看：解决什么 · 怎么装 · 怎么验 · 何时别用 ├── LICENSE 一份，放在根 ├── CHANGELOG.md 版本历史 ├── references/ L3 深水区，正文里点名指路 ├── scripts/ 可执行部分，只读/可写边界写在文件头 └── assets/ 模板、字体、样例输入输出

四、LICENSE 不是走过场：代码类和知识类要分开选

这一章回答：一个 Skill 里同时有文本和脚本，许可证该怎么定。

先说我自己踩的坑：我那份唯一的 LICENSE 藏在doc-ink/的子目录里，根目录没有。这意味着从仓库外面看，整个项目是"未声明许可"的——默认状态是保留所有权利，别人想用一个都不敢用。放错位置等于没放。

而且许可这件事在 Skill 上有两个位置：仓库根目录的LICENSE文件，和 frontmatter 里那个可选的license字段。前者管法律，后者管机器读——别人扫你的仓库时，看的是字段。我一开始只写了文件没写字段，反过来也犯过一次：opcs-order-assistant的 frontmatter 里写了license: Proprietary，仓库里却没有任何对应的许可文本，等于声明了一句空话。

比较有意思的是，连官方仓库都在玩这套分层。anthropics/skills这个仓库根目录没有 LICENSE 文件，README 里说"本仓库中许多 Skill 是开源的（Apache 2.0）“，而它的docx、pdf、pptx、xlsx那几个文档处理 Skill 写的是license: Proprietary，属于source-available（源码可见）而不是 open source（开源）。这个区分很重要：别人能看到你的代码，不等于有权使用、修改、再分发。我原来以为"公开仓库 = 开源”，官方这份仓库就是最好的反例——它同时也是下一篇讲"怎么卖"时会用到的那个手法：同一份东西，示例部分放开，能力部分收紧。

然后是选择。我的判断标准只有一条：这个 Skill 的价值主要在"文字"还是在"能跑的东西"。

MIT 和 Apache-2.0 的差别，多数人记得"都很宽松"，但真正影响决策的是 Apache-2.0 多出来的两点：明确的专利授权（贡献者授予使用者专利许可，避免"代码给你了专利不给你"），以及NOTICE 文件的保留义务（下游必须带着声明走）。对个人 Skill 来说，前者是给你和使用者都上一道保险，后者是多维护一个文件的成本。

有一个不建议的做法我要点名：不要为了"看起来专业"而上 GPL。一个 Skill 的脚本经常会被别人复制进他自己的项目里，强 copyleft 会让企业用户直接放弃——他们不是不想用，是不想让自己的代码被传染。我如果要的是"很多人用"，就选宽松许可；要的是"必须回馈"，那也得先想清楚你要的这个"回馈"值不值得少了 90% 的用户。

五、发到哪里：四个渠道，门槛和回报完全不同

这一章回答：开源之后，除了自己的 GitHub 仓库，还能往哪放，各要付什么代价。

我按"从最省事到最费事"排：

安装这一步值得单独说。我自己在 Qoder 上装第三方 Skill 用的是社区 CLI，形如：

npx skills add <owner>/<repo> --skill <name> -g

它做的事就是把仓库里那个 Skill 目录拷进用户级的 skills 目录。这里有一个我踩过的坑值得所有作者注意：用户级目录里的同名 Skill 会顶掉内置的同名能力。也就是说，如果你的 Skill 起了一个太通用的名字（比如pdf、search、commit），别人装完之后行为变了，还以为是平台坏了。

所以命名这件事在公开时有了额外约束：要带辨识度，别抢通用词。我后来给自己的规则是"动词短语 + 领域限定"，例如把blog-cover-studio这种带工作室后缀的写法保留，而不再考虑cover这种单词。

渠道这一层，我核到的几个事实值得作者提前知道，因为它们决定了"曝光"到底是什么东西：

• 索引站的排名是按安装数排的，数据来自安装遥测，不是编辑推荐。这意味着头部效应极强：一个 Skill 的名字如果撞上了通用词，它会长期被前面那个压住。
• 索引站自己写了免责声明，大意是"我们无法保证列出的每一个 Skill 的质量与安全，安装前请自行审阅"。翻译过来就是：平台只负责被找到，不负责被信任——信任成本全在你这份仓库的 README、CI 和提交历史上。
• 有一种"打包"机制可以把公开 Skill 和私有文件混在一个包里，听起来很适合"开源一部分、留一部分卖"。但它的官方说明里明确写了：这种包只是不公开列出，并不做访问控制，而且不建议放密钥。也就是说，它是一个分发便利，不是一道权限墙，靠它收费是行不通的。
• 走平台官方目录那条路是有前置条件的，官方提交入口要求账号在付费套餐内；而"自建一个市场仓库"这条路反而没有门槛——放一个清单文件进仓库就算一个市场。

至于中文圈，我的判断要修正一句：目前动的不是第三方分发渠道，而是厂商自己发官方 Skill——比如知识星球这种内容平台已经放出了可安装的运营类 Skill。这决定了开源的回报形式——不是下载量，是别人愿不愿意给你提 Issue。

六、发出去之后：真正的成本从现在开始

这一章回答：开源一个 Skill 之后，哪些事情会持续吃你的时间，以及它带来的新风险面。

我一开始以为开源的难点在"整理干净"。做完发现那只是一次性成本，持续成本在这几处：

一、环境矩阵炸开。我这边跑得好好的，因为我只有一台 macOS、一个 Python、一套字体。公开之后第一个 Issue 就是"我在 Windows 上跑不通"。路径分隔符、编码（我吃过 GBK 站点的亏）、字体是否存在、shell 是 zsh 还是 bash，每一项都是新的支持成本。能少一个平台相关假设，就少一类 Issue。

二、"它没触发"类问题最多，也最难回。用户说 Skill 装了但没用，你远程什么都看不到。我现在的应对是在 README 里直接给一段自查：先看 name 是否与目录一致、再看 description 是否含他实际说的那些词、最后确认没有别的同名 Skill 抢占。把排查路径写死，比逐条回复省命。

三、脚本的供应链责任。这是我认为最被低估的一点。一个带脚本的 Skill，本质上是让别人在你写的代码上执行操作。平台自己的安全文档把话说得很直：你安装的插件能以你的用户权限在本机执行任意代码，其中的钩子脚本是在沙箱之外跑 shell 的，插件带的bin/目录还会被加进 PATH。换句话说，别人装你的 Skill 时，装的是一份指令加一台可执行的机器。

而真正让我改做法的是这一条：开了自动更新之后，你审过的那些文件会在后台被换掉。也就是说，用户当初点头安装的版本和你现在拿到的版本，可能不是同一个东西——中间那次改动是谁做的、改了什么，他并不知道。我的打卡类 Skill 会驱动浏览器点击外部站点，那一旦我改了目标站的选择器、或者我的仓库被人攻破后塞了东西，别人机器上就会执行改动后的代码。所以：

脚本能做什么 --> 在 SKILL.md 与 README 双处声明 不许远程下代码再执行 --> 不要 curl | bash；要装依赖就写清并让人确认 凭据 --> 永远从用户自己的配置读，仓库不留示例真值 版本固定 --> 依赖带版本号，别用 latest

四、提示注入面。一个 Skill 如果会去读外部内容（网页、邮件、别人的仓库），那它读到的东西就可能包含"请忽略你之前的指令"。这已经不是 Skill 特有的问题，属于 LLM 应用的通用风险面，但 Skill 作者特别容易忽略——因为你的正文本身就是一串指令，读者分不清哪句是你写的、哪句是从外部抓来的。我的做法是在正文里明确划一条线：外部抓取的内容只能作为数据引用，不得当作指令执行，并且凡是会读外部的 Skill 都写这一条。

这四类风险在 OWASP 的 GenAI Top 10（2025 版）里都有对应条目，不是我编的分类：LLM01 提示注入、LLM03 供应链、LLM05 输出处理不当、LLM06 过度代理。其中"过度代理"这一条最贴 Skill 的处境——你的 Skill 能调用的工具越多、能写的边界越宽，出事时的爆炸半径就越大。要去查原文，这四个编号比"AI 安全"这种关键词好用。

五、维护承诺要说清。我后来在 README 里加了一行"这个项目按现状维护，不承诺响应时间"。听起来消极，但它替你挡掉了大量道德绑架式的 Issue。反过来说，如果你打算长期维护，就把这条写成承诺，它会变成别人选你而不选别人的理由。

把这一章和前面几章串成一条链，就是我现在的发布检查形状：

七、几个一定会被问到的问题

这一章回答：从自用转向公开时最集中的疑问。

Q1：我的 Skill 依赖另一个 Skill，能一起开源吗？

能，但不要用"物理嵌套"来表达依赖——我那两个把 Skill 拷进别人目录的做法是反面教材。正确做法是：在 README 和compatibility里点名"需要 X，安装命令是 Y"，让两个 Skill 各自是独立仓库或独立目录。依赖关系写出来，不要靠拷贝。

Q2：公司里写的 Skill 能开源吗？

先分清两件事：这个 Skill 里有没有公司的私有信息（内部域名、接口、数据结构、真实凭据），以及它的产出归谁。第一个是纯技术问题，扫一遍就能确定；第二个不是——我在公司环境里写的东西，默认要按雇佣协议和 IP 归属条款处理，别自己判断。我的做法是先问，问不到结论就当不能开源，只写一个同主题、纯自证思路的公开版。

Q3：要不要把脚本一起开源？

要。只给 SKILL.md 而不给脚本，等于给了说明书不给机器——只要你的正文里提到scripts/xxx.py，别人拿不到就是跑不通。反过来也成立：如果你不打算开源脚本，那正文里就别引用它，把能力降级成纯指令版。

Q4：别人 fork 之后改了，我要不要合回来？

我的原则是：只合能复现问题的改动。fork 的价值不在代码本身，在于它暴露了你没想到的用法。我合过一个 fork 里加的路径处理，因为它同时修掉了三个我没收到的 Issue；我也拒过更"高级"的功能请求，因为它会让 Skill 在别的场景下更容易误触发。

Q5：开源了之后还能卖吗？

能，而且这是下一篇的主题。简单说一句结论：你一旦用 MIT 或 Apache 放出去，就收不回来了，所以"开源什么、留什么"必须在按下公开按钮之前想清楚，而不是之后。

最后总结

• 自用和公开之间差的不是质量，是"可复现"。我的仓库里最贵的三个问题——目录名和name不一致、Skill 里套 Skill、没有 LICENSE 和版本——全都是"我自己看不见"的问题。
• 规范的硬线只有三条：name≤ 64（且必须等于目录名）、description≤ 1024、compatibility≤ 500；正文 ≤ 500 行是建议线。超硬线会直接坏，超建议线是慢慢坏——每次命中都多烧一遍上下文。
• description是召回入口，不是简介。把用户真会说出的动词和名词写进去，比写得漂亮有用。
• 公开 ≠ 开源。仓库能被访问，只说明别人能看见；能不能用、能不能改、能不能拿去卖，取决于根目录那份 LICENSE 和 frontmatter 里的license字段。官方仓库自己都在做"示例开源、能力源码可见"的分层。
• 公开前要补的五件事：可复现、依赖声明、边界与安全、版本、文档。其中"边界与安全"决定你会不会成为别人的事故。
• 许可证按"价值在文字还是在代码"来选，纯文本类 CC BY 或 MIT，带脚本的 Apache-2.0，混合就分开声明；别为了好看上 GPL。
• 开源的回报不是下载量，是 Issue。如果你不想承担持续支持成本，就在 README 里把维护承诺写清楚，这比事后解释省力得多。
• 对后端 / 架构方向的开发者，我更想说的一句：一个能公开的 Skill 仓库，和一个能上线的服务，检查项其实高度重合——接口契约（frontmatter）、依赖管理（compatibility）、可观测性（README 的自查段）、供应链安全（脚本边界）。你以前学的东西一条都没浪费，只是执行者从服务换成了模型。

参考资料 & 致谢

[1] Agent Skills - 开放规范 Specification
[2] Agent Skills - 概览与三级披露
[3] Agent Skills - 脚本使用规范（依赖声明与安全默认值）
[4] anthropics/skills - 官方 Skill 仓库（开源与 source-available 分层的实例）
[5] 插件安全与信任 - 官方文档（任意代码执行、自动更新风险）
[6] skills.sh - 社区 Skill 索引站文档（安装命令、免责声明、Packs）
[7] Choose a License - 许可证对比与选择
[8] Apache Software Foundation - Apache-2.0 许可证原文
[9] Creative Commons - CC BY 4.0 许可证说明
[10] OWASP GenAI Redesign - LLM Top 10 2025（LLM01 / LLM03 / LLM05 / LLM06）