writing-skills

编写技能（卓越实践）

兼容性：这些模板是惯例，并非通用加载器架构。请使用目标宿主文档中说明的技能目录和当前架构；自定义 metadata.triggers 是可选项，且本身不能保证技能会被发现。随附的上游指南是历史快照。渲染需要 Node.js 和本地安装的 Graphviz dot；仅检查可信的 DOT 文件，并谨慎打开生成的 SVG。--combine 会在各图表间共享节点 ID，是一种视觉上的便利功能，并非保留语义的合并。输出具有排他性：重新运行前，请谨慎删除输出目录或选择其他目录。

范围：示例是编写和测试用的夹具，并非实时指令。请遵循用户、宿主和仓库的指令层级。仅使用经授权的隔离夹具运行压力测试；绝不要删除用户的工作成果，也不要为了强制执行技能而削弱安全或审批边界。保留现有工作；如果基线已经通过，请相应调整验证计划。示例符合要求，并不能证明普遍可靠。

用于卓越技能创建的调度器。使用下方决策树查找合适的模板和标准。

⚡ 快速决策树

你需要做什么？

1. 创建新技能：

   • 是否简单（单个文件，少于 200 行）？→ Tier 1 架构
   • 是否复杂（涉及多个概念，200–1000 行）？→ Tier 2 架构
   • 是否为大型平台（10 个以上产品、AWS、Convex）？→ Tier 3 架构

2. 改进现有技能：

   • 解决“太长了” → 模块化（Tier 3）
   • 解决“AI 忽略规则” → 防合理化
   • 解决“用户找不到” → CSO（搜索优化）

3. 验证合规性：

   • 检查元数据/命名 → 标准
   • 添加测试 → 测试指南

📚 组件索引

组件	用途
CSO	“面向大模型的 SEO”。如何编写能够触发技能的描述。
标准	文件命名、YAML frontmatter、目录结构。
防合理化	如何编写 Agent 不会忽略的规则。
测试	如何确保技能确实有效。

🛠️ 模板

• 技术型技能（操作指南）
• 参考型技能（文档）
• 规范型技能（规则）
• 模式型技能（设计模式）

适用场景

• 从头创建新技能
• 改进 Agent 会忽略的现有技能
• 排查技能为何未被触发
• 在团队内统一技能规范

工作原理

1. 确定目标 → 使用上方的决策树
2. 选择模板 → 从 references/templates/ 中选择
3. 应用 CSO → 优化描述以便技能被发现
4. 添加防合理化内容 → 用于规范型技能
5. 测试 → RED-GREEN-REFACTOR 循环

快速示例

---
name: my-technique
description: Use when [specific symptom occurs].
metadata:
  category: technique
  triggers: error-text, symptom, tool-name
---

# My Technique

## When to Use
- [Symptom A]
- [Error message]

常见错误

错误	修正方法
描述概括了工作流	简洁描述能力和具体使用条件
没有 metadata.triggers	这是可选的宿主专属元数据；请在描述中加入有用的术语
名称过于笼统（如“helper”）	使用描述性强、由小写字母和连字符组成的 ID
SKILL.md 过长且一体化	拆分到 references/ 中

更多内容请参阅 gotchas.md。

✅ 部署前检查清单

部署任何技能前：

• name 字段与目录名称完全一致
• SKILL.md 文件名为全大写
• 描述说明技能的功能及适用场景
• Frontmatter 符合目标宿主和仓库架构
• 总行数少于 500 行（更多内容请使用 references/）
• 交叉引用中没有使用 @ 强制加载
• 已通过真实场景测试

🔗 相关技能

• opencode-expert：用于配置 OpenCode 环境
• 如果你的宿主定义了 /write-skill，该命令可能会提供引导式创建功能；此处未捆绑该命令

示例

创建 Tier 1 技能：

mkdir -p ~/.config/opencode/skills/my-technique
touch ~/.config/opencode/skills/my-technique/SKILL.md

创建 Tier 2 技能：

mkdir -p ~/.config/opencode/skills/my-skill/references/core
touch ~/.config/opencode/skills/my-skill/{SKILL.md,gotchas.md}
touch ~/.config/opencode/skills/my-skill/references/core/README.md

局限性

• 仅当任务明确符合上述范围时才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代方案。
• 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并请求澄清。