【Skills 系统从入门到精通】第 24 篇：Skill 编写最佳实践——从实战经验中提炼

---

本篇你将学到

• 技能粒度的权衡：太粗 vs 太细
• 技能组合优于巨型技能的拆分原则
• 命名规范、版本管理、测试策略
• 技能文档的可读性：给 Agent 读 vs 给人读
• 团队技能规范指南

读完本篇，你将从"能写技能"升级到"能写好技能"，具备设计高质量技能体系的能力。

---

一、技能粒度

1.1 太粗 vs 太细

粒度	示例	问题
太粗	devops-toolbox（包含部署、监控、日志、安全…）	触发不精准、上下文浪费
太细	grep-error-from-nginx-log	复用性差、数量膨胀
适中	log-analysis（日志分析全流程）	✅ 触发精准、可复用

1.2 粒度判断原则

一个问题域 = 一个技能。如果两个操作流程服务于不同的目标，它们应该是两个技能。

日志分析 和 日志收集 → 两个技能（不同目标）
代码审查 和 代码格式化 → 两个技能（不同目标）
TDD流程 → 一个技能（同一目标，包含测试+实现）

---

二、技能组合优于巨型技能

2.1 拆分原则

当一个技能超过 15K 字符，考虑拆分。拆分方式：

按阶段拆分：

用 Bundle 组合：

# ~/.hermes/skill-bundles/ci-cd.yaml
name: ci-cd
skills:
  - ci-build
  - cd-deploy
instruction: |
  Full CI/CD pipeline: build → test → deploy → verify

拆分 + Bundle 组合的好处：

• 每个技能更小、更聚焦
• 可以单独使用某个阶段
• 不同任务可以选择不同组合

---

三、命名与版本管理

3.1 命名层级

领域.动作.对象     （推荐）

示例：

log-analysis        → log（领域）+ analysis（动作）
deploy-kubernetes   → deploy（动作）+ kubernetes（对象）
github-pr-workflow  → github（领域）+ pr-workflow（动作）

3.2 版本管理策略

变更类型	版本升级	示例
修复 typo、补充 Pitfall	修订号	1.0.0 → 1.0.1
新增步骤或 References	次版本	1.0.1 → 1.1.0
流程根本性变更	主版本	1.x → 2.0.0

3.3 测试策略

技能的"测试"是验证它在不同场景下正确触发和执行：

测试项	方法
触发准确性	用不同的自然语言描述测试是否匹配
斜杠命令	/skill-name 能否正确加载
流程完整性	步骤是否覆盖了完整流程
边界场景	不常见的输入是否处理
跨平台	在不同 OS 上是否正常工作

---

四、给 Agent 读 vs 给人读

4.1 双重读者

SKILL.md 有两类读者：

• Agent（主要读者）：需要执行操作步骤
• 人类（次要读者）：需要理解技能做什么、审查质量

4.2 写作平衡

内容类型	为 Agent 优化	为人类优化
Procedure 步骤	✅ 精确命令	加注释解释
description	✅ 关键词优化	保持可读
Pitfalls	✅ 防止重复踩坑	✅ 便于审查
Overview	可选	✅ 帮助人类理解

平衡策略：Procedure 以 Agent 为主（精确命令），Overview 和 Pitfalls 以人类为主（清晰解释）。

---

五、团队技能规范

5.1 统一风格指南

团队共同编写技能时，建议建立规范：

规范项	统一标准
命名风格	动词+对象，全拼不缩写
description 格式	“Use when…” + 核心能力
章节顺序	Overview → When to Use → Procedure → Pitfalls → Verification
代码块	标注语言，必须可运行
版本起始	新技能从 1.0.0 开始
tags 使用	复用已有标签，不随意造新标签

5.2 团队技能管理

通过 Tap 机制分享给团队成员：

hermes skills tap add our-org/team-skills
hermes skills install our-org/team-skills/deploy-k8s

---

第五模块总结

至此，第五模块（编写自己的 Skills）的五篇全部完成：

第20篇：第一个实战技能（六步编写流程）
    ↓
第21篇：质量标准（触发条件、步骤、陷阱）
    ↓
第22篇：脚本集成（Python/Bash 脚本调用）
    ↓
第23篇：八大陷阱（避坑指南）
    ↓
第24篇：最佳实践（粒度、版本、团队规范）

你现在具备了从零编写高质量技能的全部知识。接下来的第六模块将探索 Skills Hub 生态——发现和使用全球社区共享的技能。

---

下篇预告

从下一篇开始进入第六模块"Skills Hub 生态"。第 25 篇将带你俯瞰八大技能来源的全景图。

---

如果本篇内容对你有帮助，欢迎点赞收藏！有任何疑问，欢迎在评论区交流。