工作转技能

把已完成的工作封装成AI 拿到就能独立完成的技能。

> 加载即执行： 判断是创建新技能还是更新已有技能 → 按对应流程推进 → 验证可复现性 → 交付。

核心认知

技能不是文档，是 AI 的执行手册。

正确顺序：
1. 有人把工作做完（项目完成、问题解决、流程跑通）
2. 有人教 AI 做了一遍（提示词、验证、修正，记录全过程）
3. 把教学过程和经验封装成技能（SKILL.md + references/）
4. 以后遇到同样工作，AI 直接调用技能，独立完成

不是： 先写技能 → 再去做工作。
而是： 先做工作 → 教 AI 做 → 封装成技能 → AI 复现完成。

技能的目标：可复现

判断标准： 把技能给一个完全不了解背景的人，AI 能独立完成工作吗？

Gotchas（本技能必读）

• 不要先写技能再去做工作 → 先做完工作、教 AI 做一遍，再封装
• 不要凭空想象 Gotchas → 必须从教 AI 的真实失败记录里提取
• 不要写"注意金额单位"这种提醒 → 必须写成"遇到金额 → 传分时值（99.9元 → amount=9990）"
• 不要漏掉负面触发器 → description 末尾必须加 Do NOT use for...
• 不要 SKILL.md 超过 500 行 → 超了立刻拆到 references/
• 不要忘记验证完成标准 → 技能末尾必须写"## 验证完成"，AI 才知道做完没有
• 不要教 AI 做一遍就结束 → 必须把教学过程记录到 assets/teaching-record.md，以后再封装时才有依据

快速导航

创建新技能 vs 更新已有技能

先判断：是要创建新技能，还是更新已有技能？

已有技能目录存在？
  → 否 → 走下方"五阶段流程"（创建新技能）
  → 是 → 判断更新类型：

    新增 Gotchas / 修正流程 / 补充边界情况？
      → 增量更新（patch/minor）
      → 参考 [references/updating-skills.md](references/updating-skills.md)

    改变核心流程 / 新增独立工作流 / 改变调用方式？
      → 重大更新（major）
      → 重新走五阶段流程，标记 BREAKING CHANGES

关键原则：
- 增量更新：只追加不修改已有正确内容，更新 CHANGELOG.md
- 重大更新：备份旧版本，重新验证，明确迁移路径

五阶段流程（创建新技能）

阶段一：工作识别

先确认：这份工作值得封装成技能吗？

□ 工作已完成（项目结束、问题解决、流程跑通）
□ 有实际踩坑记录（不是理论上可能踩坑）
□ 会重复发生（跨项目复用、多人需要）
□ 教 AI 做过一遍（有提示词、验证、修正记录）
□ 不是一次性方案、不是标准实践（React/Git 等已有文档）

不适合封装的情况：
- 工作还没做完 → 先做完再回来
- 一次性任务 → 写进 CLAUDE.md 或对话记录
- 标准工具（Git/React/Python）→ 已有广泛文档
- 项目专属约定 → 放项目 README

> 详细判断标准 → references/workflow-guide.md

阶段二：经验萃取

从已完成的工作中，提取 Agent 会踩的坑，并写明怎么避开。

萃取来源（按优先级）：
1. 实际失败记录 — 教 AI 做事时它犯过的错（最高优先级）
2. 边界情况 — 极端输入、异常路径
3. 隐性知识 — 文档没写但老手知道的技巧
4. 环境依赖 — 特定版本、配置、权限要求

萃取原则：

不是写"坑是什么"
而是写"如果 AI 遇到 X，应该做 Y"

示例：

## Gotchas
- `amount` 单位是分，99.9元 → `amount=9990`（遇到金额自动转换）
- 批量查询上限 100 条，超过要分页，用 offset 参数
- v2 需要先调 `auth()` 再调业务接口，顺序不能反

> 完整萃取方法论 → references/extraction-guide.md

阶段三：教学记录

记录"教 AI 做事"的完整过程，这是技能的灵魂。

必须记录的内容：

□ 初始提示词（第一次教 AI 时说的话）
□ AI 的第一次尝试（它怎么理解的）
□ 失败场景（哪里错了、为什么错）
□ 修正指令（怎么告诉它改）
□ 验证结果（改完后对不对）
□ 边界测试（极端情况行不行）

> 教学记录模板和示例 → references/teaching-record.md

阶段四：技能封装

把萃取的经验和教学记录，按规范写入文件。

写入顺序：

① 写 Frontmatter（name + description + 触发条件）
② 写 SKILL.md 首屏（加载即执行 + Gotchas + 核心流程）
③ 拆出 references/（>50 行的独立主题）
④ 写 scripts/（可执行代码）
⑤ 补全 config.json + CHANGELOG.md + LICENSE + .gitignore

关键规则：
- SKILL.md ≤ 500 行，>30 行移 references/
- description 必须同时写"做什么"和"何时用"
- Gotchas 必须写成"如果 X 则 Y"，不是单纯提醒
- 所有引用路径必须真实存在
- 必须包含验证完成的标准
- 必须包含回滚/纠错方案（如有风险操作）

