Skill 编写规范速查手册
> 怎么用：来查答案的，直接翻对应小节。每条都给可判定的标准，不给形容词。
> 形态：查用型（给人查），不替人做流程。正文只留规则与判定；细则按需加载 references/。
> 第一次用：先看 README.md 的 30 秒上手，再回这里查具体标准。
> 报错看不懂：跑 python scripts/lint.py --explain——每个检查码都有白话说明与改法，不必翻文档。
导览：四块积木
| 积木 | 回答的问题 | 小节 |
|---|---|---|
| ① 门槛层 | 怎么不被平台拒收、不静默失效 | §0 清单 · §1 frontmatter · §2 目录结构 |
| ② 内容层 | 怎么写得好，且该触发时触发 | §3 正文写法 · §4 触发设计 |
| ③ 诊断层 | 出问题怎么定位、怎么修 | §5 常见缺陷速查 |
| ④ 工程层 | 怎么可移植、可维护 | §6 可移植性 · §7 元规范 |
| 附 | 工具与进阶 | §8 伴生校验器 · §9 元规范与进阶检查 · 附录索引 |
① 门槛层 —— 让 skill 被平台接受
0. 发布前 30 秒清单
任一项不过就别上传。第 0 项与 1–7 项由 scripts/lint.py 自动判定——跑 python scripts/lint.py <目录> 即可。
| # | 检查 | 判定标准 |
|---|---|---|
| 0 | 校验器自身可信 | --selftest 全绿。跳过这步，下面所有 PASS 都不可信 |
| 1 | YAML 能解析 | §1.3，本地跑一遍，别靠平台试错 |
| 2 | name 合规 |
仅小写/数字/连字符；不含 claude / anthropic；与目录名一致 |
| 3 | description ≤1024 字符 |
超了必被拒 |
| 4 | description 五件事齐全 | §4.1。建议级——单行 WHAT 亦可，故只提示不阻塞 |
| 5 | 正例触发 + 反例不触发 | 只测一边等于没测（§4.2） |
| 6 | 无裸冒号、无英文冒号 | §1.3，症状是「技能莫名不触发」，极具误导性 |
| 7 | 包内无 __pycache__ / *.pyc / *.bak |
平台直接拒收二进制 |
| 8 | 打完包验产物 | python -c "import zipfile,sys;z=zipfile.ZipFile(sys.argv[1]);print(z.testzip() or 'OK')" <包.zip> |
进阶（可选）：加 --advanced 会另跑 10 条元规范（M01–M10），回答「能不能被反复用好」——
建议级，不影响上面的判定与退出码。判据与修法见 §9 与 references/04-meta-norms.md。
1. frontmatter
1.1 只有两个必填字段
---
name: my-skill-name
description: "做什么 + 什么时候用"
---
name：kebab-case；禁保留词 claude / anthropic（平台上传会被拒）；全局唯一，撞名加领域后缀；与目录名一致。
1.2 description 决定生死
它是唯一决定技能会不会被触发的字段。公式：做什么 + 什么时候用（含用户真实说法）。
- ✅ 写进用户会说的词：「跑流水线」「对标账号采集」「打包成稿」
- ✅ 写清负向边界：「不用于单篇精雕长文」
- ❌ 「一个很有用的技能」——永远不会被触发
- ❌ 超 1024 字符——上传被拒
1.3 ⚠️ 引号卫生（头号隐蔽杀手）
只要值里可能出现 :（冒号+空格）、箭头、中文引号，就必须整值加引号。 双引号内避免再出现未转义双引号（中文用「」代替）。
description: "含冒号：必须加引号" # ✅
description: 含冒号：必须加引号 # ❌ yaml: mapping values are not allowed
两条同源的坑要一起防：
| 坑 | 后果 | 处置 |
|---|---|---|
裸冒号 : 未加引号 |
YAML 解析直接失败 | 整值加引号 |
| 英文冒号（即便加了引号） | 部分平台按首个英文冒号截断，触发词后半段丢失 | 改用中文全角「：」 |
为什么单列：唯一一类本地能查、平台才报错的缺陷，症状极具误导性——不提示冒号，只表现为技能莫名不触发。
2. 目录结构（三层 + 渐进式披露）
my-skill/
├── SKILL.md # 入口：触发条件 + 主流程（每次激活都要读）
├── references/ # 按需加载的详细文档
└── scripts/ # 可执行逻辑（不占上下文，直接跑）
| 内容 | 放哪 |
|---|---|
| 触发条件、主流程 | SKILL.md |
| 详细说明、清单、示例 | references/*.md |
| 可执行逻辑 | scripts/* |
拆分判据：一段内容不是每次都用得上 → 拆到 references/，并在 SKILL.md 里写清「何时加载哪份」。
反模式：① SKILL.md 写成 5000 字长文全塞上下文；② references 拆成 20 个 200 字碎片，Agent 找不到；③ 脚本没实测就打包。
② 内容层 —— 让 skill 被读懂、被触发
3. 正文怎么写
给流程和判定标准，不给散文。 阈值、清单、决策表比形容词有用。
## 自检阈值
- 无建议 → 直接交付
- 不通过 < 3 项 → 轻量打磨（保持原文 ≥ 90%）
- 不通过 ≥ 3 项 → 重写改稿，最多 3 轮
人工确认点写成显式卡点：⛔ 人类卡点：采集完成后必须停下，等用户勾选才开写。
3.1 失败必须说清四状态
「说清完成了什么、没完成什么」是头号纪律——禁止只报喜。
| 状态 | 处理 |
|---|---|
| Not started | 说明障碍与替代路径，不静默放弃 |
| In progress | 交代当前进度与续跑方式 |
| Partial success | 必须说明：已完成哪些、缺口在哪、下一步从哪续 |
| Failed safely | 产物完好，交代终止原因与重启方式 |
4. 触发设计
4.1 description 五件事
| 项 | 判定 |
|---|---|
| WHAT | 有实际功能描述（不是空话） |
| WHEN | 含触发信号（「当用户…」/「use when」） |
| NEGATIVE | 含负向边界（「不用于…」/「do not use」） |
| 触发词示例 | 给 3–5 条用户真实说法 |
| 长度 | ≤1024 字符（超必拒，见 §1.2） |
说法装不下时（1024 是硬上限）：规则放 description，长尾实例下沉到 references/ 的路由表，并在门面挂入口——否则路由表不可发现，等于不存在。
> 五件事是召回优化建议，不是准入门槛。真正能立刻领先的是 NEGATIVE——
> 多写一句「不用于 X、Y」，代价最小、收益最大（判据与做法见 references/04-meta-norms.md M05）。
4.2 测试四层
- 格式层（30 秒，必做）：YAML 解析通过、description <1024、name 无保留词。
- 触发层（关键）：用真实用户口吻的句子测，不是技能名。
| 测试句 | 期望 |
|---|---|
| 「帮我跑一下流水线，出 5 篇」 | 触发 |
| 「今天天气怎么样」 | 不触发 |
只测触发、不测「不触发」= 没测——过度触发比不触发更烦人。
3. 执行层：脚本造最小输入实测；流程走一遍看卡点是否生效；产物人工过目。
4. 自验层（有脚本的才需要）：校验脚本自己验证过吗？配 fixture 矩阵（违规必报、干净必不报、指定码禁误报）一键回归，见 §8。
③ 诊断层 —— 出了缺陷怎么定位
5. 常见缺陷速查
先定位再修，别按症状打补丁。
| # | 缺陷 | 症状 | 根因 | 修法 |
|---|---|---|---|---|
| 1 | 教程化 | 解释 AI 已知概念 | 误把 Skill 当教学 | 删冗余，只留 Expert 知识 |
| 2 | 堆砌 | SKILL.md 800+ 行无拆分 | 缺渐进披露 | 拆 references，正文精简（M02） |
| 3 | 孤儿引用 | references 存在但从不加载 | 缺加载触发器 | 写清「何时加载哪份」（M03） |
| 4 | 清单流程 | Step 1/2/3 纯机械步骤 | 缺思维框架 | 加决策树 / 判断规则 |
| 5 | 模糊警告 | 「注意错误」「小心边界」 | 反模式不具体 | 改成症状+原因+修复（M07） |
| 6 | 隐身 | 内容好但从不激活 | description 差 | 五件事重写（§4.1） |
| 7 | 错位触发 | 「When to use」写在 body 里 | 误解三层加载 | 触发信号进 description + 补负向边界（M05） |
| 8 | 过度工程 | README/CHANGELOG/scripts 齐全但没必要 | 把 Skill 当软件项目 | 按自由度校准，MVP 先跑通（M01） |
| 9 | 自由度错配 | 创意任务用死板脚本 | 未校准任务风险 | 高风险给脚本，创意给原则框架 |
| 10 | 脚本裸奔 | 校验脚本写了却从没测过 | 把「脚本存在」当「脚本正确」 | 配 fixture 矩阵跑 --selftest；教训先加用例再改逻辑（M10） |
> 缺陷 10 是最贵的一种：前 9 种出错会被脚本抓住，它出错则所有脚本一起失效——
> 一个恒返回 0 的 lint 会让第 2–9 种缺陷全部隐身。所以它排在检查清单第 0 位。
>
> 这 10 种是基础层的缺陷（多数能被 G0xx 抓住）。基础之上还有 10 条元规范（M01–M10），
> 管「能不能被反复用好」——见 §9。
④ 工程层 —— 可移植、可维护
6. 可移植性（不绑定单一平台）
Agent Skills 是开放标准（agentskills.io，已被 Claude Code / Cursor / Copilot / Gemini CLI / WorkBuddy 等 40+ 产品采纳）——同一文件夹无需改动即可跨宿主复用。
- 核心路径只用标准字段（
name/description）；平台专有字段（slug/displayName）旁路并存，不进核心逻辑。 - 脚本零依赖：能标准库跑通就不引三方包。
- 不出现平台专属路径、专属工具名、专属品牌词。
绑定自检（任一命中即已绑定）：脚本 import 三方包 / 正文出现宿主绝对路径 / 非标准字段被正文依赖。
7. 元规范的地基（M09 / M10）
> 10 条元规范里，这两条比其余八条更要紧：它们不解决某个具体问题，
> 而是保证规则本身会长大。完整十条见 §9 与 references/04-meta-norms.md。
7.1 约束机器化（M09）
> 凡是能写成正则或枚举的约束，就不要写成「注意事项」。
「要注意冒号」会被绕过（换个马甲就逃）；「扫描值里是否有 :」不会。写完一条规范就问：有没有一条命令能在它再次发生时拦住它？没有，就别指望它被执行。
7.2 教训必须落检查项（M10）
踩过的坑写进 CHANGELOG 不算闭环。复盘三道必答：
- 教训 → 检查项：能不能变成机器可判定的检查？能 → 当天加进校验脚本；不能 → 写「不适用 + 理由」。
- 能力 → 主流程：新写的脚本开关，主流程调用了吗？
- 脚本 → 自验：这条新检查有没有对应用例？改逻辑前先加 fixture。
配套校验器就是这条规范的产物：§0 清单 0–7 项全部落成机器可判定检查（16 个检查码），
外加 10 条元规范的建议级检查，并自带回归自验——能判定就不写注意事项，判不了的就别装作能判。
附：工具与进阶
8. 伴生校验器
scripts/lint.py 是随包的校验器（零三方依赖），按两层标准分两组：基础检查 16 个码（G000–G016）
覆盖 §0 清单 0–7 项；进阶检查 10 条元规范（M01–M10）负责「优秀」那一层。
报告在「修法」之后内嵌一行白话——把这条检查在查什么、术语是什么意思，用日常语言再讲一遍；
单独查某一个码用 --explain <码>。校验器自带回归自验（--selftest）：它自身也会出错，所以它自己也要能验。
python scripts/lint.py <技能目录或zip> # 人读报告（三段式提示：症状/原因/修法）
python scripts/lint.py <目标> --strict # 严格模式：任一 WARN 即失败
python scripts/lint.py <目标> --advanced # 另跑 10 条元规范（建议级，不影响退出码）
python scripts/lint.py <目标> --advanced --json # 机器可读（findings + advisories 两段）
python scripts/lint.py --selftest # 回归校验器自己（加 -v 逐条列出用例）
python scripts/lint.py --explain # 检查码白话速查（--explain G008 看单条）
退出码：0 全 PASS / 1 有 FAIL 或 strict 下 WARN / 2 用法或路径错误。
机检边界、检查码总表与人工兜底 → references/03-edge-cases.md
（何时加载：lint 报出看不懂的条目，或怀疑它漏报 / 误报时）。
9. 元规范与进阶检查（基础之上求优秀）
§0 清单管「不被拒收」，这里管「被反复使用」。10 条完整版 → references/04-meta-norms.md。
| # | 元规范 | 一句话判据 |
|---|---|---|
| M01 | 单一职责 | 一块积木只做一件事，最小可用体量先跑通 |
| M02 | 路由器而非仓库 | SKILL.md 只做路由，明细下沉 references/ |
| M03 | 加载契约 | 写清「何时加载哪份」，并禁止加载无关件 |
| M04 | 接口向量分层 | 主 description 放规则，长尾说法下沉伴生字段 |
| M05 | 负向边界 | 写明「不用于…」，否则错位触发 |
| M06 | 失败信号 | 列「走偏信号」清单，让偏离可被自我识别 |
| M07 | 量化阈值 | 用数字代替「简洁 / 高效 / 尽量」 |
| M08 | 内外语言分层 | 不暴露 ID / token / 日志，不回显密钥 |
| M09 | 约束机器化 | 能写成正则或枚举的，不写成「注意事项」 |
| M10 | 教训落检查项 | 教训→检查项；能力→主流程；脚本→自验 |
怎么用：python scripts/lint.py <目录> --advanced 把这 10 条跑成进阶建议（含检查码与修法）；
建议级——命中只表示「值得复核」，不影响基础检查的判定。
> 何时加载：想知道「基础合规之上还差什么」时；动笔前定风格、评审他人 skill 时。
附录：文件索引
| 文件 | 内容 |
|---|---|
references/01-golden-example.md |
可复制的黄金 SKILL.md + 三则前后对比（隐身 / 堆砌 / 错位触发）+ 模板骨架 |
references/02-description-anatomy.md |
一条 description 的五件事逐字拆解 + 填空模板 |
references/03-edge-cases.md |
机检边界 23 项 + 检查码总表（基础 16 码 + 元规范 10 条）+ 人工兜底 |
references/04-meta-norms.md |
10 条元规范（判据 + 为什么 + 落地做法 + 机检码） |
scripts/lint.py |
校验器：基础 16 码 + 进阶 10 条元规范 + --explain 白话速查 + --selftest + --json |
