Hermes Agent Skill 怎么写: SKILL\\.md 5 段式

Hermes Agent Skill 怎么写: SKILL.md 5 段式

读者: 自托管 AI Agent (Hermes / Claude Code / Cursor / 自研) 的作者, 想沉淀方法论给团队/未来的自己复用 问题: AI agent 的 skill / prompt / 命令集怎么从"一次性能跑"沉淀成"长期可维护的资产"?

一句话总结

Skill 不是 prompt, 不是 README, 也不是代码注释。Skill 是 AI agent 的"操作手册"——告诉未来的 agent / 同事 / 作者: 在什么场景下, 按什么步骤, 避开什么坑, 怎么验证它跑对了。本文用作者 36 个沉淀 skill 的实战, 给出一套 5 段式 SKILL.md 模板。

全文目录

1. 为什么要写 SKILL.md

作者维护 36 个 skill, 复盘后发现三类场景 100% 需要 skill:

核心论点: 一次性能跑 ≠ skill。能复现 + 能维护 + 能被未来的 agent 理解 = skill。

2. 5 段式骨架

每个 SKILL.md 必含 5 段:

—
name: skill-name (kebab-case)
description: 一句话描述 + 触发场景
tags: [可选]
—

## 触发
[什么情况下 AI 自动加载本 skill]

## 步骤
[1. 第一步具体命令
2. 第二步
…]

## Pitfalls
[踩过的坑, 必含根因 + 修复]

## 验证
[跑完后怎么确认成功]

## 沉淀
[反编造铁律 / 拍板信号 / 复用建议]

2.1 frontmatter 3 字段必填

2.2 触发段写法 (重要)

❌ 错: “本 skill 用于处理飞书相关操作” (太宽)

✅ 对: “触发: 作者说’建飞书 docx’ / ‘写飞书文档’ / ‘给我可编辑’ / ‘docx 作者进不去’; 也适用于’作者要求 lark-cli 创建/修改/查询文档’” (含具体场景)

3. 6 块 prompt 编写模板

AI 加载 skill 后, prompt 必须含 6 块:

1. [角色]: 你是 X 角色 (资深 PM / lark-cli 工程师 / …)
2. [上下文]: 作者当前在做 Y (求职 / 欠款 / CSDN / …)
3. [任务]: 5 句话讲清具体任务
4. [约束]: 必走 4 件套 (查 schema / 跑脱敏 / 必验证 / 必回执)
5. [输出]: 5 行粘贴包 (标题 + URL + 1-3 行要点 + 作者手动操作项)
6. [验证]: 跑完必查 3 件 (return code / 数据写入 / 飞书可达)

3.1 实战示例 (csdn-blog-orchestrator)

1. [角色]: 你是一个 CSDN 技术博客 AI 写手, 作者在 CSDN 实名 zhangshengwang_
2. [上下文]: 拍 B 启动 q4 + q9 两篇, qid 在 csdn_planning_queue 表
3. [任务]: 写 2 篇 5500 字 Markdown, 必含表格 + 代码块, v6.2 化名表 0 命中
4. [约束]: 4 件套 – 查 queue.status / 跑 chk_personal_info.py / 写飞书 docx / 推飞书 DM
5. [输出]: 5 行粘贴包 – 标题 + URL + 1-3 行要点 + 作者手动操作项
6. [验证]: 3 件 – return code 0 / DB updated 1 / 飞书 path 200

4. 36 个 skill 沉淀分类 (作者实拍)

5. 5 类常见错误模式

5.1 触发段太宽

❌ “本 skill 用于处理文档” ✅ “触发: 作者说’建飞书 docx’…”

5.2 没有 pitfalls 段

只写"步骤"不写"坑"= 同事/未来的 agent 会重新踩一遍。

5.3 没有验证段

“跑完"≠"跑对”, 验证段必含具体可执行的命令 + 期望输出。

5.4 作者硬约束用 fetcher

拍板了, 必须写进 “✅ 作者硬约束” 字段, 不要散落在记忆/对话。

5.5 没有反编造铁律

任何"反编造铁律 vN (X 月增量)"必沉淀进 skill “## 反编造铁律” 段, 否则下个会话重复犯。

6. 一键验通脚本 + 落库 SOP

6.1 验通脚本

作者开源到 ~/.hermes/scripts/skill_validate.py:

# 5 段必查: frontmatter / 触发 / 步骤 / pitfalls / 验证
import yaml, sys
from pathlib import Path

def validate(skill_path):
p = Path(skill_path)
if not (p / 'SKILL.md').exists():
return f"❌ SKILL.md 不存在: {skill_path}"
content = (p / 'SKILL.md').read_text()
required = ['## 触发', '## 步骤', '## Pitfalls', '## 验证']
missing = [r for r in required if r not in content]
if missing:
return f"❌ {skill_path} 缺段: {missing}"
# frontmatter
if not content.startswith('—'):
return f"❌ {skill_path} 缺 frontmatter"
return f"✅ {skill_path} 5 段齐"

if __name__ == '__main__':
for skill in Path('~/.hermes/skills').iterdir():
print(validate(skill))

6.2 落库 SOP

作者用 Supabase hermes-personal.public.skills_registry 表, 字段:

• skill_id (PK)

• slug (text unique)

• category (text)

• 触发关键词 (text[])

• 5 段完整度 (bool 5 个)

• 最近验证日期

结语

Skill 是 AI agent 时代的"团队资产"。写一个能复用的 skill, 比写一个能用一次的 prompt 价值高 10 倍。这套 5 段式模板在作者的 36 个 skill 上验证 90 天, 跨会话复用率 80%+。

欢迎评论区交流你的 skill 沉淀方案。

作者: shengwangzhang 专栏: Hermes 全栈实战系列 – skill 开发篇 系列目录:

• 第 1 篇 (本文): Skill 怎么写 SKILL.md 5 段式

• 第 2 篇: Skill 反编造铁律: 实战沉淀 7 类常见认错

• 第 3 篇: Skill 自动学习 + 落地实战 (规划中)

参考资料: