技能固化与发布工具包（skill-dev-kit）
把固化判定、写作规范、发布门禁、双平台流程与踩坑教训做成可执行资产（清单 + 脚本 + 模板）。用它：固化流程为技能、发布前脱敏 / 门禁 / 归属自查、技能没触发或结果不对的排查、技能文档与市场调研。不用它：概念问答、技能内部业务逻辑实现与运行期排障、与技能开发无关的一次性脚本、只想跳过检查直接发布。
触发词
固化为技能 / 沉淀为 Skill / 做成技能 / 技能脚手架 ｜ 发布前检查 / 发布预检 / 脱敏预检 / 安全自查 ｜ 打包 SkillHub / 创建 GitHub tag 保护 / 双平台发布 ｜ 市场调研 / 竞品调研 / 市场空白定位 / 技术选型 ｜ 技能方法论 / 可靠性设计 / 错误处理 / Token 降本 ｜ 技能调试（没触发）/ 评测技能 / 跑 benchmark / 触发词评估 / 技能复盘
一、固化的两段式判定
先过自用门槛，再过发布门槛——两问分别回答，不许合并。
- 自用门槛：可复用 × 多步骤（≥8 步） × 有踩坑教训 → 固化。不该固化：一次性任务、含敏感信息、已有技能覆盖、能被脚本机械强制的约束（写成校验脚本进
scripts/或 CI，不占正文）。 - 发布门槛：立项时就要问。普适性 / 社区覆盖度 / 可移植性三维打分，越低越不该发。
- 结果分流：只过自用 ⇒ 固化不发布，落宿主技能目录自用（示例路径
~/.workbuddy/skills/；不同 harness 按其宿主目录替换）；两问全过 ⇒ 固化并发布，进 §五 → §七；只过发布 ⇒ 不发。 - 核心规则：可执行工作流 → 沉淀为 Skill；信息性事实 → 只记记忆文件（宿主提供的跨会话持久存储）。Skill 优先于记忆。
二、技能目录三件套与输出约定
skill-name/
├── SKILL.md # 行为规范：触发 + 流程 + 依赖 + 边界 + 示例
├── scripts/ # 可执行脚本（参数化，纯标准库优先）
└── references/ # 渐进披露：按需加载的口径 / 方法学 / 接入指南
- SKILL.md 五要素（缺一不可）：① 适用与触发（含不适用）② 分步流程含完整命令 ③ 依赖清单 ④ 边界与安全红线 ⑤ 使用示例。
- 脚本参数化（脱敏与复用前提）：硬编码路径 / 账号 → 环境变量或命令行参数；硬编码文件名列表 → 目录自动扫描。
- 输出约定：运行产物写到用户显式指定的技能目录；staging 目录
/tmp/<slug>-publish；SkillHub 包名<slug>-v<version>.zip，包内不含 LICENSE 与 README.md；失败留error.log、以非零退出码结束、不产出半成品包。 - 中断续跑：发布链中断后按步骤号续跑，续跑前先核对中间产物落盘位置（staging 目录、changelog 文案、已推 tag 用
git ls-remote查）。
> ⚠️ 对外文本怎么写见 references/SKILL.md编写规范.md §4.1；检查面是随包对外 markdown（SKILL.md / README / references/ 下全部 md / 版本档案），references/ 不豁免。
> ⚠️ 正文不留会随项目演进变化的数值与清单，只留「去哪个文件读 + 一条当场能跑的命令」（判据见 references/SKILL.md编写规范.md §4.8）。
三、发布前必过检查清单
- 逐项勾选见
references/发布检查清单.md：16 项 + 改动分级（T1–T6，只裁人工项）+ 门禁分层（挡发布 / 只报告）+ 降级路径 + 归属三档 + 踩坑表。 - 脚本覆盖：
preflight_release.py覆盖清单 1/3/5/6/16 项，另做六项检查与结构规范检查（清单见references/脚本速查.md§1）；check_deps.py管依赖声明。已登记的豁免用--waive-file <留痕件>复用，不必每次重抄--waive。--strict只在发版那一刻开。
四、自动化脚本（速查）
> 位于本技能 scripts/，纯 Python 标准库，逐条命令与退出码见 references/脚本速查.md。eval_trigger.py 支持留出集与重复采样；check_deps.py 只做静态比对（探环境需 --probe）。
> 自身评测闭环：evals/（build_self_eval.py 生成用例）+ eval_loop.py → benchmark.json（含无技能基线对照与 delta）。
五、五层测试闭环
| 层级 | 做法 | 验收 |
|---|---|---|
| 基线对照 | 同 prompt 跑不带技能（新建）或旧版（改进） | 关键指标可量化优于基线；无差异 = 技能没教新东西 |
| 端到端跑通 | 最小真实链路先通 | 主链路 1 次成功 |
| 合成 → 增强样例 | 先最小闭环，再覆盖全特性 | 核心链路 + 全特性通过 |
| 真实数据 | 规模化验证 | 0 失败 / 逐条抽查 |
| 错误路径 | 错误输入必须被拦截 | 拦截率 100% |
> 正确路径通过不算数——错误路径须 100% 拦截，且带技能版本须量化优于基线；验收 = 数量统计 + 逐条抽查 + 失败清单。前置成本门：改一句话先跑措辞微测（全新上下文 + 无指导对照组 + 每个变体 5+ 次），完整场景是最终关卡、不是第一关（references/评测方法论.md）。
六、两轮脱敏与安全审查
- 第一轮：grep 关键词 +
privacy-auditL1 自动扫描（退出码 0 通过 / 1 高危禁发 / 2 需人工确认）。 - 第二轮：用
skill-scanner等第三方静态扫描器二次扫描；分数区间与定级名目以该工具自己的官方说明为准，本技能不自造分档。 - 必扫：个人路径、身份信息、业务编号、领域数据、机构实名、凭据。原则：数据驱动化 > 简单删除（不删功能只去数据）。常见误报：技能名连字符像密码；运行时产物含用户数据属正常（脱敏对象是技能本体）。
七、双平台发布流程
> ⚠️ 全链较长（约 30 个原子步）、可靠性随步数衰减——每步落盘中间产物，禁止一次性跑完，每步须有「完成判据 + 产物落盘校验」。逐步命令、失败降级路径与中断续跑见 references/发布检查清单.md。
- 市场调研（前 5 家 = 3 头部 + 2 近 90 天新上架，5 份固定件，见
references/市场调研模板.md）→ 依赖自检 → 触发词 / 评测自检（改过触发词或 name / displayName 必须跑eval_trigger.py，--check与--from-description都跑，结果随报告归档）。[可重试] - 脱敏两轮（§六）→ frontmatter 补全（SkillHub 7 必填 + 归属锚点，见 §八）→
preflight_release.py（§三）。[可重试] - 人工核对清单（LICENSE 必须排除）→ 三视角语义通读（必须派独立子代理；不受分级裁剪；未回报不发布、整改后须复核轮；判据见
references/发布检查清单.md清单 12）。[可重试] - SkillHub 发布（默认先打包）：
make_skillhub_zip.py打包后发 zip（--dry-run --json→ 实发加--changelog）。[不可逆]⚠️ 目录直发不是默认路径——CLI 收集文件不做排除，带 LICENSE 必被 400 拒。 - GitHub：
gh repo create+git push+git tag -s+setup_gh_ruleset.py。[不可逆]⚠️ CLI 无gh skill publish子命令。 - 验证以
tags.latest为准，记录 URL / 版本 / 审核状态 → 版本治理（tag 与 version 一致、Changelog 追小节）→ 季度评审与失效触发随诊即改。[可重试]
> 第 3 / 4 步 [不可逆]：执行前一律 dry-run + 目录快照 + 人工确认。平台差异：SkillHub ≤10MB、按次计费、同版本不可重发；GitHub 需 skills/<name>/SKILL.md + README/LICENSE，不带商业化定位。
八、边界与安全红线
- 发布不可逆 + 扫描有盲区：发布包不得含 LICENSE、同版本不可重发；静态扫描覆盖不了未来更新引入的风险，审查工具需定期更新。
- 资产边界（防膨胀）：新增资产前先过六问（见
references/知识产权边界与护城河判定.md§七）——领域能力不外挂、复盘文档不入包、技能只收「可执行知识」、按复用面定位进哪一层；红线两条：核心知识产权不入包、来源与案例不暴露。 - 归属与权益（三档）：已发布自研 = author + Copyright 行 + homepage 三处一致且仓库真实存在；未发布自用 = frontmatter 预留即可；第三方安装 = 不碰（逐档动作见
references/发布检查清单.md）。
Constraints（红线 / 默认 / 逃逸）
- 红线（不可越）：① 隐私数据全本地处理；② 技能本体 0 敏感命中才发布；③ 发布内容不得含 LICENSE；④ 不可逆操作（发布 / 删除 / 对外公开）必须人工确认。
- 运行时边界：文件写限用户显式指定的技能目录；网络写限发布平台域名；越界须先声明并获确认（隔离强度依运行环境而定，不假设平台提供强制沙箱）。
- 默认（可偏离，须留痕）：其余所有「必须 / 禁止」均为默认指引，偏离时须说明理由与替代动作。
- 逃逸条款：与用户明确意图或更高优先级指令冲突 / 不适用时，优先保障用户数据与意图，显式声明偏离了哪一条及原因——不得静默偏离，必要时降级人工。
九、使用示例
> 用户：「把这个数据获取 + 校验流程固化为技能并发布到 SkillHub」
- 判定：可复用 × 多步骤 × 有踩坑 → 固化（§一）。
- 建三件套，写
SKILL.md（五要素 §二；骨架与 description 见references/SKILL.md编写规范.md）。 - 五层测试闭环（§五）→ 市场调研 Top5 + 两轮脱敏（§六、§七 步骤 0–1）。
preflight_release.py ./my-skill --platform skillhub --waive-file .preflight-waiver.json→ PASS → 逐项过清单（§三）。make_skillhub_zip.py ./my-skill→skillhub publish <zip> --dry-run --json→ 实发加--changelog→ 记录 URL / 版本（§七）。
参考文档（渐进披露，按需加载）
各文件头部自带「加载条件 / 命中标签」，按当前任务取用；下列内容摘要仅供定位：
references/发布检查清单.md：16 项清单 + 改动分级 + 门禁分层 + 降级路径 + 归属三档 + 踩坑表references/脚本速查.md：脚本命令 / 退出码 / CI 接入 + ACI 规范references/SKILL.md编写规范.md：五要素 + 生产骨架 + description 五策略 + 面向用户端写作（§4.1）+ 守恒判据（§4.8）references/全生命周期 10 步 + 认知底座.md：Skill 本质 + 选型三岔口 + 四场景对照 + 泛化四步references/评测方法论.md：Grader 铁律 + 双轨设计 + 用例标准 + 措辞微测（§6）references/核心公式与量化基准.md：十一条主基准 + 工具参数 + Token 降本references/反模式清单.md：反模式总表 + 可观测判据 + 自查表references/错误处理与可靠性纪律.md：可靠性纪律总表 + 代码示例references/调试三步法.md：未触发 / 不一致 / 输出异常诊断references/知识产权边界与护城河判定.md：反向检查 + 护城河三要素 + 对外双轨制（§6.1）+ 资产边界（§七）references/知识分层与版本治理.md：版本治理 + 拆分阈值 + 失效触发references/市场调研模板.md：抽样双轨 + 5 份固定件 + 发布曝光配套references/复盘报告模板.md：五段式复盘模板references/Changelog.md：版本发布说明references/Changelog写作模板.md：收录判据 + 条目公式 + 量化边界
