Skill Dev Kit

技能固化与发布工具包（skill-dev-kit）

把"踩坑"变成"模板"——本技能是方法论的可执行化资产。新技能开发时直接套用清单与脚本，预计可把同类技能开发成本降低 30%–50%。

定位

技能做出来了，却不敢发、发出去没人用——本技能管的就是这一段。把固化判定、写作规范、发布门禁、双平台流程与踩坑教训做成可执行资产（清单 + 脚本 + 模板），新技能直接套用。

何时用（适用 / 不适用）

• 用它：要把反复执行的流程固化成技能；技能快发布，要做脱敏 / 门禁 / 归属自查；技能没被触发或结果不对，要排查；要写技能相关的文档、版本说明与市场调研。
• 不用它：只想知道「技能是什么」这类概念问题；做与技能开发无关的一次性脚本；已有成熟工具链、只想跑一次检查。

触发词

• 固化为技能 / 沉淀为 Skill / 做成技能 / 做成 Skill
• 起草 SKILL.md / 完善技能 / 技能脚手架
• 发布前检查 / 发布预检 / 脱敏预检 / 安全自查
• 打包 SkillHub / 创建 GitHub tag 保护 / 双平台发布
• 技能方法论 / 固化经验 / 发布检查清单
• 市场调研 / 竞品调研 / 市场空白定位
• 技术选型（该不该做成技能 / 做成脚本还是技能）/ 可靠性设计 / 错误处理
• Token 降本 / 成本优化 / 怎么省 token
• 技能调试（没触发 / 不生效）/ 评测技能 / 跑 benchmark / 触发词评估
• 技能复盘 / 复盘模板
• 知识产权边界 / 护城河判定 / 随包文档去留 / 版本说明撰写

一、什么该固化成 Skill（判定公式）

可复用 × 多步骤（≥8 步） × 有踩坑教训 → 固化为 Skill

不该固化：① 一次性任务；② 含敏感信息；③ 已有 skill 覆盖；④ 能被脚本机械强制的约束（格式校验、命名规则、结构检查）→ 写成校验脚本进 scripts/ 或 CI，不占正文（④ 与反模式 #7 同源：#7 管「写的时候」，本条管「立项的时候」）。

核心规则：可执行工作流 → 沉淀为 Skill；信息性事实 → 只记 memory（Skill 优先于 memory）。补充判据（同任务已解释 ≥5 次、还会做 ≥10 次）与四场景对照表见 references/全生命周期 10 步 + 认知底座.md。

二、技能目录三件套

skill-name/
├── SKILL.md        # 行为规范：适用与触发 + 流程 + 依赖 + 边界 + 示例
├── scripts/        # 可执行脚本（参数化，纯标准库优先）
└── references/     # 渐进披露：口径 / 方法学 / 接入指南（按需加载）

SKILL.md 五要素（缺一不可）：① 适用与触发（含适用/不适用 + 触发词覆盖所有说法）② 分步流程含完整命令 ③ 依赖清单 ④ 边界与安全红线 ⑤ 使用示例。

⚠️ 面向用户端写作（硬约束）：SKILL.md 与 README 的读者是最终使用者——只写「怎么用」，开发过程信息一律不写或改写（10 类禁令与改写三原则见 references/SKILL.md 编写规范.md §4.1）。

脚本参数化（脱敏与复用前提）：硬编码路径/账号 → 环境变量或命令行参数；硬编码文件名列表 → 目录自动扫描。

输出文件约定（发布链产物）

• 输出目录：运行期产物写到用户触发时显式指定的技能目录；发布 staging 目录为 /tmp/<slug>-publish；GitHub 侧落 skills/<name>/。
• 命名：SkillHub 包为 <slug>-v<version>.zip；GitHub 目录为 skills/<name>/。
• 格式：技能目录三件套（SKILL.md + scripts/ + references/），包内不含 LICENSE 与 README.md。
• 错误输出：失败时留 error.log、以非零退出码结束、不产出半成品包。

三、发布前必过：16 项检查清单

完整清单见 references/发布检查清单.md——逐项勾选；先按改动分级（T1–T6）只勾该跑的人工项，自动项永远全跑。