> 详细写入规范 → references/writing-guide.md
> 可复现性设计 → references/reproducibility-guide.md
> description 写法 → references/cso.md

阶段五：可复现性验证

验证 AI 拿到技能后，能否独立完成工作。

运行自动化验证：

python scripts/validate_skill.py

人工可复现性检查：

□ AI 拿到技能后，不需要问你"接下来怎么办"
□ 每条 Gotcha 都包含"遇到 X 时做 Y"
□ 环境依赖全部写明（版本、配置、权限、密钥）
□ 决策点有明确选择标准（没有"视情况而定"）
□ 有验证完成的标准（AI 知道什么时候算做完）
□ 有风险操作时，有回滚/纠错方案
□ 所有教学记录中的失败，Gotchas 里都有对应预防
□ 同一个错误，AI 不会再犯第二次

终极测试：

把技能给一个完全不了解背景的人，让 AI 按技能执行。
AI 能独立完成工作吗？能 → 可复现。不能 → 补缺失。

> 完整验证清单 → references/complete-checklist.md

阶段五（变体）：更新已有技能

已有技能，发现新坑，如何安全更新？

1. 加载已有技能（读取全部文件，理解当前内容）
2. 识别新增内容（新坑 vs 已有 Gotchas 是否冲突）
3. 安全修改（优先追加，不破坏已有内容）
4. 更新版本号（PATCH / MINOR / MAJOR）
5. 更新 CHANGELOG.md（写明变更原因）
6. 运行验证脚本：python scripts/validate_skill.py
7. 人工确认：核心流程未被破坏，旧场景仍然正确

版本号规则：
- PATCH：修正错误、补充 Gotcha（1.0.0 → 1.0.1）
- MINOR：新增功能/工作流（1.0.0 → 1.1.0）
- MAJOR：不兼容变更（1.0.0 → 2.0.0）

> 完整更新指南 → references/updating-skills.md

阶段六：数据脱敏

所有阶段完成后，最后一步：询问用户是否要对技能进行数据脱敏。

为什么要做脱敏

封装技能时，你的工作中天然包含大量敏感信息：
- 个人信息：姓名、手机号、邮箱、身份证号
- 公司信息：公司名、组织架构、部门名称
- 岗位职级：岗位名称、汇报关系、薪资范围
- 工作链路与流程【关键】: 审批链路、工作流、SOP、数据流向
- 系统工具：内部系统地址、API 端点、数据库名
- 账号凭证：Token、密码、API Key
- 业务数据：客户名单、交易记录、价格体系
- 沟通记录：聊天记录、邮件内容、内部术语

> 完整分类和脱敏规则 → references/desensitization-guide.md

Step 1：询问用户 — 让用户选择脱敏范围

完成前五阶段封装后，先展示敏感信息清单，让用户自己选哪些要脱敏：

> 「技能文件已封装完成。以下 8 类敏感信息中，哪些需要进行脱敏处理？
>
> ① 个人身份信息（姓名、手机、邮箱、身份证、照片）
> ② 公司/组织信息（公司名、组织架构、部门）
> ③ 岗位与职级（岗位名称、汇报关系、薪资、绩效）
> ④ 工作链路与流程【核心】（审批链路、工作流、SOP、数据流向）
> ⑤ 系统与工具信息（系统地址、API、数据库）
> ⑥ 账号与凭证（Token、密码、Key）
> ⑦ 业务数据（客户、交易、价格）
> ⑧ 沟通与内部信息（聊天、邮件、术语）
>
> 你可以全部脱敏，也可以只选其中几类。
> 脱敏后： 技能可公开发布、分享、变现
> 不脱敏： 技能仅限自己使用，不可对外」

用户选择范围 → 只对用户选中的类别执行后续步骤。
用户说"全部都要" → 走全流程。
用户说"全部都不要" → 直接交付，注明「未经脱敏，仅限自用」。

Step 2：扫描敏感信息

逐文件检查用户选中的类别，记录所有敏感信息出现位置：

📄 扫描报告（示例）：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SKILL.md:
  - 第12行：「张三」→ 个人姓名（①类）
  - 第18行：「星辰科技」→ 公司名（②类）
  - 第25行：「人事专员向部门总监汇报」→ 岗位+汇报关系（③④类）
  - 第31行：「审批链：专员→总监→VP」→ 工作链路（④类）

references/example.md:
  - 第8行：「zhangsan@techcorp.com」→ 邮箱（①类）
  - 第15行：「https://internal-api.example.com」→ API地址（⑤类）

scripts/validate.py:
  - 第5行：「api_key = "[你的 API Key]"」→ 凭证（⑥类）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

把扫描结果展示给用户看，让用户知道具体有哪些内容被识别为敏感信息。

Step 3：逐类脱敏

按用户选中的类别和优先级处理（详见 desensitization-guide.md）：

Step 4：生成「脱敏操作清单」并展示给用户

每做完一处脱敏，记录具体的脱敏操作，最后生成一份完整报告给用户确认：

