第 2 课 SKILL.md 规范精讲
第 2 课 SKILL.md 规范精讲
本课目标
- 掌握 SKILL.md 文件的完整格式规范
- 理解元数据字段的含义与最佳实践
- 了解 Skill 的加载机制与生命周期
2.1 SKILL.md 文件结构
每个 Skill 就是一个 Markdown 文件，包含两部分：
┌──────────────────────────┐
│ YAML Front Matter (头部) │ ← 元数据：名称、触发词、工具
│ --- │
├──────────────────────────┤
│ Markdown 正文 │ ← 指令：Agent 的行为规范
│ (系统提示词 + 工作流程) │
└──────────────────────────┘
完整示例：一个 Git 提交助手 Skill
---
name: git-commit-helper
description: 分析代码变更，生成规范的 Git Commit 信息
version: 1.0.0
author: xiaoyang-dev
triggers:
- "帮我写提交信息"
- "生成 commit message"
- "help me write commit"
tools:
- terminal
tags:
- git
- development
---
# Git Commit Helper
## 角色
你是一个 Git 提交信息专家，严格遵循 Conventional Commits 规范。
## 工作流程
1. 执行 `git diff --staged` 查看暂存区变更
2. 分析变更内容，识别变更类型（feat/fix/refactor/docs...）
3. 生成符合规范的 commit message
4. 如果变更过大，建议拆分为多次提交
## 输出格式
约束
- Subject 不超过 50 个字符
- Body 每行不超过 72 个字符
- 使用英文编写（除非用户明确要求中文）
---
## 2.2 元数据字段精讲
### 必填字段
| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `name` | string | 唯一标识符，小写+连字符 | `git-commit-helper` |
| `description` | string | 一句话描述功能，显示在 Skills Hub | `分析代码变更，生成规范的 Git Commit 信息` |
| `version` | string | 语义化版本号 | `1.0.0` |
| `triggers` | list | 触发词列表，用户说出即激活 | `["帮我写提交信息"]` |
### 可选但推荐字段
| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `author` | string | 开发者用户名 | `xiaoyang-dev` |
| `tools` | list | 需要的工具权限 | `["terminal", "web_search"]` |
| `tags` | list | 分类标签 | `["git", "development"]` |
| `requires` | object | 环境依赖 | `{ "os": "linux" }` |
| `fallback` | object | 降级策略 | `{ "model": "nous-hermes-mini" }` |
| `icon` | string | 图标 emoji 或 URL | `📝` |
| `license` | string | 许可协议 | `MIT` |
| `pricing` | object | 定价信息 | `{ "type": "free" }` |
### name 命名规范
✅ 好的命名 git-commit-helper 全小写、有描述性 docker-log-analyzer 功能明确 ssl-cert-monitor 简洁
❌ 不好的命名 mySkill 驼峰命名 git_helper 下划线 tool1 无意义 super-awesome-skill 太长
### triggers 编写技巧
```yaml
triggers:
# 中文触发词
- "帮我写提交信息"
- "生成提交信息"
- "写 commit"
# 英文触发词
- "write commit message"
- "generate commit"
# 关键词触发
- "commit message"
原则：
- 至少 3 个触发词（中英文各覆盖）
- 包含口语化表达
- 不要太宽泛（"帮我"就会匹配所有对话）
- 不要太狭窄（只匹配一种特定表达）
tools 权限声明
tools:
- terminal # 终端命令执行
- web_search # 网络搜索
- file_read # 读取文件
- file_write # 写入文件
- mcp # MCP 协议调用
安全原则： 只声明你真正需要的工具。声明 terminal 意味着 Skill 可以执行任意命令——用户会注意这一点。
2.3 指令区编写
指令区是 SKILL.md 的 Markdown 正文，定义 Agent 激活该 Skill 后的行为。
结构模板
# [Skill 名称]
## 角色
一句话定义 Agent 在此 Skill 中扮演的角色。
## 工作流程
1. 第一步...
2. 第二步...
3. 第三步...
## 输出格式
定义输出的结构（表格/JSON/Markdown...）
## 约束
- 安全约束
- 格式约束
- 行为约束
## 示例
输入：...
输出：...
角色定义的要点
## 角色
✅ 好的角色定义：
你是一个数据库性能分析专家，擅长 PostgreSQL 慢查询诊断。
你的分析结果必须包含具体的优化建议和预期提升幅度。
❌ 不好的角色定义：
你是一个有帮助的 AI 助手。（太泛）
工作流程的编写
## 工作流程
✅ 明确的流程：
1. 执行 `pg_stat_statements` 获取 Top 10 慢查询
2. 对每条查询执行 `EXPLAIN (ANALYZE, BUFFERS)`
3. 识别问题类型：缺少索引 / 全表扫描 / 不良 JOIN
4. 生成优化建议并估算改善幅度
5. 输出结构化报告
❌ 模糊的流程：
- 分析数据库性能
- 给出建议
约束的设置
## 约束
- 只对 SELECT 查询做 EXPLAIN，不分析 INSERT/UPDATE/DELETE
- 不执行 ALTER TABLE 等 DDL 操作
- 建议创建索引时必须说明空间代价
- 输出使用中文
2.4 Skill 加载机制
匹配流程
用户输入 → 触发词匹配 → 加载 Skill → 注入指令 → Agent 执行
具体步骤：
1. 用户说："帮我分析慢查询"
2. Hermes 在所有已安装 Skill 中搜索 triggers
3. 匹配到 pg-slow-query-analyzer 的触发词
4. 将 SKILL.md 正文注入当前对话上下文
5. Agent 按照指令区的流程执行
优先级规则
当多个 Skill 的触发词匹配时：
| 优先级 | 规则 |
|---|---|
| 1 (最高) | 完全匹配（用户输入完全等于触发词） |
| 2 | 本地 Skill > Hub Skill |
| 3 | 最近使用过的 Skill 优先 |
| 4 | 触发词更长/更具体的优先 |
生命周期
安装 → 加载 → 匹配 → 激活 → 执行 → 完成
│ │
│ hermes skills install │ Skill 指令注入上下文
│ hermes skills list │ Agent 按流程执行
│ │ 完成后 Skill 指令移除
小杨的理解：「Skill 不是一个常驻程序，而是一段按需注入的指令。 激活时注入，完成后移除。轻量、灵活。」
2.5 常见错误
错误 1：触发词太宽泛
# ❌ 这个触发词会匹配几乎所有对话
triggers:
- "帮我"
- "help"
# ✅ 加上具体场景
triggers:
- "帮我写提交信息"
- "help write commit"
错误 2：遗漏 version 字段
# ❌ 没有版本号，无法进行 Skill 更新管理
name: my-skill
description: ...
# ✅ 始终包含版本号
name: my-skill
version: 1.0.0
description: ...
错误 3：指令区过于模糊
# ❌
帮用户处理事情，尽量做好。
# ✅
## 工作流程
1. 用 `git diff --staged` 获取暂存区变更
2. 分析每个文件的修改内容
3. 确定变更类型（feat/fix/refactor/docs/style/test/chore）
4. 生成符合 Conventional Commits 的信息
错误 4：声明不需要的工具权限
# ❌ 一个只分析文本的 Skill 不需要终端权限
tools:
- terminal
- web_search
- file_read
- file_write
# ✅ 最小权限原则
tools:
- file_read
2.6 动手练习
- 创建你的第一个 SKILL.md：选择一个简单场景（如"分析 JSON 格式"）
- 填写所有元数据：确保 name、description、version、triggers 齐全
- 编写指令区：定义角色、流程、输出格式、约束
- 本地安装测试：
# 将 SKILL.md 放到本地目录
mkdir -p ~/.hermes/skills/json-analyzer/
cp SKILL.md ~/.hermes/skills/json-analyzer/
# 查看是否加载成功
hermes skills list
# 用触发词测试
hermes "帮我分析这段 JSON 的结构"
- 调试触发词：尝试不同的措辞，观察是否正确触发
本课小结
| 要点 | 内容 |
|---|---|
| 文件结构 | YAML 头部（元数据）+ Markdown 正文（指令） |
| 核心字段 | name / description / version / triggers / tools |
| 指令区 | 角色 + 工作流程 + 输出格式 + 约束 |
| 加载机制 | 触发词匹配 → 注入指令 → 执行 → 移除 |
下一课：从模板到可用——小杨的第一个 Skill 实战。