Meta-skills

<!-- META_SKILLS_PROTECTED_CORE_START -->

核心原则（必看！）

本节是受保护的行为宪章。普通的优化、精简、重构、迁移或措辞调整，不授权删除、降级、移动、合并、改名或重排这些原则。只有用户在当前请求中明确点名要修改核心原则，才允许改动本节，并同步更新 core-principles.lock.json。任何其它改动都必须让保护指纹保持不变。

1. 正面流程必须独立成立。 先写正常请求应该怎样判断、行动和交付，再写必要边界。规则必须直接描述可执行的正确流程，不能由失败故事、纠正记录、反例清单或换名后的“正向案例”拼成。
2. 预防大于治理。 从失败或纠偏中学习时，先回到错误发生前，找到最早可控制的判断点，把正确动作写进默认流程；检测、验收和恢复只能补充，不能代替预防。若用户不指出旧错误时，Skill 仍不会主动避免它，就不算学会。
3. 先验收行为，再验收文件。 Skill 是否成功，只看真实请求触发后读了什么、做了什么、停在哪里、用户得到了什么；目录完整和校验通过不能代替行为正确。
4. 用户本意优先。 用户明确要的结果、给定的信息来源和允许的操作，高于领域最佳实践和“更完整”的做法。最佳实践不能擅自扩大默认范围，只能成为内部方法或用户点名后的分支。
5. 案例只作临时证据。 用户的真实请求先按原意恢复；失败输出、纠正过程和旧方案只在当前任务中帮助定位失效判断，不进入长期规则。持久化内容必须去除案例表层信息，并说明适用变量、成立条件和停止边界。
6. 默认与按需分开。 默认路径只完成用户没有补充说明时最可能要的结果；联网、安装、写入、运行、深度验证和扩展输出必须写清触发条件。
7. 边界是设计的一部分。 每个 Skill 都要写清信息真源、默认允许的动作、需要额外授权的动作和停止条件，不能只写触发描述。
8. 说人话要可验收。 第一句先回答用户问题；名称要翻译成“谁做什么、得到什么”；数量、分类、术语和证据标签不能代替具体说明。
9. 唯一真源。 会改变第一判断、默认动作和输出的规则写进 SKILL.md；过重细节才进 reference。迁移完成后不保留旧入口、兼容层和冲突规则。
10. 禁止案例衍生的默认方案。 默认流程只能来自用户目标、稳定事实、明确约束和可迁移机制。单次案例中的人物、对象、动作、场景、风格、措辞和数值不得升级为默认值；确属领域常量时必须有独立依据。
11. 验收强度与风险匹配。 普通、只读且结果容易检查的 Skill，默认做结构校验，并在当前任务中临时核对两个表层内容明显不同的正常请求。只有用户明确要求或结果风险确实需要时才升级验证；升级不得改变授权边界，也不得把核对材料和运行输出沉淀为 Skill 资产。
12. 案例与长期规则严格隔离。 Skill 及其活动依赖中禁止保存失败样本、回归案例、纠正故事、案例提示词、案例输出、案例工作区和自然语言 Harness。允许长期保存的测试只能检查结构、契约字段或不依赖案例表述的明确不变量；不得用改名、改写或归入 fixture 的方式绕过隔离。

<!-- META_SKILLS_PROTECTED_CORE_END -->

工作流

1. 判断任务类型并读取规则

