SkillSpace/meta-skills/create-hermes-agent-skill/prompt.md

如何创建 Hermes Agent 技能

本技能指导你为 Hermes Agent 框架创建符合规范的技能，基于官方文档和 GitHub 仓库中的最佳实践。

核心概念

Hermes Agent 技能（Skill）是代理的程序化记忆（Procedural Memory），代理在运行时创建和复用。技能遵循 agentskills.io 开放标准，可跨平台共享。

技能存放位置

位置	路径	用途
用户本地	~/.hermes/skills/<name>/SKILL.md	个人技能，不共享，通过 skill_manage(action='create') 创建
项目仓库内	skills/<category>/<name>/SKILL.md	随项目提交，团队共享

创建流程

1. 调研已有技能

# 查看目标分类下已有的技能
ls skills/<category>/

阅读 2-3 个同类技能的 SKILL.md，匹配风格和结构。避免创建重复技能。

2. 创建 SKILL.md

文件必须：

• 以 --- 开头（不能有空行或 BOM）
• YAML frontmatter 以 \n---\n 闭合
• frontmatter 后紧跟 Markdown 正文

3. 编写 Frontmatter

---
name: my-skill-name               # 小写+连字符，≤64 字符
description: "Use when <触发条件>. <一句话行为描述>."  # ≤1024 字符
version: 1.0.0
author: <作者名>
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [短, 描述性, 标签]
    related_skills: [other-skill, another-skill]
---

必填字段（验证器强制）：

• name：≤64 字符，正则 ^[a-z][a-z0-9_-]*$
• description：≤1024 字符，以 "Use when ..." 开头

推荐字段（所有官方技能都包含）：

• version、author、license、platforms
• metadata.hermes.tags、metadata.hermes.related_skills

4. 编写正文结构

# <技能标题>

## Overview
一到两段：做什么，为什么需要。

## When to Use
- 触发条件（bullet 列表）
- "Don't use for:" 反触发条件

## <技能特定章节>
- 快速参考表
- 精确命令的代码块
- Hermes 特有的 recipes

## Common Pitfalls
编号列表：常见错误和修复方法。

## Verification Checklist
- [ ] 操作后验证的 checkbox 列表

## One-Shot Recipes（可选）
命名场景 → 具体命令序列。

5. 添加辅助文件

• references/ — 按需加载的参考文档
• templates/ — 模板文件
• scripts/ — 辅助脚本
• assets/ — 静态资源

6. 本地验证

import yaml, re, pathlib
content = pathlib.Path("skills/<category>/<name>/SKILL.md").read_text()
assert content.startswith("---")
m = re.search(r'\n---\s*\n', content[3:])
fm = yaml.safe_load(content[3:m.start()+3])
assert "name" in fm and "description" in fm
assert len(fm["description"]) <= 1024
assert len(content) <= 100_000

7. 提交

git add skills/<category>/<name>/
git commit -m "Add skill: <name>"

注意：当前会话的技能加载器在会话开始时缓存，新技能需要在新会话中才能被 skill_view / skills_list 看到。

关键规范

Description 编写规范

• ≤ 1024 字符
• 以 "Use when ..." 开头，描述触发类别而非单一任务
• 示例：
  • ✅ "Use when debugging test failures. Enforce RED-GREEN-REFACTOR cycle."
  • ❌ "Debug tests"
  • ❌ "Be thorough when testing"

文件大小限制

限制项	值	说明
Description	≤ 1024 字符	验证器强制
完整 SKILL.md	≤ 100,000 字符	约 36k tokens
推荐范围	8-14k 字符	官方技能平均水平
超过 20k	拆分到 references/*.md	渐进式披露

渐进式披露（三层加载）

层级	调用方式	内容
L0	skills_list()	仅加载基础元数据
L1	skill_view(name)	加载完整 SKILL.md
L2	skill_view(name, path)	加载特定参考文件

触发机制

• 斜杠命令：/<skill-name>
• 自然语言对话
• fallback_for_toolsets：仅在特定高级工具缺失时显示
• platforms：自动隐藏不兼容操作系统的技能

写作质量原则

1. 优化过程可预测性 — 每一行都应改变代理行为，否则删除
2. 正确的上下文负载 — description 每次都会被加载，保持精炼
3. 信息层级 — 常用步骤放 SKILL.md，详细内容放 references/
4. 完成标准 — 每个步骤都要有可检查的完成条件
5. 规则与概念共存 — 定义、警告、示例、验证放在一起
6. 使用强引导词 — "tight loop"、"root cause"、"regression test" 比长解释更省 token
7. 消除重复和无效内容 — "Be careful"、"use best practices" 不改变行为，删除
8. 防止过早完成 — 如果代理倾向于跳过某步骤，先锐化该步骤的完成标准

官方参考技能

技能	路径	说明
Skill Authoring	skills/software-development/hermes-agent-skill-authoring/	官方技能编写指南
Test-Driven Development	skills/software-development/test-driven-development/	TDD 工作流
Systematic Debugging	skills/software-development/systematic-debugging/	系统化调试
Plan	skills/software-development/plan/	任务规划

工具链

工具	用途
skill_manage(action='create')	创建用户本地技能（~/.hermes/skills/）
skill_manage(action='patch')	补丁更新（支持 in-repo 和本地）
skill_manage(action='write_file')	写入辅助文件（references/templates/scripts/assets）
/learn 命令	从 URL 或本地上下文自动生成技能
skill_view(name)	查看技能完整内容
skills_list()	列出所有可用技能

常见陷阱

陷阱	说明
用 skill_manage(create) 创建 in-repo 技能	会写到 ~/.hermes/skills/，应用 write_file
--- 前有空行	验证器检查 startswith("---")，会失败
Description 太通用	应以 "Use when ..." 开头描述触发类别
缺少 author/license/metadata	验证器不强制，但所有官方技能都有
创建重复技能	先 ls skills/<category>/ 检查
期望当前会话看到新技能	技能加载器在会话开始时缓存
积累沉淀内容	技能应越来越精炼，添加新规则时删除旧措辞
无效内容	"Be careful" 不改变行为，用可检查的完成标准替代