Skill Creator Optimized Pro

将自然语言需求、业务流程、既有技能草稿或旧版技能包，转化为结构标准、内容完整、可安装、可审计、适合 SkillHub 发布的高质量 Skill 包。

0. 北极星目标

交付一个能被正确触发、能稳定执行、能通过静态校验、能被他人安装复用的 Skill 包，而不只是写一段看起来像提示词的文档。

执行时始终围绕三件事判断质量：

1. 触发准确：description 同时说明能力、使用场景、触发表达和排除场景。
2. 执行稳定：SKILL.md 给出目标、边界、流程、输出契约、异常处理和验证标准；复杂资料按需放入 references/、scripts/、assets/。
3. 交付可信：YAML 可解析、结构可安装、引用路径存在、无临时文件、版本与说明一致、附带测试 Prompt 与优化说明。

1. 何时使用 / 何时不要使用

使用本 Skill

当用户提出以下任一意图时使用：

• 创建、新建、生成、封装一个 Skill / 技能包。
• 新手引导 / 入门 / 第一次做 Skill / 一步步教我 / 从零创建。
• 优化、重构、审计已有 SKILL.md 或 .zip 技能包。
• 补齐或修复 YAML front matter、description、触发词、排除条件。
• 把 SOP、业务流程、提示词、专家方法论、工作规范沉淀为可安装 Skill。
• 为 SkillHub 发布准备 README、AGENTS、package metadata、质量检查、上架材料与打包文件。

不使用本 Skill

• 用户只是要一次性改写提示词，不需要形成可复用技能。
• 用户只是普通写作、代码开发、数据分析，且没有“沉淀为 Skill”的要求。
• 用户要求安装或执行来源不明、含高风险命令的 Skill；先做安全审计，不直接运行。

模式路由（先选模式，再开工）

不确定时：先问「要新手一步步引导，还是直接按专业流程生成？」；用户不选则对模糊需求默认新手引导。

2. 强制原则

1. 先定边界，再写正文：如果一个 Skill 同时解决多个不相关任务，拆分或建立任务路由，不把所有内容塞进一个入口。
2. Description 是触发器：必须写清“做什么 + 什么时候用 + 典型表达 + 不该用的情况”。避免“帮助处理文档”“提升效率”这类空泛描述。
3. SKILL.md 只放高频必要信息：主体建议保持精简；长模板、示例、规范、测试集放入 references/ 按需读取。
4. 能脚本化就脚本化：格式校验、目录初始化、打包、静态检查、批量转换等确定性动作，优先放入 scripts/ 或明确执行校验逻辑。
5. 完成标准可打勾：每个质量要求必须能被检查，而不是“更专业”“更完整”这类软描述。
6. 文件是权威来源：优化既有技能包时，先读取当前文件，不依赖记忆中的旧版本；修改后重新验证。
7. 安全优先：不得生成包含密钥、隐私、恶意命令、绕过权限或破坏性操作的技能包。

3. 工作流

Phase 0 — 新手引导（条件触发）

若命中新手引导模式：

1. 读取 [references/beginner-onboarding.md](references/beginner-onboarding.md)。
2. 使用 templates/beginner-intake.md 按 1→6 步推进；展示进度 n/6。
3. 每步复述确认；用户可随时「跳过引导」。
4. 第 6 步确认后，按所选 L1/L2 生成最小包，再进入 Phase 4 校验（可跳过深度门禁）。
5. 用新手汇报模板收尾，并给出 1 条应触发、1 条不应触发的试用话术。

未命中新手模式则跳过 Phase 0，直接 Phase 1。

Phase 1 — 需求诊断

收集并确认以下信息；缺失时给出合理默认值并标注假设：

如果用户给的是已有包，先解包审计：读取 SKILL.md、README、元数据、references/、scripts/，列出问题后再优化。

Phase 2 — 结构设计

按复杂度选择结构：

默认目录：

skill-name/
├── SKILL.md
├── README.md
├── package.json 或 _meta.json（按平台需要）
├── references/
├── scripts/
└── assets/

只创建有实际用途的目录；空目录需要 README 占位说明。

Phase 3 — 编写或优化 SKILL.md

