技能介绍

要解决什么问题

团队里常见三类痛点：新建技能不知道该用单文件还是拆 references/；规约型规则写进 SKILL.md 后 Agent 仍会「合理化」跳过；技能上线后根本不会被触发，往往是因为描述写成工作流摘要、缺少 metadata.triggers 或命名过于泛化（如 helper）。本技能不是泛泛的「怎么写文档」，而是把创建、修补、合规校验串成一条可执行的决策路径。

工作机制与核心组件

入口是一张快速决策树：创建新技能时按复杂度在 Tier 1（单文件）与 Tier 3（模块化）之间选型；若问题是「AI 忽视规则」则走反合理化；若是「用户找不到」则走 CSO（面向 LLM 的可发现性/触发描述）。组件索引里还有标准（命名、YAML frontmatter、目录结构）与测试（红-绿-重构式验证）。

典型流程可以概括为：

用决策树明确目标（新建 / 修规则 / 查合规）。
从 references/templates/ 选模板：技巧型、参考型、规约型或模式型。
对描述做 CSO：以 Use when... 作触发器，而非复述整套工作流。
规约型技能叠加反合理化条款，降低被模型「自圆其说」绕过的概率。
按测试指南用真实场景跑通后再发布。

部署前检查清单强调硬性约束：name 与目录名一致、SKILL.md 全大写、描述以 Use when 开头、triggers 至少 3 个关键词、主文件行数控制在 500 以内，长内容进 references/，且交叉引用里避免用 @ 强制加载。

适用边界与注意点

本技能偏元技能（meta-skill）：它指导你如何写别的技能，本身不替代具体领域内容。若你只在 OpenCode 里做环境配置，相关能力在 opencode-expert；需要引导式创建时可用 /write-skill 命令。常见错误对照表（描述写工作流、缺 triggers、单体过长等）在 gotchas.md 中有展开——改技能前先对照表自检，比事后排查「为什么从不触发」更省事。