Skills vs Tools: Different Layers, Different Responsibilities

+15 Mana ✨
Hermes Tools User Guide(DOCUMENTATION)

Introduction

If you have already worked through Course 3 (hermes-tools), you know what a tool is: a single named function the agent can call, like web_search or read_file. Skills look superficially similar (the agent invokes both), but they live at a different layer of the system. Conflating the two is the first stumbling block for new authors.

Key Concepts

  • Tool: A single function with a name, description, JSON schema, and runtime implementation. Hermes ships more than seventy of these.
  • Skill: A Markdown-based workflow package. It does not execute anything by itself. It instructs the agent to use existing tools in a particular sequence.
  • Layer: Tools are the capability layer (what the agent can do). Skills are the workflow layer (how the agent should do something specific).
  • Composition: A skill usually orchestrates several tools to achieve its goal.

Real World Context

Consider the request find slow database queries in our last week of logs and summarize them. There is no single tool called find_slow_queries. There is terminal for shell commands, read_file for reading files, and web_search if you needed external context. A skill called db-perf-audit could capture the exact procedure: query the right log path, filter by duration, group by query template, format the summary. The tools were already there. The skill is the recipe.

Deep Dive

Here is the relationship visually:

text
┌──────────────────────────────┐
        │   Skill (db-perf-audit)      │  Workflow layer
        │   "How to audit DB queries"  │  (Markdown instructions)
        └─────────────┬────────────────┘
                      │ orchestrates
                      ▼
  ┌──────────┬───────────┬──────────────┬──────────┐
  │ terminal │ read_file │ search_files │ memorize │  Capability layer
  └──────────┴───────────┴──────────────┴──────────┘  (Tools, ~70 built-in)

A tool is binary: it either exists in the registry or it does not. A skill is descriptive: it tells the agent how to combine the tools that exist.

This distinction has practical consequences:

  • Adding a tool requires code. It means writing a Python implementation, registering it in the toolset, and shipping a new Hermes release (or using the custom tool plugin path covered in Course 10).
  • Adding a skill requires only Markdown. You write a SKILL.md, drop it in ~/.hermes/skills/, and it works the next time you launch a session.

The trade-off is reach. A tool can be used by any skill (or by the agent without a skill at all). A skill cannot be used by a tool: skills sit higher in the stack, not lower.

There is also a security difference. Tools run code. They are vetted by the Hermes maintainers and gated by permission policy. Skills run no code of their own (any scripts they ship run through the same sandboxes the agent would use anyway). Installing a skill is closer to installing a system prompt than to installing a plugin.

Common Pitfalls

  1. Building a skill when you really need a tool: If you find yourself writing a skill whose entire body is run this exact Python script every time, you probably want a custom tool instead. Skills should describe decisions, not be a wrapper around one command.
  2. Building a tool when a skill would do: Conversely, if your tool would just inline a few existing tool calls in a fixed order, write a skill. Adding tools has a higher maintenance cost.

Best Practices

  1. Ask is this a function or a recipe?: Functions become tools. Recipes become skills. Most user-facing workflows are recipes.
  2. Reach for skills first: Skills are cheaper to write, easier to update, and live entirely in user space. Only escalate to a custom tool when the skill cannot be expressed without one.

Summary

  • Tools are the capability layer: single named functions with schemas and code.
  • Skills are the workflow layer: Markdown recipes that orchestrate tools.
  • A skill cannot exist without tools; the tools it uses are still the agent's only way to act.
  • Choose a skill when you need a recipe, a tool when you need a new capability.

Code Examples

markdown
---
name: db-perf-audit
description: Audit slow Postgres queries from the last week and summarize them by template.
---
# DB Perf Audit

## Procedure
1. Use the `terminal` tool to run:
   `aws logs filter-log-events --log-group-name /aws/rds/postgres/prod --filter-pattern 'duration:' --start-time $(date -v-7d +%s)000`
2. Use `read_file` if the user points to a local export.
3. Group entries by normalized query template (strip literals).
4. Summarize: top 10 templates, p50 and p99 duration, total invocations.

## Pitfalls
- The log group rotates every 30 days. If the window exceeds that, warn the user.
- Do not include literal parameter values in the summary (PII risk).
✓ Completed