What Is a Skill: Package Structure and SKILL.md Specification

Chapter 29: What Is a Skill: Package Structure and SKILL.md Specification

In the Hermes Agent ecosystem, a Skill is the smallest reusable unit of capability. It is not a Tool, not a Plugin, but an abstraction above both — a self-describing package that encapsulates "knowing what to do" (intent) together with "knowing how to do it" (tool calls). Understanding the design philosophy of Skills is the key entry point to mastering the Hermes ecosystem.

29.1 Concept Clarification: Skill vs Plugin vs Tool

These three concepts are frequently conflated in the AI Agent ecosystem, but in Hermes they occupy distinct layers:

Hierarchy Diagram

┌─────────────────────────────────────────────────────┐
│                      Skill                          │
│  ┌─────────────────────────────────────────────┐   │
│  │  Metadata + Intent desc + Guide + Examples   │   │
│  │                                              │   │
│  │  ┌──────────────┐  ┌──────────────────────┐ │   │
│  │  │  Tool call   │  │  Tool call           │ │   │
│  │  │  web_search  │  │  write_file          │ │   │
│  │  └──────────────┘  └──────────────────────┘ │   │
│  │                                              │   │
│  │  ┌─────────────────────────────────────────┐│   │
│  │  │          Plugin (optional)               ││   │
│  │  │   External API calls / custom logic      ││   │
│  │  └─────────────────────────────────────────┘│   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘

Fundamental Differences

Same Feature, Three Implementations

Using "web search and summarize" as an example:

# As a Tool: interface only, model decides how to use it
TOOL_DEFINITION = {
    "name": "web_search",
    "description": "Search the web for information",
    "input_schema": {"type": "object", "properties": {"query": {"type": "string"}}}
}

# As a Plugin: encapsulates external API call logic
class SearchPlugin:
    def __init__(self, api_key: str):
        self.api_key = api_key
    def search(self, query: str) -> list[dict]:
        # Calls Bing/Google API, handles responses
        ...

# As a Skill: complete self-describing capability package
# SKILL.md contains: when to use, how to use, examples, caveats
# Paired with tool calls so the model truly "understands" how to do good research

29.2 Complete Skill Package Directory Structure

my-skill/
├── SKILL.md              # Core: skill description file (required)
├── skill.json            # Machine-readable metadata (required)
├── tools/
│   ├── __init__.py
│   ├── main_tool.py      # Primary tool implementation
│   └── helpers.py        # Helper functions
├── prompts/
│   ├── system.md         # Skill-specific system prompt fragment
│   └── examples/
│       ├── example1.json # Input/output example pairs
│       └── example2.json
├── tests/
│   ├── test_basic.py
│   ├── test_edge_cases.py
│   └── fixtures/
│       └── sample_data.json
├── docs/
│   └── api_reference.md  # Optional: detailed API documentation
├── requirements.txt
├── LICENSE
└── README.md             # GitHub display (not the same as SKILL.md)

skill.json: Machine-Readable Metadata