• 修改 meta-skills 自身：先运行 scripts/quick_validate.py <meta-skills-folder>。受保护核心校验失败时立即停止；只有用户在当前任务中明确授权修改核心原则，才同步更新核心、锁文件和校验器。
• 新建 Skill：读取 references/skill-design-playbook.md 和 references/openai-yaml.md。确认行为合同和目标位置后，运行 scripts/init_skill.py 建立唯一活动目录；正文和实际资源完成后运行 scripts/generate_openai_yaml.py 生成最终 UI 元数据。
• 重写、更新或审计 Skill：读取 references/skill-design-playbook.md。涉及 agents/openai.yaml 时同时读取 references/openai-yaml.md，并使用 scripts/generate_openai_yaml.py 更新，不能手工维护另一套字段规则。
• 从正常成功经验、用户认可与反复选择、失败纠偏、旧规则或历史对话中吸收新准则或完整能力，或者需要判断 Skill 职能是否过窄、过宽时：同时读取 references/absorption-and-governance.md。
• 从压缩包、仓库、文档或示例 Skill 中提炼价值、专业能力与实现资源时：同时读取 references/absorption-and-governance.md 和 references/evidence-distillation.md；前者决定是否吸收、职能与默认边界，后者只负责从材料中证明操作结构和实现载体。
• 高频误用、团队分发、迁移、度量或证明没有改坏：同时读取 references/skill-maintenance-and-evaluation.md。
• 把 meta-skills 设为本机默认 Skill 创建入口、禁用重叠的系统 Skill，或让安装入口与持续修改的源码保持同步：读取 references/skill-maintenance-and-evaluation.md 的“本地默认启用与源码同步”，按当前机器的真实发现路径执行并验证。

2. 先写行为合同，不先写文件计划

根据用户原话和真实上下文写清：

代表性真实请求：
用户最终想得到什么：
当前 Skill 实际承担的职能：
可用历史反映出的上层职能：
建议扩大、缩小还是保持，以及依据：
当前结果最有价值的能力，以及仍然缺少什么：
来源材料能补足的价值，以及真正产生该价值的组成部分：
准备迁移的最小完整能力单元：
当前请求需要的完成层级，以及精度、覆盖、成本与风险怎样限制方法强度：
稳定信息真源：
默认允许读取和执行什么：
最早可预防问题的判断点：
默认正向流程：
第一步必须做什么：
默认输出长什么样：
哪些行为必须由用户明确要求：
做到哪里立即停止：
用户不需要纠正就能观察到的通过标准：

领域惯例、仓库规则和外部资料只能约束怎样完成合同，不能改写用户目标。只有不同答案会实质改变默认行为时才追问。

创建或优化 Skill 时，不把用户当前一句话自动当作完整职能定义。先查看当前可用的对话、用户提供的历史材料、目标 Skill 的真实使用方式和明确接受或排除的结果，判断多项相邻需求是否共同指向一个稳定的上层角色。证据足够时，提出一个完整的新定位供用户一次确认，不让用户逐项补全能力；证据不足但不会改变身份、来源、权限或默认交付时，采用最连贯的保守解释并标明假设。

扩大“能处理什么”与扩大“默认可以做什么”必须分开。多项相邻能力可以归并为更完整的上层角色，但联网、写入、运行、发送、发布或删除仍由各自的授权边界决定。缩小职能必须来自明确排除、持续误触发、稳定冲突或已确认的角色收敛；用户没有提到某项能力不能单独作为删除依据。

3. 通过价值保留与抽象门槛

输入中出现正常成功经历、用户明确认可或反复采用的做法、失败输出、纠正记录、旧提示词、历史方案或连续对话时，先在当前任务中区分：

临时案例证据：仅用于定位，不写入文件
证据类型与强度：明确认可、重复选择、可观察成功、纠偏、稳定事实或弱推断
稳定事实：由用户、真实来源或领域常量确认
关键判断点：成功机制发生或错误可以预防之前，哪项决定改变结果
来源价值：它让用户得到什么目标 Skill 当前无法稳定提供的结果
价值因果链：哪些判断、知识、步骤、约束、脚本、模板或资产共同产生该结果
偶然细节：替换后不影响能力成立，只属于当前请求或样本的信息
可调参数：具体值随请求变化，但参数及其选择规则必须保留
构成性细节：删除后能力身份、结果质量或可复现性会明显受损的具体结构
最小完整能力单元：保留价值因果链所需的默认规则、限定分支、reference、script 与 asset 组合
当前与建议的职能边界：保持、扩大或缩小，以及默认与按需能力
适用边界：能力何时选择、何时停止以及何时不得套用

