Skill开发管理工坊（SkillWorks）

> 不是给人用的项目管理工具，是给AI自己用的开发管理规范。
> 把所有踩坑经验（分批改、不归档、不写CHANGELOG、不做营销……）沉淀为可执行规则。

Design Mode: Pipeline + Gate + Inversion + Generator + Reviewer

双入口流程

本Skill有两条入口路线。用户说"创建/升级/改进/重构 XXX"时触发：

用户发出创建/升级/改进/重构指令
    ↓
┌──── 讨论模式 ──────────────────────────────────────┐
│  走 Phase 1（需求采集）+ Phase 2（方案设计）         │
│  聊完了但还没说"开干" → 方案存档，下次继续           │
│  🔐 Gate: 用户确认方案                              │
└────────────────────────────────────────────────────┘
    ↓（用户说"开始创建" / "开始升级" / "开干" / "执行"）
┌──── 执行模式 ──────────────────────────────────────┐
│  从头走完整流程：归档→文件生成→PM更新→Review→打包   │
│  🔐 Gate: 所有Gate通过                              │
└────────────────────────────────────────────────────┘

🚀 快速：用户怎么用

讨论模式

Phase 1A：创建需求采集（Inversion — 创建新Skill）

Step 0：先写评测用例，再写Skill

> Skill最大风险不是"不加载"，而是"乱加载"。先定义路由边界，再写内容。

在开始问任何问题之前，先帮助用户创建这个Skill的评测用例集：

评测用例三来源
1. 真实用户查询 — 用户实际会怎么问？列出3-5条典型请求
2. 已知失败案例 — 过去同类Skill踩过什么坑？哪些请求曾导致错误响应？
3. 邻近领域混淆（负例） — 哪些请求看起来像、但不该触发这个Skill？

> 负例比正例更重要。 每增加一个Skill都可能让其他Skill变差。明确什么情况不触发，是防止"乱加载"的关键。

输出给用户过目确认。

> 🔐 Gate: 评测用例已创建(含正例+负例)且用户确认 → 进Phase 1A。

在所有阶段完成之前，不要开始构建或设计。 以下问题全部问完后再进Phase 2。

1. 项目名称是什么？ 中文&英文各是什么？
2. 一句话描述这个Skill做什么？
3. 目标平台是什么？
   - 华为小艺开放平台（较严格）
   - SkillHub（较宽松）
   - 两者都要（推荐：以华为规范为准，同时兼容SkillHub）
4. 属于哪类？（参照九类分类法，见 references/design-patterns.md）
5. 需要哪些功能点？（5-20个）
6. 有什么现成的参考资料？（方法文件、笔记、已有知识库等）
7. 有营销/推广的考虑吗？（品牌名、超级话语、目标用户）
8. 哪些操作可以固化为脚本？ — 每次执行逻辑一致的确定性操作(如数据解析/格式转换),写成 scripts/ 脚本,不让模型重复发明

> 🔐 Gate: 以上问题全部有答案 → 进Phase 2。用户说"你看着办" → 给出默认方案让用户确认。

Phase 1B：升级需求采集（Inversion — 升级已有Skill）

先问清楚以下3个问题，全部回答后才能进Phase 2：

1. 改哪个Skill？（项目文件夹路径）
2. 为什么改？ — 遇到什么问题？平台要求变动？功能扩展？
3. 具体改什么？ — 功能变更 / 内容修正 / 规范适配 / Bug修复 / 体验优化

然后读取当前SKILL.md和相关文件，分析现状与目标的差距，形成改动方案草案。

评测回顾

检查这个Skill原有的评测用例(如有 references/评测用例.md)，确认本次改动的范围是否需要新增或修改评测：是否有新的正例/负例需要加入？

如果没有现成的评测用例，创建一份初始评测用例并写入 references/评测用例.md。

经验池检查：判断是否值得升级

在进Phase 2之前，先查这个Skill的 references/经验池.md，判断改动证据是否充分：

读给用户听判断结论，让用户决定是否继续。

> 🔐 Gate: 目标明确、差距清晰 + 经验池判断结论已告知用户 → 进Phase 2。不确定时让用户再想想。

Phase 2：方案设计

2.1 定类型（九类分类法）

详细分类说明参见 references/design-patterns.md。快速参考：

2.2 定设计模式

2.3 定文件结构