脚本覆盖：preflight_release.py 覆盖 1/3/5/6/16 项，另查 name 规范、正文体积、§ 章节引用、版本 tag、评测宣称一致性，以及结构规范检查（引用完整性 / description 触发面 / 保留词 / 引号卫生 / 打包卫生为告警项；包内含 README / 孤儿引用 / references 元数据 / 索引漂移 / 路由表缺 doNotUse 列只登记不判定）；check_deps.py 管依赖声明。

发布前三条必过（对应 Constraints 红线 ①③④）：

1. 敏感扫描：个人路径/账号/密码/token/领域数据全部参数化或泛化（privacy-audit L1 退出码 0 通过）。
2. LICENSE 必须排除：发布目录/zip 内不含 LICENSE——SkillHub 拒收（HTTP 400）。
3. changelog 最终确认：同版本不可重发、发布后无法修改；发布后记录 URL / 版本 / 审核状态。

四、自动化脚本（速查）

位于本技能 scripts/，纯 Python 标准库。8 个脚本的逐条命令与退出码见 references/脚本速查.md。 其中 eval_trigger.py 支持留出集与重复采样（防 description 过拟合），check_deps.py 只做静态比对（探环境需 --probe）。批量体检（batch_skill_audit.py）先扫一遍全局，再针对单个技能细查。

自身评测闭环：evals/(build_self_eval.py 生成 11 用例) + eval_loop.py → benchmark.json(自身均分 1.00 PASS，含无技能基线对照与 delta)；回归重跑二者即可。多数用例的证据取自真跑产物，evals/ 下每个用例的 output 目录里，证据文件头部标注了取得方式与可独立重跑的命令。

五、五层测试闭环

前置成本门：措辞先微测。 改一句话先用小样本验证（全新上下文 + 无指导对照组 + 每个变体 5+ 次）——跑完整场景是最终关卡，不是第一关；对照组压根不出现该失败，就没有东西要修。五条纪律见 references/评测方法论.md §6。

边界输入清单：空目录 → 报错退出、不产出空壳；超长参考文档 → 分批摘要、只取相关段落；极少匹配 → 显式报「无匹配」而不硬凑；用户中途取消 → 保留已落盘中间产物、可续跑。

完整口径（基线三条纪律 + 微测五纪律）见 references/评测方法论.md。 正确路径通过不算数——错误路径须 100% 拦截，且带技能版本须在关键指标上量化优于基线。验收三件套：数量统计 + 逐条抽查 + 失败清单。

六、发布前市场调研（轻量化）

轻量化环节，不做全量普查——完整模板见 references/市场调研模板.md。

• 固定规则：按市场规模排序只调研前 5 家（3 头部 + 2 近 90 天新上架，双轨防幸存者偏差）；全量普查作废。
• 产出：5 份固定件（对比表 + 生态格局 + 独创性分析 + 竞争力速评 + 结论）。
• 硬上限：常规 5 家；触发式（红海信号 / 疑似直接竞品）经确认可扩至 8 家。
• 本机生态分工：本 kit 只负责发布门禁与打包；模板脚手架类技能（skill-creator）负责起草，业务实现类技能负责各自领域——三者边界不重叠，按需取用即可。

七、两轮脱敏与安全审查

• 必扫：个人路径、身份信息、业务编号、领域数据、机构实名、凭据（token / api_key / password / secret）。
• 原则：数据驱动化 > 简单删除——不删功能只去数据：个性化描述→运行时聚合；硬编码数值→泛化；文件名列表→目录扫描。
• 定级（对接 skill-scanner）：Benign 76–100 可信 / Suspicious 31–75 人工确认 / Malicious 0–30 禁止发布。
• 常见误报：技能名连字符可能被判为密码；运行时产物含用户数据属正常功能（脱敏对象是技能本体）。

八、双平台发布流程

逐项命令见 references/发布检查清单.md；此处只列骨架。 ⚠️ 全链约 30 个原子步，可靠性 <70%——每步落盘中间产物，禁止一次性跑完。