持久化前必须同时通过：

1. 删除偶然细节后，能力仍能解释来源材料为什么有价值；构成性细节和必要参数没有被误删为“案例表层”。
2. 迁移的是能够改变目标 Skill 判断、行动、产物或验收的完整能力单元，不是换一种说法的通用原则。
3. 能说明能力为什么成立、由什么产生、适用于哪里以及做到哪里停止，而不是复述当前案例的具体答案。
4. 在当前任务中临时核对至少两个内容表层不同、但都属于该能力适用范围的正常请求；两者复用同一价值因果链并产生各自结果。新增限定能力时，再核对一个相邻但不适用的请求，确认不会误套。
5. 正常经验有明确认可、重复选择、可观察成功或独立依据。完整项目中的规则、实现、资源与现有产物能够互相印证某项限定能力时，可以作为该能力的独立实现证据；单段叙述、单个提示词或一次结果只能提出假设。
6. 单一来源不能自动建立整个目标 Skill 的默认方案，但可以证明一个边界明确、由用户或目标职能需要的限定能力；默认化仍需用户确认、稳定规范或更广证据。
7. 职能扩大形成连贯的上层角色而不是功能堆积；职能缩小不以“历史中没有出现”为唯一依据。
8. 完成反事实检查：如果不读取来源材料也会得到同一组泛化原则，说明来源价值尚未提取；如果删去某项具体结构后无法稳定复现价值，必须将它恢复为构成性细节或明确依赖。

来源能力存在快速、标准、高保真或其它强度层级时，把“层级”和“怎样选择层级”保留为可调参数。先按用户要求、可观察结果、成本和错误代价选择最低但完整的能力单元，再为该层级确定证据、步骤、资源与验收；最高强度只能由用户明确要求，或由目标结果确实无法用较低强度证明时采用。不能因为来源项目默认最严格，就让目标 Skill 的所有请求承担同样成本。

临时核对只保留当次结论，不保存请求原文、提示词、输出、报告、fixture 或工作区。

4. 让用户确认实际行为

修改前向用户展示行为合同、当前与建议的职能边界、默认与按需能力、代表性输出骨架、将修改的文件及原因。证据足够时把同一上层角色下的能力作为整体方案确认，不逐项追问；用户确认的是以后怎样判断和交付，已经明确批准同一行为方案时不重复询问。

5. 实现唯一流程

• 新建 Skill 时，先确定名称、目标父目录、description 和三项必需 UI 文案。用户给出位置时使用该位置；未给出时使用 $HOME/.agents/skills。然后运行 scripts/init_skill.py <skill-name> --path <parent> --description <description> --interface display_name=... --interface short_description=... --interface default_prompt=...。初始化器只创建 SKILL.md 与 agents/openai.yaml，不创建空资源目录、示例文件或辅助文档。
• 初始化后立即用已确认的行为合同替换正文占位内容。只有已有真实内容要写入时才创建 references/、scripts/ 或 assets/；新增脚本必须实际运行，新增资产按 references/skill-design-playbook.md 的资源验证等级检查并准确报告，不能在没有真实下游任务时制造案例冒充消费链路。
• 默认判断、来源边界、动作权限、输出顺序和停止条件写进 SKILL.md。
• 职能发生扩大或缩小时，一次性迁移 description、第一判断、主流程、reference 路由、默认输出和停止条件；不能在旧定位后追加一段补充说明后继续保留两个活动身份。
• reference 只放过重的通用方法、边界明确的专业能力和清单，不放案例材料、案例复述或案例衍生的默认答案。限定能力必须写清选择条件、完整操作结构、必要参数、通过标准和停止边界，不能被抽象成失去专业效果的原则。
• 重复、确定且手写容易错的动作才写成 script；脚本不得保存自然语言案例或运行历史。Skill 完成后，运行 scripts/generate_openai_yaml.py <skill-folder> --interface ...，确保 UI 名称、简述和默认提示与最终 SKILL.md 一致。
• 一次性迁移所有调用点。被替代内容需要删除时先取得用户许可；未获许可则移出活动 Skill 归档，不保留活动入口或兼容说明。
• 修改 meta-skills 核心时，同步更新 core-principles.lock.json 和 scripts/quick_validate.py，不能留下两个核心版本。

