第 29 章

Skill 是什么：包结构与 SKILL.md 规范

第29章：Skill 是什么：包结构与 SKILL.md 规范

在 Hermes Agent 生态中，Skill 是能力的最小可复用单元。它不是工具（Tool），不是插件（Plugin），而是两者之上的抽象——一个将"知道该做什么"（意图）和"知道怎么做"（工具调用）封装在一起的自描述包。理解 Skill 的设计哲学，是掌握 Hermes 生态系统的关键入口。

29.1 概念辨析：Skill vs Plugin vs Tool

这三个概念在 AI Agent 生态中经常被混用，但在 Hermes 框架中有明确的层次关系：

层次结构图

┌─────────────────────────────────────────────────────┐
│                    Skill                            │
│  ┌─────────────────────────────────────────────┐   │
│  │  元数据 + 意图描述 + 使用指南 + 示例         │   │
│  │                                              │   │
│  │  ┌──────────────┐  ┌──────────────────────┐ │   │
│  │  │  Tool 调用   │  │  Tool 调用           │ │   │
│  │  │  web_search  │  │  write_file          │ │   │
│  │  └──────────────┘  └──────────────────────┘ │   │
│  │                                              │   │
│  │  ┌─────────────────────────────────────────┐│   │
│  │  │          Plugin（可选）                  ││   │
│  │  │   外部 API 调用 / 自定义逻辑             ││   │
│  │  └─────────────────────────────────────────┘│   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘

三者的根本区别

维度	Tool	Plugin	Skill
本质	单一功能函数	外部服务接口	能力封装包
调用方式	模型直接调用	通过 API/SDK	注入到系统提示
携带知识	无（仅有 Schema）	最少	丰富（指南+示例）
可复用性	低（高度定制化）	中等	高（开箱即用）
发现机制	手动配置	插件商店	Skill 索引
版本管理	无标准	有	有（semver）
测试规范	无	框架相关	标准化
分发方式	代码	注册表	ClawHub

具体示例：同一功能的三种实现

以"网络搜索并总结"功能为例：

# 作为 Tool：仅定义接口，模型自己决定如何用
TOOL_DEFINITION = {
    "name": "web_search",
    "description": "Search the web for information",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string"}
        }
    }
}

# 作为 Plugin：封装了外部 API 调用逻辑
class SearchPlugin:
    def __init__(self, api_key: str):
        self.api_key = api_key
    
    def search(self, query: str) -> list[dict]:
        # 调用 Bing/Google API，处理响应
        ...

# 作为 Skill：完整的自描述能力包
# SKILL.md 包含：何时使用、如何使用、示例、注意事项
# 配合工具调用，让模型"懂得"如何做好搜索总结

29.2 完整的 Skill 包目录结构

一个标准的 Hermes Skill 包具有以下目录结构：

my-skill/
├── SKILL.md              # 核心：技能描述文件（必需）
├── skill.json            # 机器可读的元数据（必需）
├── tools/
│   ├── __init__.py
│   ├── main_tool.py      # 主工具实现
│   └── helpers.py        # 辅助函数
├── prompts/
│   ├── system.md         # 技能专属系统提示片段
│   └── examples/
│       ├── example1.json # 示例输入输出对
│       └── example2.json
├── tests/
│   ├── test_basic.py     # 基础功能测试
│   ├── test_edge_cases.py
│   └── fixtures/
│       └── sample_data.json
├── docs/
│   └── api_reference.md  # 可选：详细 API 文档
├── requirements.txt      # Python 依赖
├── LICENSE
└── README.md             # GitHub 展示用（非 SKILL.md）

各目录的作用说明

# skill.json：机器可读的元数据，供 Skill 索引使用
{
    "id": "web-research-summarizer",
    "version": "1.2.0",
    "name": "Web Research Summarizer",
    "author": "your-username",
    "license": "MIT",
    "hermes_version": ">=3.0.0",
    "tags": ["research", "web", "summarization"],
    "tools_required": ["web_search", "fetch_url"],
    "entry_point": "SKILL.md",
    "homepage": "https://clawhub.io/skills/web-research-summarizer"
}

29.3 SKILL.md 字段详解

SKILL.md 是 Skill 包的核心，采用结构化 Markdown 格式，包含人类可读和机器可解析两种内容。

完整 SKILL.md 模板

---
# ===== SKILL METADATA（YAML Front Matter）=====
id: web-research-summarizer
version: 1.2.0
name: Web Research Summarizer
description: >
  Searches the web for information on a topic and produces
  a structured summary with source citations.
author: your-username
license: MIT
tags:
  - research
  - web
  - summarization
  - citations