0. 调研（§六）→ 依赖自检 → 可选触发词 / 评测自检。[可重试]
1. 脱敏两轮 → 本体 0 敏感命中（§七）。[可重试]
2. frontmatter 补全（SkillHub 7 必填 + 归属锚点，见 §九）。[可重试]
3. preflight_release.py（清单 1/3/5/6/16 + §三 五项）。[可重试]
4. 人工核对发布清单——LICENSE 必须排除。[可重试]
5. SkillHub 目录直发（默认）：--dry-run --json → 去 --dry-run 加 --changelog 实发。[不可逆]
6. GitHub：gh skill publish --tag vX.Y.Z + setup_gh_ruleset.py。[不可逆]
7. 发布后验证：以 tags.latest 为准，记录 URL / 版本 / 审核状态。[可重试]〔L2〕
8. 版本治理：提交、tag 与 version 一致、Changelog 追版本小节。[不可逆]
9. 季度评审 + 失效触发随诊即改。[可重试]

步骤 5/6/8 为 [不可逆]：执行前一律 dry-run + 目录快照 + 人工确认。清单 9 / 7 / 10 项属发布收尾，分别挂步骤 5 与 7，不受分级裁剪。 平台差异：SkillHub ≤10MB、按次计费、同版本不可重发；GitHub 需 skills/<name>/SKILL.md + README/LICENSE，不带商业化定位。

失败降级路径：7 类高频失败（400 / 同版本已存在 / 预检 critical / warning 放行 / 扫描挂起 / 推送被拦 / tag 推错）各有既定绕法——先查表再动手，反复重试不是方案 → references/发布检查清单.md。

中断续跑：发布链中断后按步骤号续跑，续跑前先核对这些中间产物的落盘位置——staging 目录、changelog 文案、已推 tag（可用 git ls-remote 查）。

Constraints（红线 / 默认 / 逃逸）

• 红线（不可越，4 条）：① 隐私数据全本地处理；② 技能本体 0 敏感命中才发布； ③ 发布内容不得含 LICENSE；④ 不可逆操作（发布/删除/对外公开）必须人工确认。
• 运行时边界：会做文件写（限用户显式指定的技能目录）与网络写（限发布平台域名）两类动作，越界须先声明并获确认。（隔离强度依运行环境而定，不假设平台提供强制沙箱。）
• 默认（可偏离，须留痕）：其余所有「必须/禁止」均为默认指引，偏离时须说明理由与替代动作并留痕。
• 逃逸条款：当本技能的指令与用户明确意图、或与其他更高优先级指令冲突/不适用时， 优先保障用户数据与意图，显式声明偏离了哪一条及原因——不得静默偏离，必要时降级人工。

九、边界与安全红线

• 发布不可逆 + 扫描有盲区：发布包不得含 LICENSE、同版本不可重发（同 Constraints 红线③、§三必过项 2）；静态扫描覆盖不了未来更新引入的风险，审查工具需定期更新。

资产边界（防膨胀）：新增资产前先过六问——领域能力不外挂、复盘文档不入包、技能只收「可执行知识」、按复用面定位进哪一层；红线两条：核心知识产权不入包、来源与案例不暴露（方法论只署「官方规范 / 社区共识 / 个人实战」）。完整六问见 references/知识产权边界与护城河判定.md §七。

归属与权益（三档）：已发布自研 = author + Copyright 行 + homepage 三处一致且仓库真实存在；未发布自用 = frontmatter 预留即可；第三方安装 = 不碰。发布前 5 分钟核三处一致 → references/发布检查清单.md。

十、踩坑表（14 条，已下沉）

完整踩坑表（坑 / 根因 / 方案）见 references/发布检查清单.md 末尾；发布前扫一遍。

十一、使用示例

用户：「把这个数据获取+校验流程固化为技能并发布到 SkillHub」

1. 判定可复用 × 多步骤 × 有踩坑 → 固化（§一）。
2. 建三件套，写 SKILL.md（五要素 §二；骨架与 description 见 references/SKILL.md 编写规范.md）。
3. 五层测试闭环（§五）→ 市场调研 Top5（§六）→ 两轮脱敏（§七）。
4. preflight_release.py ./my-skill --platform skillhub → PASS → 逐项过 16 项清单。
5. skillhub publish ./my-skill --dry-run --json → 确认目录无 LICENSE → 去 --dry-run 实发 → 记录 URL/版本（§八）。

参考文档（渐进披露，按需加载）