8dafa5bc52
- Add archives/ directory for immutable external skill snapshots - Strict immutability rule: only README/CHANGELOG can be modified - First import: dev-pipeline-universal v1.0.0 (Hermes Agent) - Import dev-pipeline-universal into hermes-agent/skills/ with CHANGELOG - Update hermes-agent/publish/registry.json with imported skill - Rewrite meta-skills/create-hermes-agent-skill/ with full spec: - SKILL.md frontmatter fields and validator constraints - Recommended body structure (Overview → When to Use → Pitfalls → Verification) - Progressive disclosure (3-level loading) - 8 writing quality principles - Official reference skills from GitHub repo - Tool chain docs (skill_manage, /learn, skill_view) - Update README.md with archives/ in directory structure
125 lines
3.6 KiB
Markdown
125 lines
3.6 KiB
Markdown
# Hermes Agent 技能规范摘要
|
||
|
||
> 基于 Hermes Agent 官方文档和 GitHub 仓库（`nousresearch/hermes-agent`）整理。
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
<skill-name>/
|
||
├── SKILL.md # 核心指令文件（必填）
|
||
├── references/ # 按需加载的参考文档（可选）
|
||
├── templates/ # 模板文件（可选）
|
||
├── scripts/ # 辅助脚本（可选）
|
||
├── assets/ # 静态资源（可选）
|
||
└── CHANGELOG.md # 版本变更记录（推荐）
|
||
```
|
||
|
||
## SKILL.md 规范
|
||
|
||
### YAML Frontmatter
|
||
|
||
文件必须以 `---` 开头（第一个字节），无空行或 BOM：
|
||
|
||
```yaml
|
||
---
|
||
name: my-skill-name # 必填，≤64 字符，^[a-z][a-z0-9_-]*$
|
||
description: "Use when ..." # 必填，≤1024 字符
|
||
version: 1.0.0 # 推荐
|
||
author: <作者> # 推荐
|
||
license: MIT # 推荐
|
||
platforms: [linux, macos, windows] # 推荐，不兼容平台自动隐藏
|
||
metadata:
|
||
hermes:
|
||
tags: [tag1, tag2] # 推荐，搜索标签
|
||
category: software-development # 可选
|
||
related_skills: [other-skill] # 推荐，跨技能引用
|
||
fallback_for_toolsets: [] # 可选，仅在特定工具缺失时显示
|
||
requires_toolsets: [] # 可选，依赖的工具集
|
||
config: [] # 可选，配置项
|
||
---
|
||
```
|
||
|
||
### 验证器硬约束
|
||
|
||
| 约束 | 值 | 来源 |
|
||
|------|---|------|
|
||
| `name` 必填 | — | `skill_manager_tool.py::_validate_frontmatter` |
|
||
| `name` 最大长度 | 64 字符 | `MAX_NAME_LENGTH` |
|
||
| `description` 必填 | — | 同上 |
|
||
| `description` 最大长度 | 1024 字符 | `MAX_DESCRIPTION_LENGTH` |
|
||
| SKILL.md 最大长度 | 100,000 字符 | `MAX_SKILL_CONTENT_CHARS` |
|
||
| Frontmatter 开头 | `---`（第 0 字节） | 同上 |
|
||
| Frontmatter 闭合 | `\n---\n` | 同上 |
|
||
| Frontmatter 后正文 | 非空 | 同上 |
|
||
|
||
### 推荐正文结构
|
||
|
||
```markdown
|
||
# <标题>
|
||
|
||
## Overview
|
||
做什么，为什么。
|
||
|
||
## When to Use
|
||
- 触发条件
|
||
- "Don't use for:" 反触发
|
||
|
||
## <特定章节>
|
||
命令、表格、recipes...
|
||
|
||
## Common Pitfalls
|
||
编号列表。
|
||
|
||
## Verification Checklist
|
||
- [ ] 验证项
|
||
```
|
||
|
||
## 存放位置
|
||
|
||
| 类型 | 路径 | 创建方式 |
|
||
|------|------|---------|
|
||
| 用户本地 | `~/.hermes/skills/<name>/` | `skill_manage(action='create')` |
|
||
| 项目仓库 | `skills/<category>/<name>/` | `write_file` + `git add` |
|
||
| 外部导入 | `~/.hermes/skills/openclaw-imports/` | 从 OpenClaw 迁移 |
|
||
|
||
## 分类目录（官方）
|
||
|
||
```
|
||
autonomous-ai-agents creative data-science devops dogfood
|
||
email gaming github leisure mcp media mlops
|
||
note-taking productivity red-teaming research
|
||
smart-home social-media software-development
|
||
```
|
||
|
||
选择最接近的已有分类，不要随意创建新分类。
|
||
|
||
## 渐进式披露
|
||
|
||
| 层级 | API | 内容 |
|
||
|------|-----|------|
|
||
| L0 | `skills_list()` | 基础元数据（name + description） |
|
||
| L1 | `skill_view(name)` | 完整 SKILL.md |
|
||
| L2 | `skill_view(name, path)` | 特定 references/ 文件 |
|
||
|
||
## Skill Bundles
|
||
|
||
多个技能可打包为一个 Bundle：
|
||
|
||
- 存放路径：`~/.hermes/skill-bundles/`
|
||
- 格式：YAML 文件
|
||
- 通过单个斜杠命令调用一组技能
|
||
|
||
## Skills Hub
|
||
|
||
- 官方 Hub：[agentskills.io](https://agentskills.io)
|
||
- 支持来源：`official`、`skills-sh`、`well-known`、`github`
|
||
- 所有第三方安装会经过安全扫描
|
||
|
||
## 编辑已有技能
|
||
|
||
| 操作 | 方法 |
|
||
|------|------|
|
||
| 小修复 | `skill_manage(action='patch', name=..., old_string=..., new_string=...)` |
|
||
| 大重写 | `write_file` 整个 SKILL.md |
|
||
| 添加辅助文件 | `write_file` 到 references/templates/scripts/assets |
|