hermes_version: ">=3.0.0"
tools_required:
  - web_search
  - fetch_url
tools_optional:
  - create_file
language: en
created: 2024-03-15
updated: 2024-11-20
---

# Web Research Summarizer

## Overview

This skill enables Hermes to conduct structured web research on any topic.
When activated, Hermes will search multiple sources, evaluate their credibility,
and synthesize a comprehensive summary with proper citations.

**When to use this skill:**
- User asks for information on a recent or factual topic
- User needs information with source verification
- User wants a balanced view from multiple sources

**Do NOT use this skill when:**
- The question can be answered from training knowledge (avoid unnecessary searches)
- User explicitly asks you not to search the web
- The topic is highly time-sensitive and requires real-time data (use dedicated tools)

## Usage

### Invocation

This skill is automatically invoked when Hermes detects research intent.
You can also explicitly invoke it with:
- "Search the web for..."
- "Research and summarize..."
- "Find information about... with sources"

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `topic` | string | Yes | — | The research topic or question |
| `depth` | enum | No | "medium" | Research depth: "quick" / "medium" / "deep" |
| `sources` | integer | No | 3 | Number of sources to consult (1–10) |
| `language` | string | No | "auto" | Summary language (auto-detect from user) |
| `format` | enum | No | "prose" | Output format: "prose" / "bullets" / "structured" |

### Process

When this skill is invoked, follow this process:

1. **Query formulation**: Break the topic into 2–3 specific search queries
2. **Search execution**: Call `web_search` for each query
3. **Source evaluation**: Prioritize authoritative and recent sources
4. **Content retrieval**: Use `fetch_url` for the top 3 sources
5. **Synthesis**: Combine information, resolve conflicts, note disagreements
6. **Citation**: Include inline citations [1] and a references section

## Examples

### Example 1: Quick Research

**User input:**

What is the current state of quantum computing?


**Skill execution:**
```json
// Step 1: Search
{"tool": "web_search", "query": "quantum computing breakthroughs 2024"}
{"tool": "web_search", "query": "quantum computing practical applications current"}

// Step 2: Fetch top sources
{"tool": "fetch_url", "url": "https://..."}

Expected output:

## Quantum Computing: Current State (2024)

Quantum computing has reached several milestones in 2024...
[1] Source citation...

### Key Developments
- IBM achieved X qubits...
- Google demonstrated Y...

## References
[1] Title, URL, Date
[2] ...

Example 2: Deep Research with Structured Output

[详细示例省略]

Dependencies

Required Tools

web_search: Core search capability. Requires API key configured.
fetch_url: URL content fetching. Must support text extraction.

Optional Tools

create_file: If present, can save research results to file on request.

External Services

Any web search API (Bing, Brave, SerpAPI, etc.)
No special accounts required beyond base Hermes configuration

Configuration

Add to your hermes.yaml to enable:

skills:
  - id: web-research-summarizer
    version: "^1.2"
    config:
      default_depth: medium
      max_sources: 5
      preferred_language: auto

Limitations

Search results are limited by the configured search API's rate limits
Content from paywalled sites cannot be retrieved
Research accuracy depends on the quality of available web sources
Real-time data (stock prices, live scores) requires dedicated tools

Changelog

1.2.0 (2024-11-20)

Added format parameter for structured output
Improved citation formatting
Fixed: URL fetch timeout handling

1.1.0 (2024-06-10)

Added multi-language support
Added depth parameter

1.0.0 (2024-03-15)

Initial release


### 字段详解表

| 字段 | 位置 | 必需 | 说明 |
|-----|-----|-----|-----|
| `id` | YAML Front Matter | 是 | 全局唯一标识符，kebab-case |
| `version` | YAML Front Matter | 是 | semver 格式（如 1.2.0） |
| `name` | YAML Front Matter | 是 | 人类可读名称 |
| `description` | YAML Front Matter | 是 | 一句话描述，供索引和搜索 |
| `tools_required` | YAML Front Matter | 是 | 必须存在的工具列表 |
| `hermes_version` | YAML Front Matter | 是 | 兼容的 Hermes 版本范围 |
| Overview | Markdown 正文 | 是 | 详细描述 + When to use |
| Usage | Markdown 正文 | 是 | 参数说明 + 使用流程 |
| Examples | Markdown 正文 | 是 | 至少 2 个完整示例 |
| Dependencies | Markdown 正文 | 是 | 工具依赖和外部服务说明 |
| Limitations | Markdown 正文 | 推荐 | 明确说明不适用场景 |
| Changelog | Markdown 正文 | 推荐 | 版本历史 |

---

## 29.4 Skill 索引机制

Hermes 通过 Skill 索引发现和加载可用的 Skill：

```python
# Skill 索引的工作原理
class SkillIndex:
    """
    Skill 索引管理器：
    1. 扫描配置的 Skill 目录
    2. 解析每个 Skill 的 SKILL.md 和 skill.json
    3. 建立可搜索的索引
    4. 在运行时提供 Skill 发现和注入服务
    """
    
    def __init__(self, skill_dirs: list[str]):
        self.skills: dict[str, SkillMeta] = {}
        self._load_all(skill_dirs)
    
    def _load_all(self, dirs: list[str]):
        for skill_dir in dirs:
            for skill_path in Path(skill_dir).glob("*/skill.json"):
                meta = self._parse_skill(skill_path.parent)
                if meta and self._check_compatibility(meta):
                    self.skills[meta.id] = meta
    
    def find_relevant(self, user_message: str, top_k: int = 3) -> list[SkillMeta]:
        """根据用户消息找到最相关的 Skill"""
        # 简单关键词匹配（生产中使用向量检索）
        scores = {}
        for skill_id, meta in self.skills.items():
            score = self._relevance_score(user_message, meta)
            if score > 0:
                scores[skill_id] = score
        
        top_skills = sorted(scores, key=scores.get, reverse=True)[:top_k]
        return [self.skills[sid] for sid in top_skills]
    
    def inject_skill(self, skill: SkillMeta, system_prompt: str) -> str:
        """将 Skill 的关键内容注入到系统提示中"""
        skill_content = self._extract_injection_content(skill)
        return system_prompt + f"\n\n<skill name='{skill.id}'>\n{skill_content}\n</skill>"
    
    def _extract_injection_content(self, skill: SkillMeta) -> str:
        """从 SKILL.md 中提取需要注入到提示的核心部分"""
        # 提取：Overview + Usage（去掉示例和 Changelog 节省 Token）
        skill_md = Path(skill.path) / "SKILL.md"
        # ... 解析逻辑
        return compressed_content

