# Skill Dev Kit

> 技能固化与发布工具包。当用户要"把工作流固化为 Skill、起草或完善 SKILL.md、做发布前脱敏与安全预检、打包 SkillHub zip、创建 GitHub tag 保护 ruleset、走双平台（SkillHub/GitHub）发布流程、沉淀可复用方法论、做技能触发词评估或评测循环"时使用。覆盖固化判定、技能目录三件套、SKILL.md 五要素、五层测试闭环（含基线双跑对照）、两轮脱敏审查、发布前 16 项检查清单（含 author/Copyright 归属门禁，按改动类型分级裁剪）、8 脚本自动化（含依赖自检与推送兜底）、触发词评估与评测循环、双平台发布、复盘与自动化反哺。内置脚本零第三方依赖（仅 Python 标准库 + 可选 gh/skillhub CLI），可直接接入 CI 门禁。不适用 / 不用于：技能内部业务逻辑的实现与运行期排障（属发布链路之外的事）、与技能开发无关的一次性脚本、已有成熟流水线且只想跳过检查直接发布的情形。

- Skill: `johnsmithca-sta/skill-dev-kit` (Agent Skill, multi-file: 78 files)
- Install (CLI): `npx skillmds@latest add johnsmithca-sta/skill-dev-kit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/johnsmithca-sta/skill-dev-kit/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: johnsmithCA-sta (https://skillmd.com/u/johnsmithca-sta)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/johnsmithca-sta/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。

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

| 层级 | 做法 | 验收 |
|---|---|---|
| 基线对照 | 同 prompt 跑不带技能（新建）或旧版（改进） | 关键指标上可量化优于基线；**无差异 = 技能没教新东西** |
| 端到端跑通 | 最小真实链路先通 | 主链路 1 次成功 |
| 合成 → 增强样例 | 先最小闭环，再覆盖全特性 | 核心链路 + 全特性通过 |
| 真实数据 | 规模化验证 | 0 失败 / 逐条抽查 |
| 错误路径 | 错误输入必须被拦截 | 拦截率 100% |

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

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

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

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

## 七、两轮脱敏与安全审查

| 轮次 | 做法 | 工具 |
|---|---|---|
| 第一轮 | grep 关键词 + privacy-audit 技能 L1 自动扫描 | `privacy-audit`（退出码 0 通过 / 1 高危禁止发布 / 2 需人工确认） |
| 第二轮 | 市场专业审查技能 | `skill-scanner`（朱雀实验室） |

- **必扫**：个人路径、身份信息、业务编号、领域数据、机构实名、凭据（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/版本（§八）。

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

| 文件 | 内容 | 何时查 |
|---|---|---|
| 发布检查清单.md | 16 项清单 + 改动分级 + 降级路径 + 归属三档 + 踩坑表 | 发布前 |
| 脚本速查.md | 8 脚本命令/退出码/CI + 脚本 ACI 规范 | 用脚本 |
| SKILL.md 编写规范.md | 五要素 + 生产骨架 + description 五策略 + 面向用户端写作（§4.1） | 起草/改技能 |
| 核心公式与量化基准.md | 11 条基准 + 工具参数 + Token 降本 | 评审/降本 |
| 反模式清单.md | 30 条反模式 + 可观测判据 + 自查表 | 写码前 |
| 错误处理与可靠性纪律.md | 12 条可靠性纪律（含代码示例） | 设计脚本/写复盘 |
| 调试三步法.md | 未触发 / 不一致 / 输出异常诊断 | 技能出问题 |
| 全生命周期 10 步 + 认知底座.md | Skill 本质 + 选型三岔口 + 四场景对照 | 立项 |
| 知识分层与版本治理.md | 三层 memory + 版本治理 + 失效触发 | 版本决策 |
| 市场调研模板.md | 抽样双轨 + 5 份固定件 + 发布曝光配套 | 发布前调研 |
| 评测方法论.md | Grader 六铁律 + 双轨设计 + 用例标准 + 构建路线图 + 留出集 | 做评测时 |
| 复盘报告模板.md | 五段式复盘模板 | 交付后复盘 |
| 知识产权边界与护城河判定.md | 反向检查 + 护城河三要素 + 对外双轨制（§6.1 版本说明）+ 资产边界（§七） | 发布前 IP 自查 |
| Changelog.md | 版本史（用户侧口径） | 追溯变更 |