---

name: writing-skills description: "用于创建、更新或改进 Agent 技能时使用。" category: meta risk: unknown source: community date_added: "2026-02-27"

编写技能（卓越标准）

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

快速决策树

你需要做什么？

1. 创建一个新技能：

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

2. 改进现有技能：

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

3. 验证合规性：

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

组件索引

| 组件 | 用途 | |-----------|---------| | CSO | "面向 LLM 的 SEO"。如何编写能触发技能的描述。 | | 标准 | 文件命名、YAML 前置元数据、目录结构。 | | 反合理化| 如何编写 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]

常见错误

| 错误 | 修复方法 | |---------|-----| | 描述总结了工作流程 | 仅使用 "Use when..." 触发器 | | 没有 metadata.triggers | 添加 3+ 个关键词 | | 通用名称（"helper"） | 使用动名词（creating-skills） | | 冗长的单体 SKILL.md | 拆分到 references/ |

详见 gotchas.md。

部署前检查清单

部署任何技能前：

• [ ] name 字段与目录名完全匹配
• [ ] SKILL.md 文件名全大写
• [ ] 描述以 "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

限制

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