Skill 加载的 Token 成本

注入策略	Token 成本	适用场景
注入完整 SKILL.md	800–2,000 tokens	开发调试
注入 Overview + Usage	300–600 tokens	生产推荐
仅注入 Overview	100–200 tokens	Token 极限场景
仅注入工具描述	50–100 tokens	极简模式

29.5 官方 Skill 仓库结构分析

ClawHub（Hermes 官方 Skill 仓库）的组织结构：

clawhub.io/
├── skills/
│   ├── official/          # NousResearch 官方维护
│   │   ├── core-research/
│   │   ├── code-assistant/
│   │   ├── data-analysis/
│   │   └── file-manager/
│   │
│   ├── verified/          # 社区贡献，经过安全审核
│   │   ├── web-scraper/
│   │   ├── pdf-analyzer/
│   │   └── ...
│   │
│   └── community/         # 社区贡献，未审核
│       └── ...
│
└── collections/           # 技能包（多个 Skill 的组合）
    ├── developer-toolkit/
    └── research-suite/

安装官方 Skill：

# 使用 Hermes CLI 安装 Skill
hermes skill install web-research-summarizer
hermes skill install official/[email protected]

# 查看已安装的 Skill
hermes skill list

# 更新所有 Skill
hermes skill update

# 查看 Skill 详情
hermes skill info web-research-summarizer

29.6 小结

Skill 是 Hermes Agent 生态系统的核心组件，理解其设计原则至关重要：

Skill vs Tool vs Plugin：Skill 是高层抽象，包含意图理解和使用知识，而非仅仅是函数接口
SKILL.md 是核心：结构化的自描述文档，同时服务于人类理解和机器解析
目录结构规范：标准化的包结构确保 Skill 的可发现性、可测试性和可复用性
索引机制：Skill 通过轻量索引实现动态发现和按需注入，避免 Token 浪费
ClawHub 生态：从官方 → 认证 → 社区三层分级管理，平衡质量和开放性

思考题

SKILL.md 中的 "When to use" 和 "Do NOT use" 部分对模型有多大影响？如果这部分写得不准确，会出现什么问题？
Skill 索引在选择相关 Skill 时需要做语义匹配。简单关键词匹配 vs 向量检索——对于 Hermes Agent 场景，哪种方式更合适？各自的优缺点是什么？
如果一个任务需要两个 Skill 协作（如先用 Research Skill 获取信息，再用 Writing Skill 撰写报告），Hermes 如何协调多个 Skill 的注入而不超出 Token 预算？
设计一个 Skill 的"能力证明"机制——在 Skill 发布前，如何自动验证 SKILL.md 中声明的功能确实有效？

本章评分

4.9 / 5 (4 评分)