Writing Skills

编写技能（卓越篇）

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

⚡ 快速决策树

你需要做什么？

1. 创建一个新技能：

   • 是否简单（单文件，<200 行）？→ Tier 1 架构
   • 是否复杂（多概念，200-1000 行）？→ Tier 2 架构
   • 是否为大型平台（10+ 产品，AWS、Convex）？→ Tier 3 架构

2. 改进现有技能：

   • 修复"它太长了" -> 模块化（Tier 3）
   • 修复"AI 忽略规则" -> 反合理化
   • 修复"用户找不到它" -> CSO（搜索优化）

3. 验证合规性：

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

📚 组件索引

🛠️ 模板

• 技巧型技能（How-to）
• 参考型技能（文档）
• 纪律型技能（规则）
• 模式型技能（设计模式）

何时使用

• 从零创建一个新技能
• 改进智能体忽略的现有技能
• 调试某个技能为何未被触发
• 在团队内统一技能标准

工作原理

1. 确定目标 → 使用上方决策树
2. 选择模板 → 从 references/templates/ 中选择
3. 应用 CSO → 优化 description 以提升可发现性
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]

常见错误

更多内容见 gotchas.md。

✅ 部署前检查清单

部署任何技能之前：

• name 字段与目录名完全一致
• SKILL.md 文件名全大写
• description 以 "Use when..." 开头
• metadata.triggers 包含 3+ 关键词
• 总行数 < 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

局限性

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