Skill创作发明家

name: mu-skill-creator version: 3.7 description: "Skill创建与质量门控，含53项10层审计模型。触发词：创建skill、skill创建、skill审计、质量审计。不适用：skill发布、生态体检（用mu-skill-auditor）" tags: Skill开发,质量门控,发布流程,三层模型,组织规范,工作流 visibility: public

IRON LAW:1改完 Skill 必须立即跑 skill-audit 全绿才算完成,禁止"目测没问题"就交付;2description 只给 Agent 读(触发器),intro 只给人看(Skill市场简介),两者不可混用;3安全扫描未通过禁止 push,人员/组织/薪酬/职级信息禁止进任何 Skill 文件;4IRON LAW 必须是该 Skill 的业务专属约束,禁止只写行数/凭据等通用套话;5行数以效果为第一原则,≤300行是预算上限不是拆分目标——禁止为了让数字好看而拆分,只有"拆分后仍能一次执行不降级"才可以拆,拆完必须验证拆分后指令仍可被完整执行,做不到就保留超行数也不拆(L1-5行数项优先级低于L2-1逻辑闭环/L10-1可验证性)。

§1 Motivation：为什么需要这个 Skill

Skill 质量劣化有三个系统性失效模式，所有规则都针对它们：

1. 规则遗忘——小改动不检查→质量劣化在缝隙中发生。根因：没有强制审计闭环，"目测没问题"成了默认行为。
2. 规则冲突——新增规则与旧规则矛盾→Agent 执行时选错。根因：规则分散无全局校验，改一处忘同步另一处。
3. 规则膨胀——什么都想管→300行溢出→有效指令被挤出 context。根因：缺少拆分约束和优先级判断，"写了=管了"的幻觉。

三条共同根因：缺少工程脚手架，不是 Agent 能力不足。每条规则都应可追溯到「哪次事故催生了它」。

§2 生态分工

§3 核心设计决策

三决策解释了「为什么用这个架构」，每条对抗至少一个失效模式：

1. 三层模型 > 单文件——L1(description)始终加载、L2(SKILL.md≤300行)激活时加载、L3(references/)按需加载。WHY：控制 context 膨胀，对抗规则膨胀（失效3）。

L1：唯一触发机制，倾向"宁多触发别漏"(漏触发=Skill不存在，误触发可纠正) L2：≤300行(官方建议500，取300留余量)，引用仅一级(WHY:超注意力预算→指令被挤出)。⚠️行数是预算上限不是拆分目标，拆分用对刀:效果不减才可拆——需多一次read才能执行=拆分即质量降级。禁止为了单纯让行数好看而拆分；判断标准不是"数字降下来了没"，而是"拆完之后 Agent 能不能一次把该做的事做完不降级"，做不到就宁可保留超行数(见IRON LAW 5) L3：每主题一文件，超100行加索引

2. 阶段门控 > 线性流程——每个阶段有独立入口/出口条件，未满足不可跳过。WHY：对抗规则遗忘（失效1），门控是结构约束不是"建议"。

3. 审计脚本+清单 > 人工目测——自动化扫描+53项10层逐项确认。WHY：目测=遗漏，脚本=可重复。对抗规则遗忘+规则冲突（失效1+2），跨章节一致性只能靠脚本校验。

§4 设计原则

分正向（怎么做好）和防御（怎么防坏）两个视角，适用于所有 Skill。每条原则下方标注对应的 AP 反模式。

正向设计

1. 状态外置优于上下文累积：进度写文件不写对话，fresh session 注入状态（WHY:上下文累积=认知死循环主因 | 对应:AP-12循环无终止）
2. 执行与评估分离：干活的不评判进度，编排层基于量化指标判断（WHY:自评=运动员兼裁判 | 对应:AP-5无完成门控）
3. 方向差异化优先于深度挖掘：多候选方向时优先增加多样性（WHY:多样性是逃出局部最优的唯一路径 | 对应:AP-12循环无终止——同一方向反复=停滞）
4. 每次迭代必须有可验证产出：不是「做了」而是「产出了什么、能验证什么」（WHY:无产出=停滞前兆 | 对应:AP-6不可验证指令）

