用途
本技能用于在指定仓库中创建或升级技能（skill）。它覆盖仓库专属的 frontmatter 规则、渐进式披露、参考文件策略、验证流程，以及生产级工程技能所需的质量标准。当任务需要可复用的判断、领域约束或经过验证的工作流，而非临时性建议时，适合使用本技能。
当任务与技能编写无关，或更适合由更具体的配套技能处理时，不应使用本技能；当请求只需一个简单答案、本技能的约束或参考文件无法提供实质帮助时，也不应使用。
主要能力
- 定义可复用问题：仅当技能能捕获可重复工作流、稳定的架构或领域模式，或高风险区域（护栏能显著改善结果）时才创建或更新技能。不为通用编程知识或一次性任务创建技能。
- 选择技能形态：工作流技能（针对脆弱或顺序性工作的分步执行）、标准技能（针对质量敏感领域的决策规则、检查清单和门禁）、领域技能（业务概念、不变量和重复出现的实现模式）。
- 保持核心精简：SKILL.md 应包含范围与激活线索、有序工作流或决策逻辑、不可协商的标准、简短检查清单、对更深文件的引用。将大型示例、审查模板、详细模式、长检查清单、主题深入内容移至 references/。
- 编码判断而非样板：好的技能告诉 Codex 优先考虑什么、避免什么、哪些权衡重要、什么算“完成”；差的技能只是复述显而易见的框架语法或堆砌长教程。
- 参考文件策略：若技能覆盖多个子领域，按主题拆分参考文件，使每个文件有单一明确用途，并以主题命名、可独立加载、直接从 SKILL.md 链接。不要重新发明常见模板，优先复用 skill-composition-standards 技能 references/ 目录下的模板库（如 threat-model-template.md、entity-model-template.md、normalisation-playbook.md、test-plan-template.md）。不要将重要文件埋藏多层，应直接从 SKILL.md 链接。
- 书籍与源文件蒸馏规则：当用户提供书籍、EPUB、PDF、课程笔记、长文章等源文件时，将其视为临时输入，完成的技能必须在这些文件被删除、移动或重命名后仍然有用。不要仅链接源文件路径，而要将实用知识蒸馏为自包含的 references/*.md 文件，保留工作流、决策表、检查清单、失败模式、示例、质量门禁和输出要求。保持 SKILL.md 简洁，将持久深度放在直接链接的参考文件中。避免复制长段落，应总结、综合并将书籍知识转化为可复用执行规则。在参考文件中添加简短说明，表明其自包含且由提供的源材料整理而成，以便未来代理不依赖原始文件。若源材料范围广，按实用主题而非书籍章节拆分。验证每个新参考文件都从 SKILL.md 链接，并附有明确的加载条件。
使用方式
- 先阅读 SKILL.md，然后仅加载任务所需的深层参考文件。
- 应用本技能中的有序指导、检查清单和决策规则，而非挑选孤立片段。
- 产出交付物时，在重要处明确假设、风险和后续工作。
所需输入：收集相关项目上下文、约束和要解决的具体问题；按需加载参考文件和脚本。确认期望的交付物：设计、代码、审查、迁移计划、审计或文档。
仓库规则
- SKILL.md 保持在 500 行以内。更深的 markdown 参考保持精简，难以加载或维护时拆分。
- 仅使用验证器批准的 frontmatter 键：name、description、license、allowed-tools、metadata。
- 让 description 成为触发器：说明技能做什么以及何时使用。
- 将深层细节放在 references/；SKILL.md 专注于执行逻辑。
- 不要在技能内添加元文档，如 README.md 或 CHANGELOG.md。
Frontmatter 模板：
name: skill-name description: Use when ...
指南：name 必须与目录名完全匹配；description 直接具体；将主要触发短语前置；避免填充词和营销语言。
质量与验证
质量标准：每个技能应帮助 Codex 产出生产就绪、默认安全、关注性能、可测试可维护、以用户为中心、明确失败处理和运营风险的输出。编写工程技能时以 world-class-engineering 为基线。
升级检查清单：移除模糊或通用建议；添加决策规则和发布门禁；添加真实失败案例和反模式；若提供了书籍/源文件，使升级后的技能自包含且不依赖这些文件继续存在；收紧激活描述；仅在依赖确实有用时链接其他技能；编辑后重新检查行数。
验证：创建或更新技能后，运行 python -X utf8 skill-writing/scripts/quick_validate.py <skill-dir>（检查 frontmatter、必需章节、双兼容标记、行数限制）；运行 python -X utf8 skill-writing/scripts/contract_gate.py --skill <skill-dir>（来自 validation-contract 的 Evidence Produced 契约），使用 --all 扫描整个仓库，--bundle <path> 验证 Release Evidence Bundle，--strict 将警告视为错误；修复任何 frontmatter、结构或契约问题；用真实提示对技能做合理性检查；确保技能单独加载时仍清晰可读。
适用场景与限制
适用场景：在指定仓库中编写或升级技能；需要将书籍、PDF、课程笔记等源材料蒸馏为自包含参考文件；需要为工程技能建立质量标准、决策规则和发布门禁。
限制与反模式：避免像教科书一样庞大的 SKILL.md；避免过于宽泛的触发描述；避免重复现有技能而不提升质量门槛；避免示例堆砌而缺乏操作指导；避免忽视安全、性能、测试或可维护性的指令。默认加载所有参考文件而非使用渐进式披露也是反模式。
配套技能：编写工程技能时加载 world-class-engineering；在分享高影响或安全敏感技能前加载 skill-safety-audit。
输出：符合任务的具体结果，如实现指导、审查发现、架构决策、模板或生成的工件；当任务无法仅凭可用上下文完成时，明确假设、权衡或未解决的缺口；在能实质改善执行时，列出使用的参考、配套技能或后续行动。
致谢：由 Peter Bamuhigire 分享，techguypeter.com，+256 784 464178。