SKILL.md 必须包含：

1. YAML front matter：至少 name、description；发布级建议补充 version、author、tags。
2. 目标：一句话说明这个 Skill 要交付什么。
3. 使用边界：何时用、何时不用。
4. 输入检查：需要用户提供哪些材料，缺失时如何处理。
5. 工作流：按阶段给出可执行动作和关键决策分支。
6. 输出契约：结构、格式、文件命名、交付方式。
7. 质量门禁：可验证 checklist。
8. 异常处理：缺文件、YAML 错误、引用缺失、打包失败、需求冲突时如何恢复。
9. 资源索引：什么时候读取哪些 references/ 或脚本。

写法要求：

• 使用动作动词：读取、检查、生成、验证、打包、汇报。
• 对关键规则解释原因，帮助 Agent 在新场景中迁移。
• 给必要自由度：规定目标、约束和验收标准；不要把所有微步骤写死。
• 给正反触发测试 Prompt，尤其是“不应该触发”的反例。

Phase 4 — 质量验证

交付前执行静态检查：

• YAML front matter 存在，且可被 YAML 解析。
• name 使用小写字母、数字、连字符，避免空格和中文。
• description 非空、具体，包含触发场景和排除边界；含英文冒号加空格等易破坏 YAML 的内容时使用引号或块标量。
• SKILL.md 中引用的本地文件路径存在。
• README、package metadata、SKILL.md 的名称和版本一致。
• 无 .DS_Store、上传残留、日志、临时文件、密钥文件。
• zip 根目录结构正确：解压后应直接得到技能目录或技能文件集合，不混入无关父目录。

必要时读取 [references/qa-checklist.md](references/qa-checklist.md) 执行完整门禁；发布级任务还可读取 [references/skill-scorecard.md](references/skill-scorecard.md) 做维度诊断（不产出等级、不参与发布裁决），发布结论只由 Gate 给出。

两个域的血缘：validate-skill.py 同时给出结构域与安全域的 Gate 判定；security-scan.py 只跑安全域，score-skill.py 只做诊断，两者都不决定是否放行。

自动化命令：

python scripts/validate-skill.py <skill-dir> [--json] [--depth]                 # 结构域校验 + 安全域判定（Gate）
python scripts/security-scan.py <skill-dir> [--json] [--scope dist|all]         # 安全域单独跑
python scripts/score-skill.py <skill-dir> [--json]                              # 维度诊断，不产等级
python scripts/report-render.py <skill-dir> --out <output-dir>                  # 渲染人可读报告
python scripts/bump-version.py <new-version>                                    # 版本五处一次回写
python scripts/pack-skill.py <skill-dir> --out <output-dir> [--force]           # 唯一发版入口，恒校验

validate-skill.py 检查 YAML front matter、推荐目录、Markdown 本地引用、description 长度、禁用词、临时产物、版本/名称一致性，并给出结构域与安全域的 Gate 判定；--depth 启用专业深度门禁（source-map / playbook / phrasebook / PRD 审计脚手架）。security-scan.py 是安全域的独立入口，输出 findings 与 coverage。score-skill.py 产出各维度诊断分，不产出等级、不参与放行，Gate 失败时不计算任何分数。pack-skill.py 是唯一发版入口，恒校验且两个域都查（结构域 + 安全域），任一失败即拒绝打包。脚本检查通过不代表人工评审通过；触发边界、可执行性和交付契约仍需人工确认。

Phase 5 — 打包与交付

1. 将最终技能包写入用户指定输出目录。
2. 生成优化说明，列出：解决的问题、设计决策、文件清单、验证结果、后续迭代建议。
3. 使用 scripts/pack-skill.py 重新打包 .zip（禁止手工塞入临时文件）。
4. 汇报任务是否完全完成；如未完成，说明阻塞点和可选方案。
5. 若启用了 §7：必须分别声明「结构合规」与「专业深度」是否达标。

4. 输出契约

标准交付至少包含：

<skill-name>.zip
methodology-and-optimization-report.md
optimized/<skill-name>/SKILL.md
optimized/<skill-name>/README.md

最终回复中说明：是否完成优化和验证；优化版 zip 链接；方法论报告链接；关键变更摘要；后续可选优化。