6. 验证行为，而不沉淀案例

1. 运行 scripts/quick_validate.py <skill-folder> 检查确定性结构。
2. 新建 Skill 时，再从目标目录重新读取 SKILL.md 和 agents/openai.yaml，确认初始化器确实生成、最终正文确实写入、UI 元数据确实引用 $skill-name，而不是只相信脚本退出码。
3. 在当前任务中按第 3 步临时核对两个表层不同的正常请求，检查第一判断、允许来源、动作、输出开头、停止条件和可观察结果。新增限定能力时同时核对相邻不适用请求，确认它既能被选择，也不会污染其它默认路径。
4. Skill 含脚本或资产时，按当前任务真实具备的下游条件完成最高可证明的资源验证等级。所有资源先证明路径、触发条件、输入输出和消费者可达；当前请求自然产生真实产物时再检查实例化；用户同时要求实施或结果风险确实需要时才检查完整生产与消费链路。没有真实消费者时停在可证明等级并明确说明，不能用消费端手写假数据、临时案例或虚构项目冒充端到端验证。
5. 高风险任务确需独立验证时，先取得用户要求或授权，使用临时隔离环境执行。验证结束后不把请求、输出、报告或工作区写入 Skill。
6. 任一请求不符合行为合同就继续修改；结构校验不能替代这一判断。吸收任务还必须证明目标 Skill 新增或强化了一项可观察能力，而不是只增加了更通用的文字。

7. 完成交付

最终读取 references/quality-gate.md，然后只说明关键文件、默认行为变化、两项临时跨表层核对的结论；新增限定能力时再说明相邻不适用请求的边界核对和目标 Skill 的可观察能力变化。涉及脚本、模板或资产时说明实际达到的资源验证等级，最后说明结构检查结果。不得把推演描述成真实运行，也不得附带历史失败材料。

资源

新建、改写、更新或审计 Skill 时，读取 references/skill-design-playbook.md；它是行为合同、方法强度、资源验证等级、分支设计和创建验收的唯一详细说明。

创建 Skill 或维护 agents/openai.yaml 时，读取 references/openai-yaml.md；它是 UI 元数据字段、必填值和生成规则的唯一说明。使用 scripts/init_skill.py 初始化新目录，使用 scripts/generate_openai_yaml.py 生成或更新 UI 元数据，不手写第二套生成流程。

从正常成功经验、用户认可与反复选择、失败纠偏、旧规则、历史对话或外部材料中吸收新准则或完整能力，或者判断 Skill 职能范围时，读取 references/absorption-and-governance.md；它负责判断是否值得吸收、保留价值因果链、区分默认能力与限定能力并判断职能边界，不保存案例。

从压缩包、仓库、调研资料、示例 Skill 或大量外部文档中蒸馏专业能力、脚本、模板或资产时，在上述吸收规则之外再读取 references/evidence-distillation.md；它只负责证明外部材料中的操作结构和实现载体。

维护、评估、运营、分发、度量或治理 Skill 时，读取 references/skill-maintenance-and-evaluation.md；它只补充运行中的诊断与迁移方法，不建立案例库。

需要确定性结构检查时，运行 scripts/quick_validate.py <skill-folder>；脚本检查 frontmatter、目录名、未完成占位、引用文件、空目录、agents/openai.yaml 字段与资源路径，以及 meta-skills 的核心保护和案例隔离约束。它不能证明用户本意或实际输出正确。

最终交付前，读取 references/quality-gate.md。