skill-name/
├── SKILL.md          ← 核心指令（≤500行），只写模型搞不定的判断边界
├── module.json       ← 华为平台配置（Semver版本号）
├── _meta.json        ← 元数据（SkillHub兼容）
├── CHANGELOG.md      ← 版本变更记录
├── references/       ← 参考文档（按需条件加载）
│   ├── checklist.md  ← Reviewer检查清单
│   ├── 评测用例.md   ← 正例+负例，定义路由边界
│   ├── 产品简介.md   ← 平台展示文案，不参与行为指令
│   ├── 经验池.md      ← 使用反馈积累，为升级决策提供依据
│   └── xxx.md        ← 其他具体参考（条件加载，不读完）
├── scripts/          ← 确定性逻辑脚本（不让模型重复发明）
│   └── parse_data.py ← 例：每次执行一样的解析逻辑
├── assets/           ← 静态资源（如需要）
└── data/             ← 用户数据（打包时排除）

> 文件结构即导航路径：什么信息必须马上给模型？什么可以需要时再读？什么根本不该让模型推理，而是交给确定性脚本？

2.4 定改动范围（升级路线专用）

列出所有受影响的文件及改动方式：

> ⚙️ 克制原则（SkillOpt）：列出所有需要改的点，区分"证据充分（必须本次改）"和"证据不足（建议等以后）"。一次只攻证据充分的点，不做大范围"顺手修改"。每次改动幅度不宜过大，避免破坏已有有效能力。

2.5 定工具与引用清单

列出所有需要声明的工具（toolDependencies）、附件、引用Skill等。

2.6 确认产品简介内容

生成三段平台展示用的产品简介让用户确认，写入 references/产品简介.md（不放进SKILL.md）：
- 🎯 这是什么？ — 活生生的介绍，用加粗强调核心价值
- 🚀 怎么用 — 表格，2-3个场景
- 📊 你能得到什么 — 收益+简短输出样例预览

通用规则： 不说AI专业术语，活灵活现先说"能干嘛"再说"怎么干"。

读给用户听，让用户确认后写入 references/产品简介.md。

> 🔐 Gate: 用户确认了方案（含产品简介）？→ 开始执行。

2.7 升级后的经验池更新计划

在动手前，预判本次升级完成后，经验池需要新增什么记录：

1. 本次升级要解决的问题 → 改完后经验池记录"已修复"
2. 本次升级尝试改了什么 → 写入经验池以备后续效果评估
3. 如果本次是"证据不足但用户坚持" → 标注到经验池，后续自动追踪效果

执行模式

用户说"开始创建" / "开始升级" / "开干" / "开始执行"时启动。顺序执行，不可跳步。

Step 1：归档旧版（仅升级时执行）

cd skills/<项目名>
mkdir -p archive

# ① 当前完整目录打包存档
cp -r . /tmp/<项目名>-backup/
cd /tmp && zip -r "skills/<项目名>/archive/<项目名>-v当前版本-完整包.zip" "<项目名>-backup/"
rm -rf /tmp/<项目名>-backup/

# ② dist/旧zip移到archive/
[ -f dist/<项目名>-v当前版本.zip ] && mv dist/<项目名>-v当前版本.zip archive/

> 🔐 Gate: 旧版已完整保留（升级时）/ 跳过（创建时） → 进下一步

Step 2：创建项目文件夹（仅创建时执行）

mkdir -p skills/<英文名>/references
mkdir -p skills/<英文名>/dist
mkdir -p skills/<英文名>/archive

> 🔐 Gate: 文件夹就绪 → 进Phase 3

Phase 3：文件生成/修改（Generator）

按Phase 2确定的方案，生成或修改完整Skill文件夹。

3.1 SKILL.md 生成标准

Frontmatter（YAML）:

> description是最难写的部分。 它决定路由——写太宽会误触发，写太窄会错过加载。以真实用户查询为来源，控制在50词以内。

正文写作原则：从命令级走向意图级

❌ 不要写通用流程 — 模型本来就会做的事（如"先理解需求→再拆解步骤→再执行→再总结"）不写，写了只占token。
❌ 不要写一串命令 — 如"先git log→再checkout main→再建分支→再cherry-pick"。环境一变就断了。
✅ 写意图级指导 — 告诉模型"目标是什么，冲突时保留什么，失败时怎么解释，不要做什么"
✅ 写判断边界和坑点 — 那些"看起来可以做但千万别做"的地方最值钱
✅ 写你的opinion — 领域判断、工程判断、从失败中学到的经验