防御设计

5. 规则必附事故来源：IRON LAW/Gotcha/AP 每条补「来自XX事故」（WHY:理解事故>死记禁止令 | 对应:AP-19规则只有MUST没WHY）
6. 职责隔离靠约束不靠自律：不该做X是让结构上做不了，不是写「别做」（根因:Guardian越界→上下文污染 | 对应:AP-7无Confirmation Gate——用门控而非"建议确认"）
7. 假设每层都会失败：单点可能挂，确保有独立恢复路径（根因:Cron超时无人知 | 对应:AP-12循环无终止——无终止条件=单点失败无恢复）
8. 停滞检测用量化指标：用可度量信号判断卡住，不靠主观判断（根因:6/17串行超时 | 对应:AP-12循环无终止——stale_count是量化终止条件）
9. 已知局限必须诚实披露：SKILL.md加## 已知局限段（WHY:沉默=误导 | 对应:AP-6的镜像——不只验证"做对了什么"还要声明"做不了什么"）

停滞检测规则

适用于所有含循环/迭代/Cron的 Skill。

"换结构不是调参数"：当任务在同一框架内反复停滞，决定性收益来自修正环境/结构约束本身，不是在现有框架里更用力调参。

§5 创作工作流

自动触发：新建Skill→完整流程(阶段1→8) | 修改→10层审计模型+行数+AP | 发布前→完整检查+安全扫描 禁止：改完不audit就提交 | 只目测不逐项过Checklist | 用系统自带版/app/skills/skill-creator/替代本Skill

阶段 1:理解需求

入口：收到Skill创建/优化需求

操作：

• 从对话中提取：若当前对话已包含完整工作流，优先从聊天历史提取——工具链、步骤、纠正点、I/O格式，提取后请用户确认
• 收集 3+ 输入→输出示例(真实场景,不是假设)
• 明确 Skill 类型：工具封装 / 流程引导 / 知识编码 / 检阅类
• 确认不适用场景(description 里必须写)

出口：有明确输入输出示例清单≥3条

阶段 1.5:找实践案例(非工具封装类必做)

入口：阶段1完成,且非纯工具封装 操作：黄金案例3+/失败案例5+/有效-无效对比≥1组 出口：有案例清单,或"工具封装型,已跳过"

阶段 2:规划

入口：阶段 1(含1.5)完成

操作：

• 选意图模式：工具封装 / 生成器 / 检阅器 / 流水线 / 路由分发
• 选架构模式(可组合)：顺序工作流 / 多MCP协调 / 迭代精化 / 上下文路由 / 领域知识嵌入
• 列文件树(SKILL.md + references/ + scripts/ + assets/)
• 长流程Skill(≥4阶段)：定义 progress.json 字段（状态外置，对抗context压缩后丢失进度）

出口：文件树清单已确认,架构模式已选定

阶段 3:写 L1(description)

入口：阶段 2 完成

操作：

• 写触发词+使用/跳过条件,双引号单行≤1024字符
• 禁止：emoji、工作流描述、宣传语（放intro）(WHY:description是路由触发器不是广告)
• 必须：含"不适用"场景(WHY:明确边界防误触发)
• ⚡ Pushy 原则：AI 助手系统性偏向undertrigger，加「即使没提X，只要提到Y也要用」

格式："做什么功能。触发词:词1、词2、词3。不适用:场景描述(用哪个替代)。"

阶段 4:写 L2(SKILL.md)

入口：阶段 3 完成

操作：