{
    "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 Field Reference

SKILL.md is the heart of a Skill package — structured Markdown that serves both human readers and machine parsing.

Complete SKILL.md Template

---
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
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 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
- User explicitly asks not to search the web
- Topic requires real-time data (use dedicated tools)

## Usage

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `topic` | string | Yes | — | The research topic |
| `depth` | enum | No | "medium" | "quick" / "medium" / "deep" |
| `sources` | integer | No | 3 | Number of sources (1–10) |
| `language` | string | No | "auto" | Output language |

### Process

1. **Query formulation**: Break 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 top 3 sources
5. **Synthesis**: Combine, resolve conflicts, note disagreements
6. **Citation**: Include inline citations and a references section

## Examples

### Example 1: Quick Research

**User input:**

What is the current state of quantum computing?

**Skill execution:**
```json
{"tool": "web_search", "query": "quantum computing breakthroughs 2024"}
{"tool": "fetch_url", "url": "https://..."}

Expected output structure:

## Quantum Computing: Current State (2024)
...summary with citations [1]...

## References
[1] Title, URL, Date

Dependencies

Required Tools

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

Optional Tools

• create_file: Can save research results to file on request.

Limitations

• Search results limited by configured API rate limits
• Paywalled content cannot be retrieved
• Accuracy depends on available web sources

Changelog

1.2.0 (2024-11-20)

• Added format parameter for structured output
• Improved citation formatting

1.0.0 (2024-03-15)

• Initial release

### Field Reference Table

| Field | Location | Required | Description |
|-------|----------|----------|-------------|
| `id` | YAML Front Matter | Yes | Global unique identifier, kebab-case |
| `version` | YAML Front Matter | Yes | semver format (e.g., 1.2.0) |
| `name` | YAML Front Matter | Yes | Human-readable name |
| `description` | YAML Front Matter | Yes | One-sentence description for indexing |
| `tools_required` | YAML Front Matter | Yes | List of required tools |
| `hermes_version` | YAML Front Matter | Yes | Compatible Hermes version range |
| Overview | Markdown body | Yes | Detailed description + When to use |
| Usage | Markdown body | Yes | Parameters + Execution process |
| Examples | Markdown body | Yes | At least 2 complete examples |
| Dependencies | Markdown body | Yes | Tool deps and external services |
| Limitations | Markdown body | Recommended | Explicit non-use cases |
| Changelog | Markdown body | Recommended | Version history |

---

## 29.4 The Skill Index Mechanism

```python
class SkillIndex:
    """
    Skill Index Manager:
    1. Scans configured Skill directories
    2. Parses each Skill's SKILL.md and skill.json
    3. Builds a searchable index
    4. Provides Skill discovery and injection at runtime
    """
    
    def find_relevant(self, user_message: str, top_k: int = 3) -> list:
        """Find most relevant Skills for the user's message."""
        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, system_prompt: str) -> str:
        """Inject key Skill content into the system prompt."""
        skill_content = self._extract_injection_content(skill)
        return system_prompt + f"\n\n<skill name='{skill.id}'>\n{skill_content}\n</skill>"

Skill Injection Token Cost

29.5 ClawHub Repository Structure

clawhub.io/
├── skills/
│   ├── official/          # NousResearch maintained
│   │   ├── core-research/
│   │   ├── code-assistant/
│   │   └── data-analysis/
│   │
│   ├── verified/          # Community, security-reviewed
│   │   └── ...
│   │
│   └── community/         # Community, unreviewed
│       └── ...
│
└── collections/           # Skill bundles (multi-Skill combos)
    ├── developer-toolkit/
    └── research-suite/

# Install via Hermes CLI
hermes skill install web-research-summarizer
hermes skill install official/[email protected]
hermes skill list
hermes skill update
hermes skill info web-research-summarizer

29.6 Summary

Skill is the core component of the Hermes Agent ecosystem:

• Skill vs Tool vs Plugin: Skill is a high-level abstraction carrying intent knowledge and usage guidance, not just a function interface
• SKILL.md is central: Structured self-describing document serving both human understanding and machine parsing
• Standard directory: Ensures discoverability, testability, and reusability
• Index mechanism: Lightweight discovery with on-demand injection avoids unnecessary token waste
• ClawHub ecosystem: Three-tier management (official → verified → community) balances quality and openness

Discussion Questions

1. How much influence do the "When to use" and "Do NOT use" sections in SKILL.md have on model behavior? What happens if they're inaccurate?

2. Skill index relevance matching can use keyword matching or vector retrieval. For Hermes Agent scenarios, which approach is more appropriate? What are the tradeoffs?

3. If a task needs two Skills to collaborate (e.g., Research Skill then Writing Skill), how does Hermes coordinate multiple Skill injections without exceeding the token budget?

4. Design a "capability proof" mechanism — before publishing a Skill, how could you automatically verify that the functionality declared in SKILL.md actually works?