正文结构（四层6块，总行≤500）：

关键原则：
- ❌ 不陈述AI已知道理（如"PE=市值/净利润"）
- ✅ 只写模型搞不定的东西（偏好、坑、流程规定）
- ✅ Gotchas（踩坑点）是最值钱的内容
- ✅ 正文里的"标准流程"砍掉，换成"判断优先级"和"负例"
- ✅ scripts/里的脚本调用方式要在SKILL.md里直接写明

3.2 ~ 3.4 各文件模板

参考 references/file-templates.md 中的module.json / _meta.json / CHANGELOG.md 模板直接生成。

3.5 参考资料生成

根据类型生成对应的references/文件：
- checklist.md — 通用Reviewer检查清单（参见Phase 4检查维度）
- 评测用例.md — 将Step 0创建的评测用例(正例+负例)写入此文件
- 经验池.md — 经验积累文件（创建/升级时都自动生成空模板，详见下面 "经验池模板内容"）
- 其他按需的参考文档

> 条件加载原则：不要让模型一上来全读references/。SKILL.md里写明："满足条件X时再去读Y文件"。如："如果用户询问华为平台问题 → 读huawei-platform-guide.md"。不满足条件就不读。

scripts/ 生成

根据Phase 1A Q8或Phase 2方案确定的"可固化为脚本的逻辑"，生成对应的 scripts/ 文件。

什么该放scripts/： 数据解析/格式转换/确定性验证/固定模板输出/外部工具调用固化逻辑
什么不该放scripts/： 需模型推理判断的/每次条件不同的操作

scripts/在SKILL.md中直接写明调用方式，不让模型每次重新发明代码。

如果本次没有需要固化的脚本逻辑，可跳过。

经验池模板

创建 references/经验池.md。模板结构：用户反馈 / 异常记录 / 改进建议 / 负反馈四张表，含"证据强度"字段。具体格式参考已存在的 references/经验池.md。

3.6 写入产品简介到references/

将Phase 2.6确认的产品简介内容写入 references/产品简介.md，格式：🎯这是什么 / 🚀怎么用 / 📊你能得到什么 三段。

> 🔐 Gate: 产品简介已写入references/且用户已确认 → 进下一步。不完整则补全。

Step 3：更新PM.md

参考项目根目录下的PM.md或projects/PM-TEMPLATE.md模板，填入更新内容：
- 版本历史表新增当前版本行（状态：🟡 当前）
- 旧版本标记为 ✅ 已归档
- 更新升级计划和BUG追踪

Step 4：更新CHANGELOG.md

参考CHANGELOG.md已有格式新增一条变更记录。

Step 5：同步references/

检查所有受影响的ref文件（checklist / 模板文件 / 营销方案等），不一致的同步更新。

Step 6：执行用户自定义工作流（如有）

读取 data/config/user-workflows.md：
- 如果文件存在且包含有效步骤 → 按文件中定义的步骤顺序执行
- 如果文件不存在或仅含注释 → 跳过此步

> 🔐 Gate: user-workflows.md 包含有效步骤时全部执行完毕 → 进下一步。否则直接跳过。

Step 6B：评测验证（仅升级时执行）

> 带着行为证据上线。用评测验证新版本确实优于旧版本。

1. 读取 references/评测用例.md，构建hero request set（代表性查询集）
2. 用当前评测用例集分别对"旧版本内容"和"新版本内容"做对比:
   - 正例是否都能正确触发/响应
   - 负例是否都不会误触发
   - 输出是否比旧版本更准确
3. 如果新版本在hero request set上表现不及旧版本 → 退回修改，不发布

> 如果没有评测用例文件，可以跳过此步，但告知用户下次建议先建评测。

> 🔐 Gate: 新版本在hero request set上表现 ≥ 旧版本 → 进下一步。

Phase 4：自检Review

必须逐项对照验收。 问题修复 → 回Phase 3修改 → 重新Review。循环直到全部通过。

检查维度：

4.1 华为硬校验

• name = 目录名（英文）
• SKILL.md 行数 ≤ 500行
• 无危险命令（rm -rf /、chmod 777、curl | bash等）
• 无硬编码凭据（API密钥、token、密码等）

