description: Common pitfalls and tribal knowledge for skill creation.metadata:tags: [gotchas, troubleshooting, mistakes]技能编写陷阱避免常见错误的部落知识。YAML Frontmatter无效语法# ❌ 错误混合列表和映射metadata:references:triggers:a,b,c-item1-item2# ✅ 正确结构一致metadata:triggers:a,b,creferences:-item1-item2多行描述# ❌ 错误换行导致解析错误description:Use when creating skills. Also for updating.# ✅ 正确使用 YAML 多行语法description:-Use when creating or updating skills.Triggers:new skill,update skill命名目录必须与name字段匹配# ❌ 错误 directory: my-skill/ name: mySkill # Mismatch! # ✅ 正确 directory: my-skill/ name: my-skill # Exact matchSKILL.md 必须全大写# ❌ 错误 skill.md Skill.md # ✅ 正确 SKILL.md发现描述 触发词而不是工作流# ❌ 错误代理读了它就跳过完整技能description:Analyzes code,finds bugs,suggests fixes# ✅ 正确代理读取完整技能以理解工作流description:Use when debugging errors or reviewing code quality纪律技能的违规前触发词# ❌ 错误违规之后才触发description:Use when you forgot to write tests# ✅ 正确违规之前触发description:Use when implementing any feature,before writing codeToken 效率每次对话都加载的技能 Token 消耗频繁加载的技能200 词其他所有500 词把细节移到references/文件中不要重复 CLI 帮助# ❌ 错误用 50 行记录所有标志 # ✅ 正确一行 Run mytool --help for all options.反合理化仅纪律技能代理擅长找漏洞# ❌ 错误信任代理会领会精神 Write test before code. # ✅ 正确显式封堵每个漏洞 Write test before code. **No exceptions:** - Dont keep code as reference - Dont adapt existing code - Delete means delete构建合理化表基线测试中的每个借口都放进表里ExcuseReality“Too simple to test”Simple code breaks. Test takes 30 seconds.“I’ll test after”Tests-after prove nothing immediately.交叉引用保持引用只向下一层# ❌ 错误嵌套链A → B → C See [patterns.md] → which links to [advanced.md] → which links to [deep.md] # ✅ 正确扁平A → B, A → C See [patterns.md] and [advanced.md]绝不用 强制加载# ❌ 错误立即烧掉上下文 skills/my-skill/SKILL.md # ✅ 正确代理在需要时加载 See [my-skill] for details.OpenCode 集成正确的技能目录# ❌ 错误旧的单数路径~/.config/opencode/skill/my-skill/# ✅ 正确复数路径~/.config/opencode/skills/my-skill/技能交叉引用语法# ❌ 错误文件路径脆弱 See /home/user/.config/opencode/skills/my-skill/SKILL.md # ✅ 正确技能协议 See my-skill层级选择不要过度思考层级选择# ❌ 错误以第 3 级开始以防万一 # 结果浪费精力引用文件空空如也 # ✅ 正确从第 1 级开始需要时升级 # 之后随时可以添加 references/需要升级的信号SignalActionSKILL.md 200 lines→ Tier 23 related sub-topics→ Tier 210 products/services→ Tier 3“I need X” vs “I want Y”→ Tier 3 decision trees
