一、发布前要过七条

七条检查，前四条是硬伤，后三条是习惯问题。

第三条容易被忽略：描述是常驻的，每次对话都要占位置。写长了每次都在付费。 第四条最要命，也最容易犯——调试的时候随手写一把测试密钥，发的时候就忘了。

二、撞一遍：五条不过

拿一份「写完就发」的包去撞这七条，五条不过。

五条里有两条是发出去会出事的：密钥和绝对路径。另外三条只是不好用。 修法都很简单：描述砍到两句、删密钥、路径改相对、正文加一句「README 里写了安装步骤」、清缓存。 改完再撞，七条全过。整个过程不到十分钟。

三、密钥这件事要说三遍

把密钥写进文件，再删掉那一行，不算完。 git 的历史里还在。任何人 clone 之后翻 log 都能拿到，而且它会在你的仓库里躺很久。 正确的处理顺序是三步：先吊销那把钥匙、再重写历史、最后才发。 顺序不能反。先清历史后吊销，中间那段时间它还是有效的。 更省事的做法是从一开始就不写：密钥只从环境变量读，文件里只写变量名。

四、三种发布范围

范围越大，要求越高。个人自用能忍的毛病，社区发布一条都不能有。 团队分享有一个额外要求：别放个人偏好。「我不喜欢用冒号」这种话不要写进去。 社区发布还要想一件事：别人会拿它干你没想过的活。边界那一节写清楚，是保护别人也是保护你。

五、名字和描述，是别人见到你的第一眼

后半句最常被漏。它决定别人在什么场景下会想起你——也就是会不会被选中。 「带用户的说法」的意思是：写用户嘴里会说的话，不写行业术语。 用户会说「帮我整理个纪要」，不会说「执行纪要生成任务」。后半句要照着前一种写。

六、发布之后还会变

「改输出格式」是最容易忘的破坏性改动。下游可能正照着你上一版的形状写解析器。 第 5 章那条流水线就是例子：writer 技能改了输出形状，polish 的解析器直接崩。 所以改格式的时候，先问一句：有没有别的东西正在读我的输出。

七、本章小结

第 6 章是一条完整的生产线，五步。 需求：把痛点写成一句话，填满六格。缺哪格，技能就缺哪段。 设计：四招——记踩坑点、可容错、可扩展、跨对话记忆。核心是不静默算错。 实现：你决策、它执行。分三步构建，每步只盯一件事。 测试：定标准、跑两版、只改丢分那一项。改一处才能归因。 上线：过七条检查，按范围决定要求高低。密钥和绝对路径一条都不能有。 五步里最容易被跳过的是第一步和第四步：想不清楚就开始写，写完不测就发出去。 下一章换个方式收尾：不按流程讲，按时间讲——一个数据分析技能的四次迭代。

八、动手 Demo：发布前扫一遍，五个问题一次报全

这一段写七条检查，拿一份「写完就发」的包去撞，再改一遍重撞。 七条都是字符串层面的判断，扫一遍不到一秒。

CHECK = [('frontmatter 有 name', lambda fm, b: 'name:' in fm),
         ('没有明文密钥', lambda fm, b: not re.search(r'sk-[A-Za-z0-9-]{8,}', fm + b)),
         ('没有绝对路径', lambda fm, b: not re.search(r'[A-Za-z]:\\|/Users/', fm + b)),
         ('正文提到 README', lambda fm, b: 'README' in b),
         ('没有缓存目录', lambda fm, b: '__pycache__' not in fm + b)]

bad = [a for a, fn in CHECK if not fn(BAD, BAD_BODY)]
print(len(bad), bad)

实跑输出：

--------------------------------------------------------------------
发布前扫一遍，5 个问题一次报全
--------------------------------------------------------------------


  ① 发布前要过七条
  --------------------------------------------------------------------
| 序 | 检查项 |
|:---:|---|
| 1 | frontmatter 有 name |
| 2 | frontmatter 有 description |
| 3 | description 不超过 100 字 |
| 4 | 没有明文密钥 |
| 5 | 没有绝对路径 |
| 6 | 正文提到 README |
| 7 | 没有缓存目录 |

  七条里前四条是硬伤，后三条是习惯问题。硬伤会让别人装不上或者不安全。

  ② 拿一份没整理过的包去撞
  --------------------------------------------------------------------