• IRON LAW按需添加：有高频违规风险时才写，内容必须是业务专属约束，不写比写套话强(WHY:套话占行数不激活场景)。条数上限6条：超过6条需逐条审核是否真正"违反即出大问题"，非铁律级的规则下沉到工作流步骤或Gotchas中(WHY:条数膨胀→Agent注意力稀释→全部失效，来自mu-redskill-intro实战:新增3条经验被错误提升为IRON LAW)
• 如有IRON LAW，放frontmatter之后第一位(WHY:Agent第一眼=硬约束)
• 每个阶段：编号+入口条件+操作步骤+出口条件
• 改动类→Confirmation Gate(实施前用户确认)
• 输出前→Pre-Delivery Checklist(可逐项打勾)
• 行数≤300；超出优先判断"能否拆分而不降效果"，能则移到references/，不能则保留超行数不硬拆(WHY:超注意力预算→指令被忽略；但拆分本身若导致多跳read/执行链断裂，效果损失比行数超标更严重，见IRON LAW 5)
• Explain WHY：重要规则附WHY。纯MUST/NEVER/ALWAYS=yellow flag
• Gotchas section：环境里反直觉事实集中写，单位token价值高；**但Gotchas是"速查结论"不是"事故日志"——单条超3-5行的现象/根因/修复完整叙述、或条目>10条/占全文>40%，必须按分层处置(AP-34/L1-8)：①删除(结论已被IRON LAW/工作流覆盖)、②上浮固化("该怎么做"的操作结论→提炼一句进对应阶段步骤)、③下沉("某模板/环境的实现坑"→移到references/troubleshooting.md，主文件只留"症状→查阅"索引表)。判据:常规执行时需读它=上浮，只在改特定东西时才需=下沉，别处已说=删
• Specificity to fragility：越不可逆越精确(给命令/模板)；越灵活越说明意图让Agent自主发挥
• 子Agent执行规范(流水线/多步骤必做)：SKILL.md含## 子Agent最小执行规范(≤30行)：必读文件+硬Gate+格式约束+禁止行为
• 已知局限段：SKILL.md加## 已知局限，声明什么做不到/什么条件退化(WHY:沉默=误导)
• 版本历史不入SKILL.md：SKILL.md只留1行版本号+CHANGELOG.md链接(如当前版本 vX.X，完整历史见 references/CHANGELOG.md)。版本历史是溯源信息，不参与任何生成/路由/决策，占行数=纯浪费注意力预算(WHY:mu-visual-card曾用35行版本历史占615行中的5.7%，迁移后省至1行)

出口：wc -l SKILL.md≤300，有Checklist(IRON LAW按需)

frontmatter字段：name(必填,小写+数字+连字符,与目录名一致) | description(必填,≤1024字符,含触发词+不适用+pushy) | compatibility(可选) | metadata(可选)

阶段 5:写 L3(references/)

入口：阶段 4 完成

操作：每主题一文件 | 引用仅一跳(禁A→B→C)(WHY:多跳=token膨胀+遗忘指令) | 底部建索引

出口：所有引用文件存在，SKILL.md有索引

阶段 6:可验证性审查

入口：阶段 5 完成

操作：逐条审查指令，确认可yes/no判断。❌"写高质量代码"→✅"lint通过无error"

出口：无主观指令，全部可yes/no判断

阶段 6.5:Eval 测试(可选但推荐)

入口：阶段 6 完成

操作(详见references/quality-gates.md)：写2-3个prompt→evals/evals.json，spawn两组(cleanup=delete，最多4并发)，accuracy≥85%。⚠️定性类Skill(写作/面评/引导)豁免量化，改用人工审查(WHY:强行量化=造假断言)

出口：evals.json存在且accuracy≥85%；或标注"已跳过"/"定性类,人工审查"

阶段 7:触发词优化

入口：阶段 6.5 完成(或跳过)

操作(详见references/quality-gates.md)：扫禁止词(analyzer/helper/tools/assistant/单独skill/短动词/≤2字) | 中英文触发词5+种 | 测试10+10触发/不触发，accuracy≥85% | 调试:问Agent「什么时候用这个Skill?」——回答不准=description需优化

出口：无禁止词，中英文覆盖，accuracy≥85%

阶段 8:发布(组织四步)