4.2 华为软校验

• description 以"Load when"开头 ≤ 300 tokens
• 内容一致性：description功能描述与SKILL.md实际操作完全一致
• 无指令注入（不引导用户执行敏感操作）

4.3 安全红线

• 无10种指令注入：文件窃取/命令注入/任务劫持/提权诱导/逃逸诱导等
• 无代码混淆（Base64/Hex/XOR隐藏逻辑）
• 无反沙箱逻辑（检测Docker/VM/调试器环境）
• 权限最小化：不申请不需要的权限
• 无虚假描述：功能描述与实际完全一致
• 无营销诱导词：名称不含"免费/促销/最优/躺赢/最好"等
• 无侵犯知识产权：不使用其他品牌商标暗示官方关系

4.4 设计质量

• 用了合适的Pipeline模式？有Gate？
• 有Gotchas（踩坑点）？踩坑点是真实经验还是通用常识？
• 正文写的是判断边界而非通用流程？ 砍掉了模型已知的标准流程？
• 用了scripts/放确定性逻辑？ 模型不自己写重复代码？
• references/有条件加载？ 不满足条件就不读？
• 版本号正确：_meta.json和module.json一致

> 🔐 Gate: Checklist全部打勾 ✅ → 进下一步。

Step 7：生成营销方案（仅创建时执行）

参考 references/营销方案模板.md，写一份轻量级营销方案存入项目文件夹：

skills/<项目名>/references/营销方案.md

内容包括：

Step 8：打包 dist/

cd <工作目录>
zip -r "skills/<项目名>/dist/<项目名>-v新版本号.zip" "skills/<项目名>/" -x "skills/<项目名>/dist/*" "skills/<项目名>/archive/*"

> 🔐 Gate: 包名包含版本号 + archive/和dist/未打包进去 → ✅ 完成

Step 9：通知用户

1. ✅ 完成内容 — 创建/升级了什么
2. 文件清单摘要（各文件位置和用途）
3. 当前版本和状态
4. 下一步建议（上传/测试/推广）

首次运行：初始化用户工作流配置

> 当本Skill首次在当前工作空间被调用时（没有检测到 data/config/user-workflows.md），自动执行初始化。

mkdir -p data/config

然后主动问用户：

> "首次使用，有没有个人专属流程需要在创建/升级Skill时自动做？如：项目创建后同步更新某个计划文件、升级后自动同步版本号到总表、打包后自动上传到平台。如果没有也没关系，后续不再问。"
>
> 如果用户有 → 结构化写入 data/config/user-workflows.md。没有 → 空模板+标记初始化完成。

领域知识

标准Skill项目结构及版本规范

详细结构见 references/design-patterns.md 和 references/file-templates.md。

版本号规范： v主版本.次版本.补丁（重构→主版本，新增→次版本，修复→补丁）

设计模式组合规则： Pipeline里嵌Reviewer / Pipeline前加Inversion / Generator前加Reviewer。全量组合：Pipeline+Gate+Inversion+Reviewer+Generator

⛔ 安全红线（绝对禁止）

1. ❌ 禁止不归档直接改 — 旧版不回退就无法回溯
2. ❌ 禁止跳步 — Pipeline各Step必须顺序执行
3. ❌ 禁止项目没有PM.md — PM和CHANGELOG版本也必须一致
4. ❌ 禁止将data/目录打包进dist/ — data/含用户个人数据
5. ❌ 禁止硬编码凭证、危险命令、指令注入、代码混淆、反沙箱<br>6. ❌ 禁止营销诱导词（"免费/最优/躺赢/最好"）和侵犯知识产权
6. ❌ 禁止硬编码任何用户环境特有关联: Skill 要上传平台给其他用户安装使用，所有文件(包括SKILL.md中的路径引用/依赖检查逻辑/脚本路径)不能硬编码当前开发环境特有的内容。路径通过环境变量/相对路径/通用发现机制(which/command -v/find等)处理，而不是写死安装目录。
7. ❌ 禁止通过写死路径检查依赖是否存在: 检查依赖 Skill 的安装情况时，必须用 which/command -v/环境变量等方式，不假设"用户一定放在~/skills/xxx/"

🧑🤝🧑 与人协作

References（按需读取，不进上下文）