安全门禁与检测边界

security-scan.py 的安全规则共 15 项，本版全部实现（P0 字面量层 9 项 + P1 AST/path/文件层 6 项）。始终以 coverage.implemented / coverage.unimplemented 的实时输出为准，不得写死比例。

已验证覆盖（15 项）：提示注入短语；硬编码凭据与私钥（OpenAI / GitHub / AKIA / JWT / PEM 私钥头）；危险命令字面量（递归删除系统或用户目录、管道直灌远程脚本、提权后接命令）；全局可写权限；递归所有权变更；动态构造命令（拼接 / f-string / argv 常量段命中危险骨架）；不安全反序列化（pickle / marshal / dill / shelve / 非安全 Loader 的 yaml）；运行时依赖安装（安装命令字面量与 package.json 安装期钩子）；供应链风险点（自定义镜像源与未锁定依赖）；路径越界（穿越 / 家目录 / 绝对路径字面量与解压复核）；外联行为（HTTP 客户端调用，按 allowed-domains 声明裁决）；已知敏感文件名（.env、*.pem、id_rsa）。完整模式清单见 references/security-rules.md，正文不复写字面量，避免规则样例污染 Gate。

全部实现 ≠ 全部风险已排除：检测停留在模式与语法位置层面；运行时行为、动态拼接且无静态片段可判的参数、变体与编码形态（Base64 包装、Unicode 混淆、图片/网页正文等间接注入载体）不在检测范围内，仍需人工审查。每条规则各自的边界见规则表「未命中时说明什么」列。

三条硬原则：
1. 未检测 ≠ 通过 —— 规则未实现时该维度结论是「未检测」，不得静默计为通过。
2. 未命中 ≠ 已验证安全 —— 未覆盖的攻击面由披露与人工复核承担，不通过削弱阻断来体现。
3. 凭据可忽略、外联可声明、命令与注入不可放行。

按此口径，对外只能写「本包 15 项检测未检出 + 各规则边界清单 + 人工复核结论」，不能写「本包安全」「已通过安全检测」或「安全扫描已上线」。

5. 异常处理

• 缺少输入文件：停止并请用户上传；不要凭空构造既有包内容。
• YAML 解析失败 / 引用文件缺失：先修 front matter 再继续优化；引用缺失优先补齐，确不需要则删除引用。
• 需求过宽：建议拆分为多个 Skill 或增加任务路由。
• Gate 失败：结构域或安全域任一失败即不得打包发布；列出失败项，修复后重跑验证。
• 工具/权限失败：停止硬跑，汇报卡点、已尝试内容、失败原因和替代方案。

6. 资源索引

