【Skills 系统从入门到精通】第 23 篇编写常见陷阱与避坑指南本篇你将学到技能编写中最常见的 8 大陷阱每个陷阱的典型表现、根因和修复方案编写后自检的方法从这些陷阱中提炼出的预防原则读完本篇你将避开别人踩过的坑直接写出高质量的技能。八大陷阱详解八大编写陷阱描述类陷阱1 description 非触发式陷阱6 related_skills 死链结构类陷阱2 技能过大超 20K陷阱7 Frontmatter 格式错误流程类陷阱3 缺少 Verification陷阱4 创建重复技能陷阱5 当前会话不可见条件类陷阱8 fallback 与 requires 写反陷阱 1description 写成功能描述而非触发条件表现技能存在但自然语言触发总是失败。# ❌ 错误功能描述description:This skill provides comprehensive log analysis capabilities.# ✅ 正确触发描述description:Use when analyzing server logs. Error extraction,pattern matching,root cause.根因description 是 Agent 语义匹配的唯一线索。“provides comprehensive capabilities” 不包含用户可能说的关键词。修复改用 “Use when…” 句式包含用户会使用的同义词。陷阱 2技能过大超过 20K 字符表现技能加载时占用大量上下文影响 Agent 处理其他任务的能力。根因把所有细节都塞在 SKILL.md 正文中包括完整的 API 规范、所有配置选项、冗长的示例。修复正文只保留核心流程8K-15K 字符详细内容移入references/目录在正文中用详见 references/xxx.md引导陷阱 3忘记 Verification 步骤表现Agent 执行完技能流程后无法确认结果是否正确。# ❌ 没有 Verification ## Procedure 1. ... 2. Done. # ✅ 有 Verification ## Verification - [ ] Error count matches statistical summary - [ ] All extracted timestamps fall within target window根因作者认为流程走完就是完成了忽略了验证环节。修复每个技能都必须有 Verification 章节列出可量化检查的验证步骤。陷阱 4创建了重复技能表现系统中存在两个功能重叠的技能Agent 不确定用哪个。根因没有先检查现有技能库就动手创建。修复创建前执行hermes skills list和hermes skills search 关键词如果找到相似技能考虑扩展现有技能而非新建如果确实需要独立技能在 description 中明确区分陷阱 5当前会话看不到新技能表现刚创建的技能在当前会话中调用不了。# 刚创建了技能skill_manage(actioncreate,namemy-skill,...)# 立刻尝试调用/my-skilldosomething# → 技能不存在根因技能加载器在会话启动时初始化当前会话的技能缓存不会中途更新。修复开新会话/new或重新启动hermes后验证。新会话当前会话用户新会话当前会话用户skill_manage create my-skill技能文件写入磁盘/my-skill do something技能不存在会话启动时的缓存不更新new 开新会话启动时扫描技能目录/my-skill do something正常加载执行陷阱 6related_skills 引用不存在表现related_skills 中引用了不存在的技能名。# 假设 systematic-debuggin 不存在少了 gmetadata:hermes:related_skills:[systematic-debuggin]# typo根因手动编写 Frontmatter 时打错字或引用了未安装的技能。修复引用的技能名必须和hermes skills list中的 name 完全一致使用skill_manage(actioncreate)创建时 Agent 会自动处理正确性陷阱 7Frontmatter 格式错误表现技能无法加载或 Frontmatter 被当作正文。# ❌ 错误1开头有空行← 这行是空的---name:my-skill# ❌ 错误2description 中有未转义冒号description:Use when:analyzing logs# ❌ 错误3YAML 缩进错误metadata:hermes:tags:[devops]修复---必须是文件的第一个字符无前导空行/空格description 含冒号时加引号description: Use when analyzing: logsYAML 缩进必须一致陷阱 8条件激活字段逻辑写反表现技能在应该显示的时候隐藏了或者反过来。# ❌ 错误想做 fallback 但写成了 requiresmetadata:hermes:requires_toolsets:[web]# 这是有 web 时才显示# 实际意图是没有 web 时作为 fallback 显示# 应该用 fallback_for_toolsets# ✅ 正确metadata:hermes:fallback_for_toolsets:[web]# 没有 web 时显示根因fallback 和 requires 的语义容易混淆。修复fallback_for_* “当它不在时我顶上”降级方案requires_* “我需要它才能工作”工具依赖当它不在时 我顶上我需要它才能工作想表达的条件意图语义方向fallback_for_toolsets降级方案requires_toolsets工具依赖例 DuckDuckGoweb 不可用时显示例 Docker 技能有 terminal 才显示预防原则从八大陷阱中提炼出四条预防原则原则预防的陷阱先查再建重复技能、related_skills 错误格式严格Frontmatter 错误大小适中技能过大新会话验证当前会话看不到预防预防预防预防四条预防原则先查再建格式严格大小适中新会话验证陷阱4 陷阱6陷阱7陷阱2陷阱5本篇小结陷阱修复方案description 非触发式“Use when…” 关键词技能过大拆分到 references/无 Verification添加可量化验证步骤重复技能先搜索扩展而非新建当前会话不可见开新会话验证related_skills 死链名称完全匹配Frontmatter 错误无前导空行、引号、缩进条件激活写反fallback顶上requires依赖下篇预告下一篇是第五模块的最后一篇——技能编写最佳实践从实战经验中提炼技能粒度、命名、版本管理、测试策略等。如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。