| 序 | 检查项 | 结果 |
|:---:|---|:---:|
| 1 | frontmatter 有 name | 过 |
| 2 | frontmatter 有 description | 过 |
| 3 | description 不超过 100 字 | 不过 |
| 4 | 没有明文密钥 | 不过 |
| 5 | 没有绝对路径 | 不过 |
| 6 | 正文提到 README | 不过 |
| 7 | 没有缓存目录 | 不过 |

  七条里 5 条不过。
  不过的分别是：description 不超过 100 字、没有明文密钥、没有绝对路径、正文提到 README、
  没有缓存目录。
  ! 第四条最容易漏：密钥写进文件再删掉也不算完，git 历史里还在。

  ③ 修一遍，再撞
  --------------------------------------------------------------------
| 序 | 检查项 | 结果 |
|:---:|---|:---:|
| 1 | frontmatter 有 name | 过 |
| 2 | frontmatter 有 description | 过 |
| 3 | description 不超过 100 字 | 过 |
| 4 | 没有明文密钥 | 过 |
| 5 | 没有绝对路径 | 过 |
| 6 | 正文提到 README | 过 |
| 7 | 没有缓存目录 | 过 |

  七条全过。改动是：描述砍短、删掉密钥、路径改成相对、补 README、清缓存。

  ④ 三种发布范围，做法不一样
  --------------------------------------------------------------------
| 范围 | 放哪 | 要注意什么 |
|---|---|---|
| 个人自用 | ~/.claude/skills/ | 只有你，改完就是最新 |
| 团队分享 | 项目仓库 .claude/skills/ | 跟着代码走，谁拉谁有 |
| 社区发布 | 公开仓库加 LICENSE | 陌生人也会装，得写清能做什么 |

  范围越大，要求越高。个人自用能忍的毛病，社区发布一条都不能有。

  ⑤ 名字和描述，是别人见到你的第一眼
  --------------------------------------------------------------------
| 写哪 | 怎么定 | 例子 |
|---|---|---|
| 名字 | 小写、连字符、不加版本号 | minutes，不要 Minutes-v2 |
| 描述前半句 | 做什么，一句话 | 把会议转写稿整理成四段纪要。 |
| 描述后半句 | 什么时候用，带用户的说法 | 用户要给纪要、要列待办时使用。 |

  后半句最常被漏。它决定别人在什么场景下会想起你——也就是会不会被选中。

  ⑥ 发布之后还会变
  --------------------------------------------------------------------
| 改动 | 怎么做 | 对别人的影响 |
|---|---|---|
| 加功能 | 加一节，不影响旧用法 | 旧用户无感 |
| 改输出格式 | 等于破坏性改动 | 写进 CHANGELOG 提醒 |
| 删功能 | 尽量别删，标成废弃 | 删了别人会坏 |

  「改输出格式」是破坏性改动，这一条最容易忘——下游可能正照着你上一版的形状写解析器。

第一段七条检查，前四条是硬伤，后三条是习惯问题。 第二段拿一份没整理过的包去撞：五条不过。 不过的五条是：描述太长、写死密钥、绝对路径、没提 README、带缓存目录。 第三段修一遍重撞，七条全过。整个过程不到十分钟。 第四段讲三种发布范围：个人自用、团队分享、社区发布，范围越大要求越高。 第五段讲名字与描述：描述后半句写用户嘴里的说法，不写行业术语。 第六段讲发布之后的变动：「改输出格式」是破坏性改动，最容易忘。

30 秒实验

1. 拿你现有的技能包跑一遍这七条，看有几条不过。密钥和绝对路径先修。
2. 把你的 description 砍到两句：前半句做什么，后半句什么时候用。
3. 给你的技能加一个 CHANGELOG，写下第一行「v1 初始版本」。

常见误区

1. 把密钥删掉就算完。git 历史里还在。先吊销，再重写历史，最后才发。 顺序反了中间那段时间它还有效。
2. 描述写成长篇介绍。描述是常驻的，每次对话都占位置。两句够了：做什么、什么时候用。
3. 直接改输出格式不通知。 下游可能正照着你上一版的形状写解析器，一改就崩，而且崩的地方离你很远。

第 6 章完。下一章换一种讲法：不按流程，按时间——一个数据分析技能的四次迭代。

• ☐ （本篇完，下一篇 7.1 V1 基础版：先跑通再说）

相关笔记

• 测试：验证技能好不好用
• 安全是头等大事
• Agent+RPA 实战 · 索引
• 🧩 Skill提效实战 · 索引