入口：阶段7完成+木老师明确授权发布

⚠️ Confirmation Gate:发布前必须获得木老师明确的"可以发布"指令

完整流程见references/publish-workflow.md： 1.安全扫描(人员/凭证/内网/appkey)→ 2.frontmatter校验→ 3.打包+说明→ 4.push到Skill市场(skill-cli push+--intro)

出口：Skill市场可搜到，安全徽章双绿，简介显示三段式intro

§6 安全硬规则

禁止进任何Skill文件：人才标准/组织信息/角色指南/职级定义/人员信息(姓名/MIS/userID)/C4高敏数据 受限系统黑名单(禁止调用API)：hr/ehr/mthr/hc/ov/goal/okr/huoshui/bole/talent/hrmdm.example.com + restricted-hr.example.com 用户态数据隔离：本地已安装列表/用户偏好/快照/推荐历史等个性化文件禁止随Skill发布，必须.skillignore排除+SKILL.md声明"首次使用自动生成"(根因:发布者数据污染下载用户行为) 正确做法：Skill只写"运行时现读"指令(documentId/知识库链接)，内容不进Skill。违反=安全泄密+发布拦截

§7 Anti-Pattern 清单(AP-1~34)

完整说明+修复示例见references/quality-gates.md。每条标注根因事故和对应的设计原则。

AP-23~32: 代码质量反模式(eval/exec/异常宽度/调试残留/废弃API/契约不一致/import不匹配/无fallback/路径替换/遍历无上限/.gitignore缺失)，详见references/quality-gates.md AP-33: SKILL.md留版本历史——版本历史是溯源信息不是执行指令，占行数挤占注意力预算却无任何生成/路由作用。修复：SKILL.md只留1行版本号+CHANGELOG.md链接，历史详情移到references/CHANGELOG.md。根因：mu-visual-card v12.6版本历史占35行。对应§3决策1(三层模型控制context膨胀) AP-34: Gotchas/踩坑记录堆积膨胀——Gotchas从"反直觉事实速查"退化成"逐条事故日志"(现象→根因→修复完整叙述)，条目/行数失控占据L2主文件。它是AP-33的同构兄弟：都把"溯源/调试类信息"堆进主文件，占注意力预算却不参与生成/路由/决策。修复按分层处置(见§5阶段4Gotchas决策树)：结论已被IRON LAW/工作流覆盖的直接删(=AP-14冗余)；"该怎么做"的操作结论上浮固化进对应阶段；"某模板/环境的实现坑"下沉到references/troubleshooting.md，主文件只留"症状→查阅"索引。判据一句话:常规执行时需读它=上浮，只在改特定东西时才需=下沉，别处已说=删。根因：某开源宣传类Skill，27条Gotchas占389行/全文66%，主文件593行。对应§3决策1(三层模型控制context膨胀)+§1失效3(规则膨胀) 失效模式→AP: 遗忘→3/5/8/17/25 | 冲突→4/14/16/18/27 | 膨胀→1/9/13/15/20/31/33/34 | 跨模式→6/7/10/11/12/19/23/24/26/28/29/30/32

§8 质量审计：10层模型

运行：bash scripts/skill-audit.sh <skill-name>（在 Skill 目录下执行） 支持环境变量 SKILL_BASE 指定 Skills 根目录（默认从脚本位置自动探测） 完整说明见 references/quality-gates.md

逐项清单(🔍=脚本可查,👤=人工判断)