• 需要新手引导/入门带练时，读取 [references/beginner-onboarding.md](references/beginner-onboarding.md)，并用 templates/beginner-intake.md 收集答卷。
• 需要完整创建/优化流程时，读取 [references/workflow.md](references/workflow.md)。
• 需要发布前门禁时，读取 [references/qa-checklist.md](references/qa-checklist.md)。
• 需要处理失败和恢复路径时，读取 [references/error-handling.md](references/error-handling.md)。
• 需要保存长期任务进度时，读取 [references/progress-template.md](references/progress-template.md)。
• 需要方法论背景时，读取 [references/methodology.md](references/methodology.md)。
• 需要维度诊断口径或批量诊断时，读取 [references/skill-scorecard.md](references/skill-scorecard.md)（只诊断，不产出等级）。
• 需要本技能触发回归或生成测试集时，读取 [references/test-prompts.md](references/test-prompts.md)。
• 需要安全规则明细（15 项 ID、severity、是否可放行）时，读取 references/security-rules.md；需要平台展示字段（display_name 等）时，读取 [references/platform-fields.md](references/platform-fields.md)。
• 需要报告输出样式规范时，读取 [references/output-style.md](references/output-style.md)；需要回归测试基线时，读取 tests/BASELINE.md。
• 需要专业深度门禁时，读取 [references/source-inheritance-depth-gate.md](references/source-inheritance-depth-gate.md)，并复制 templates/source-map.md、templates/playbook.md、templates/phrasebook.md、templates/prd-implementation-audit.md；填写示例见 examples/source-map-filled-sample.md。
• 需要 SkillHub 上架材料时，读取 [references/skillhub-listing-review-pack.md](references/skillhub-listing-review-pack.md)、[references/listing-copy.md](references/listing-copy.md)，并按需读取 examples/before-after-diff-case.md、examples/evaluation-run-log-sample.md。
• 需要代理执行红线时，读取 AGENTS.md。
• 需要按类型快速起草新 Skill 时，读取 examples/README.md 的路由表并只加载匹配的 1 个示例。
• 需要复制为独立可安装技能时，读取 minimal-skills/README.md，复制后必须阅读对应 references/domain-rules.md；minimal 默认视为脚手架，不是生产完成态。
• 需要跑 Gate 时，运行 scripts/validate-skill.py（结构域 + 安全域；深度任务加 --depth，批量审核加 --json）。
• 需要单独扫安全域时，运行 scripts/security-scan.py；诊断用 scripts/score-skill.py（维度诊断，不产等级）；渲染报告用 scripts/report-render.py（--extras 深度报告、--html 单页聚合）；版本五处回写用 scripts/bump-version.py；实测用 scripts/run-eval.py（子代理执行结果经 --import 导入复算）；迭代防回退用 scripts/ratchet.py。
• 需要洁净打包时，运行 scripts/pack-skill.py <skill-dir> --out <output-dir>（--force 允许覆盖同名 zip）；它是唯一发版入口，恒校验两个域；解包审计用 scripts/unpack-skill.py；平台字段用 scripts/platform-fields.py；新技能起步用 scripts/init-skill.py；批量对比用 scripts/batch-audit.py；触发词曝光体检用 scripts/exposure-check.py。

7. 专业内容深度升级规则（深度定制）

当用户提供了研究资料、PRD、评估报告、访谈记录、案例库或前期沉淀，并要求生成/优化 SkillHub 技能包时，必须把这些源材料视为能力内核，而不只是背景参考。禁止只输出结构合规、模板很薄的“空壳包”。

在 Phase 2 结构设计后、Phase 4 验证前，必须执行本节；模板见 templates/，细则见 [references/source-inheritance-depth-gate.md](references/source-inheritance-depth-gate.md)。

7.1 强制源材料继承审计

在生成或优化技能包前，必须建立 source-map.md 或等价内容映射表，至少覆盖：

如果源材料覆盖率低于 80%，不得声称已经完成专业优化；必须继续补齐或明确降级为“结构样包”。

7.2 内容密度门禁

发布级专业 Skill 不只检查 YAML、ZIP 和目录，还必须检查内容厚度：

• 至少包含一份方法论/理论转译文件（说明“为什么这样判断”）与一份实践 playbook（说明“遇到不同场景怎么做”）。
• 表达型 Skill 必须包含话术库或案例库，覆盖正例、反例、灰区处理；modules/ 每个核心模块应包含判断标准、执行步骤、输出示例、失败/拒答处理；SKILL.md 可以精简，但内部知识库不得因此变薄。

7.3 PRD 落地率检查

如果前期存在 PRD，必须逐条检查：

1. 用户角色是否转为触发场景；
2. 核心功能是否转为模块或 playbook；
3. MVP 范围是否体现在路由与边界；
4. 风险控制是否转为安全策略和测试用例；
5. 指标与验收是否转为 QA 清单。

未落地项要写入 qa/prd-implementation-audit.md，不能在最终汇报中跳过。

7.4 话术与案例资产要求

当 Skill 的价值依赖“怎么说、怎么写、怎么回应”时，必须至少沉淀：

• 典型触发语、推荐回应、不推荐回应、为什么这样改、适用边界、升级/拒答策略，六项缺一不可。

禁止只写“给出温和版、坚定版、正式版”而不提供真实示例。

7.5 最终汇报必须区分两种完成

• 结构合规完成：包能安装、能触发、能通过上传校验。
• 专业能力完成：研究资产已转译、话术/案例/判断规则齐备、PRD 已落地、测试覆盖关键场景。

如果只达到结构合规，不得说“专业优化完成”。