📋 脱敏操作清单（示例）：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
【SKILL.md】
  · 「张三」 → 替换为「[姓名]」
  · 「星辰科技」 → 替换为「[某科技公司]」
  · 「李总」 → 替换为「[部门负责人]」
  · 「人事专员」 → 泛化为「人力资源岗」
  · 「审批链：专员→总监→VP」 → 泛化为「审批链：专员→主管→负责人」

【references/example.md】
  · 「zhangsan@techcorp.com」 → 替换为「[邮箱]」
  · 「https://internal-api.example.com」 → 替换为「[内部系统API地址]」

【scripts/validate.py】
  · 「skh_abc123...」 → 替换为「[你的 API Token]」

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
共处理 7 处敏感信息，涉及 4 个文件。

展示后问用户： "以上脱敏操作是否满意？有没有需要调整的地方？"

Step 5：脱敏验证

□ 用户选中的类别全部处理完毕
□ 脱敏后技能功能不受影响（流程结构保留）
□ 脱敏后无法追溯到具体公司/个人
□ 所有占位符标注清晰（如 [公司名称]、[部门]）
□ 脚本/SKILL.md 中无硬编码的 URL/IP/账号
□ 用户已确认脱敏操作清单 ✓

Step 6：交付

✅ 脱敏完成，技能已安全可发布。

📋 脱敏摘要：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
用户指定脱敏类别：① ② ③ ④ ⑤ ⑥
实际处理：6 个文件，12 处敏感信息
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

详细脱敏操作清单见上方，所有替换均经用户确认。
技能当前可公开发布、分享或变现。

> 完整脱敏指南和场景示例 → references/desensitization-guide.md

阶段七：平台适配发布

脱敏完成后，询问用户是否要推送到特定平台，按目标平台规范调整技能文件。

Step 1：询问目标平台

脱敏完成，技能已安全可发布。
你要推送到哪个平台？
  ─ 不指定平台 → 保持当前通用版本
  ─ skillhub.cn → 按 skillhub 规范调整
  ─ Coze「我的技能」 → 按 Coze 商店规范调整
  ─ ClawHub → 按 ClawHub 规范调整
  ─ 其他平台 → 请指定

Step 2：按平台规范调整

skillhub 规范差异：

☐ SKILL.md frontmatter 补充 slug 和 displayName 字段
☐ 删除 .gitignore（skillhub 不允许）
☐ 删除 LICENSE（skillhub 不允许，有自己许可证管理）
☐ 确认版本号唯一（不能重复使用已发布的版本号）

Coze「我的技能」规范差异：

☐ 使用 skill_draft_create 创建/更新草稿
☐ 配置三方 API 凭证（如需）
☐ 通过 skill_draft_publish 发布到「我的技能」

ClawHub 规范差异：

☐ 保持通用版本即可（与当前规范基本一致）
☐ 确认 name 与目录名一致

Step 3：适配后交付

✅ 平台适配完成。

📋 适配摘要：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
目标平台：{平台名称}
调整项：{删除 .gitignore / 补充 slug / ...}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

技能包已就绪，可推送至目标平台。

关于文件结构与平台规范

阶段五清单中的文件要求是通用规范（支持大部分平台）。不同平台可能有差异：

最佳实践： 先按通用规范创建和验证技能，在阶段七按目标平台调整发布。这样技能在通用状态下是完整的，适配不同平台只需做少量增删。

文件结构

skill-name/
├── SKILL.md              ← 必需：编排入口（≤500行）
├── scripts/              ← 必需：可执行代码（有 docstring）
├── references/           ← 必需：>50行独立主题移出
├── assets/               ← 必需：模板、图片等静态资源
├── config.json           ← 必需：运行时配置
├── CHANGELOG.md          ← 必需：版本变更记录
├── LICENSE               ← 必需：许可证
└── .gitignore            ← 必需：版本控制忽略规则

❌ 不要： README.md、__pycache__/、空文件、重复内容。

核心设计原则

Frontmatter 标准模板

---
name: your-skill-name
description: "What this skill does. Use when [trigger condition 1], [trigger condition 2], or [trigger condition 3]. Do NOT use for [exclusion condition]."
license: MIT
compatibility: "Requires Python 3.10+ and internet access"
metadata:
  version: "1.0.0"
  author: "your-org"
  category: "development"
  tags: ["pdf", "documents", "extraction"]
---

关键规则：
- name 必须与目录名完全一致（小写+连字符）
- description 必须同时包含"做什么"和"何时用"
- description 必须包含负面触发器（Do NOT use for...）
- description + when_to_use（如有）合并 ≤ 1536 字符

> description 详细写法 → references/cso.md

故障排除

> 完整故障排除指南 → references/troubleshooting.md

验证完成

本技能交付的技能包，必须满足：

□ python scripts/validate_skill.py → ✅ ALL CHECKS PASSED
□ 第七关可复现性验证 → 通过
□ 找不了解背景的人测试，AI 能独立完成工作
□ [如有脱敏] 阶段六脱敏验证 → 全部通过
□ [如有平台适配] 阶段七平台适配 → 已按目标平台规范调整

未满足以上任一条，不算完成，回对应阶段补全。