L1文档结构: 🔍L1-1 IRON LAW(frontmatter后,业务专属,≤6条——超6条逐条审核是否铁律级,非铁律下沉到工作流/Gotchas) | 🔍L1-2 desc(单行无emoji+触发词+不适用) | 🔍L1-3 intro(三段式≠desc,tags≥6) | 🔍L1-4 name(小写+连字符=目录名) | 🔍L1-5 行数≤300(脚本只报数字,超标不等于判红——需先按IRON LAW 5评估能否拆分而不降效果,做不到就标注"已评估-保留超行数"视为通过) | 👤L1-6 refs索引完整 | 🔍L1-7 版本历史不入SKILL.md(只留1行版本号+CHANGELOG链接,AP-33) | 🔍L1-8 Gotchas未膨胀(踩坑段###条目≤10且占全文≤40%,超标按分层处置删/上浮/下沉到troubleshooting.md,AP-34;同L1-5为信息告警不直接判红) L2架构一致性: 👤L2-1 逻辑冲突(新旧矛盾/因果闭环/约束可满足性:对同一度量的所有数值约束取数学交集，验证交集非空——如面积上限≤X%和下限≥Y%是否X≥Y；不同约束作用于有交集的集合时组合效果是否可行) | 🔍L2-2 阶段编号+入口/出口+可验证 | 👤L2-3 跨章节(原则↔AP↔事故) | 👤L2-4 交互一致(多模式无矛盾) | 👤L2-5 版本号匹配 L3代码质量(scripts/+assets/可执行文件): 🔍L3-1 API契约(签名↔调用) | 🔍L3-2 无eval/exec | 🔍L3-3 异常宽度(无bare except) | 🔍L3-4 无调试残留 | 🔍L3-5 无废弃API | 🔍L3-6 shebang+set-euo | 👤L3-7 硬编码已参数化 | 👤L3-8 功能退化 L4跨文件一致性: 👤L4-1 模板双源(不双存) | 👤L4-2 信息冗余(清单未被覆盖) | 👤L4-3 共享模式一致(utils用法) | 🔍L4-4 数值一致性(同一语义量的所有引用点——含同文件不同章节——尺寸/字号/坐标/色值/百分比统一；版本迭代后旧章节数值未同步=此项不通过) L5文档↔代码(scripts/+test-output参考实现): 🔍L5-1 参数表一致(SKILL↔CLI) | 🔍L5-2 功能路由完整(均有实现) | 👤L5-3 参考实现正确性(示例代码/模板/SVG语法正确且与文档对齐) L6依赖完整性(scripts/): 🔍L6-1 import↔requirements匹配 | 👤L6-2 技术栈表一致 | 🔍L6-3 可选依赖有fallback L7文件卫生: 🔍L7-1 僵尸文件(refs有引用) | 🔍L7-2 断链(引用均存在) | 👤L7-3 路径孤儿(改名同步) | 👤L7-4 用户态未混入 | 🔍L7-5 .gitignore(scripts/时) | 🔍L7-6 无平台产物 L8安全合规: 🔍L8-1 安全扫描(appkey/MIS/C4/受限系统) | 🔍L8-2 frontmatter无MIS(AP-21) | 🔍L8-3 _meta.json已排除(AP-22) L9健壮性&降级: 👤L9-1 降级链(外部依赖有处理) | 👤L9-2 改动类→Confirm Gate | 👤L9-3 流水线→子Agent规范 | 👤L9-4 数据量限制(AP-13) | 👤L9-5 大文件截断(AP-15) | 🔍L9-6 路径安全(splitext) | 🔍L9-7 遍历上限 L10内容质量: 👤L10-1 可验证性(yes/no) | 🔍L10-2 AP清零(无AP-1~34) | 👤L10-3 文案(无错别字) | 👤L10-4 已知局限 | 👤L10-5 停滞检测(stale_count) | 👤L10-6 边缘输入覆盖(极短/极长/空输入/非预期语言等边界条件是否有处理指引或在已知局限中声明)

§9 已知局限

1. 53项10层模型覆盖文档/代码/安全/健壮性，不能覆盖设计品味——审计全绿≠产出优秀
2. 定性类Skill审计依赖人工判断，脚本无法量化"好"
3. 触发词受Agent模型影响，不同模型可能表现不同
4. L4跨文件一致性(4项)和L10内容质量(6项)依赖人工判断，自动化率较低
5. 状态外置(progress.json)推荐非强制——短流程Skill无需

references/ 索引