Composing Multiple Skills in One Session

+15 Mana ✨
Conditional Activation(DOCUMENTATION)

Introduction

Skills are not exclusive. A single session can use several of them, sometimes in the same turn. The Level 0 index is intentionally cheap so you can have dozens installed without paying for context until activation. Composition becomes its own design question: which skills should coexist, which should hide based on environment, and how to keep the index legible.

Key Concepts

  • Composition: Two or more skills active in the same conversation, either sequentially or in support of each other.
  • Conditional activation: A frontmatter feature (fallback_for_toolsets, requires_toolsets, fallback_for_tools, requires_tools) that hides or shows a skill based on which tools are loaded.
  • Platform gating: The platforms frontmatter field hides a skill on incompatible operating systems.
  • Index hygiene: Keeping the Level 0 index legible by pruning unused skills and writing tight descriptions.

Real World Context

A developer is on macOS with the web toolset loaded (FIRECRAWL_API_KEY set). They have gif-search, duckduckgo-search, linux-rescue, and axolotl installed. The Level 0 index they see contains only gif-search and axolotl: duckduckgo-search hides because web is available (it is a fallback), and linux-rescue hides because platforms: [linux]. The agent picks cleanly because the irrelevant noise is filtered out automatically.

Deep Dive

A Hermes session can compose skills in three ways:

Sequential composition. The user runs /plan migrate auth, the agent writes a plan, the user then runs /github-pr-workflow open a PR for the plan. Two skills, one after the other, each contributing to a multi-step task. The session loads Level 1 for each only when the agent activates it.

Supporting composition. A primary skill calls out to a supporting one. For example, a deploy-runbook skill might reference an incident-response skill in its ## Pitfalls section. The agent, reading the runbook, can choose to also activate the response skill if things go sideways.

Conditional composition. Skills automatically appear or disappear based on environment. This is what makes the index stay clean across very different setups.

Four frontmatter fields drive conditional activation:

yaml
metadata:
  hermes:
    fallback_for_toolsets: [web]      # hide when 'web' toolset is loaded
    fallback_for_tools: [web_search]  # hide when 'web_search' tool is available
    requires_toolsets: [terminal]     # hide when 'terminal' toolset is NOT loaded
    requires_tools: [gh_create_pr]    # hide when this specific tool is missing

The fallback_for_* fields let you ship free-tier skills that step in when premium tools are absent. The requires_* fields let you ship skills that should only appear when their prerequisites are present. The result: the index the agent sees adapts to the current capabilities.

Platform gating adds OS-level filtering:

yaml
platforms: [macos, linux]   # hide on Windows
platforms: [macos]          # macOS only

A few composition patterns are worth knowing:

  • Fallback pairs: Ship a premium skill (firecrawl-search) and a fallback (duckduckgo-search) with fallback_for_toolsets: [web]. Users only see one depending on their API key state.
  • Toolset bundles: Group skills under a single category and require the same toolset. A team's aws-* skills can all declare requires_toolsets: [terminal].
  • Platform-specific runbooks: A linux-rescue skill for SREs and a macos-debugging skill for laptops can coexist; each hides on the other platform.

Index hygiene matters because Level 0 is small but not free. If you install fifty skills with overlapping descriptions, the agent will burn a few extra cycles disambiguating. Prune what you do not use:

bash
hermes skills list
hermes skills uninstall some-skill

Common Pitfalls

  1. Overusing requires_toolsets: It is tempting to mark every skill requires-something. But a skill that only requires terminal (almost always loaded) just adds noise. Use the field for genuine dependencies.
  2. Hiding skills the agent should still know exist: If a skill is unavailable because its toolset is missing, the agent will not suggest installing the prerequisite. Sometimes you want the skill visible with a clear pitfall in the body.

Best Practices

  1. Use fallback pairs to scale across user environments: One repo, two skills with mirrored frontmatter, every user sees exactly the one that fits their setup.
  2. Audit your installed set occasionally: hermes skills list | wc -l followed by hermes skills uninstall ... for the deadwood.

Summary

  • A session can use many skills sequentially, in support of each other, or conditionally.
  • fallback_for_* and requires_* frontmatter fields filter the Level 0 index by tool/toolset availability.
  • platforms filters by operating system.
  • Index hygiene (pruning, sharp descriptions) keeps composition cheap and predictable.

Code Examples

yaml
# Fallback skill: appears only when the premium web toolset is missing
---
name: duckduckgo-search
description: Web search via DuckDuckGo when no premium web toolset is configured
metadata:
  hermes:
    fallback_for_toolsets: [web]
---
# DuckDuckGo Search
## When to Use
The user asks a web search question and the premium 'web' toolset is not available.
## Procedure
...

# Required-tool skill: hides if the GitHub MCP server is not loaded
---
name: pr-from-branch
description: Open a clean PR from the current branch using the GitHub MCP tools
metadata:
  hermes:
    requires_tools: [gh_create_pr]
platforms: [macos, linux]
---
✓ Completed