Conditional Activation: Context-Aware Skills
- Use fallback_for_toolsets and requires_toolsets to show or hide skills based on which toolsets are available in the current session
- Apply fallback_for_tools and requires_tools for tool-level conditional activation within a toolset
- Configure external skill directories in config.yaml to enable team-shared libraries with environment variable path expansion
Why One-Size Skills Do Not Fit All Platforms
Hermes runs in many environments: a developer's local terminal, a team's Slack workspace, a web dashboard, a Discord server, a WhatsApp group. Each environment has a different set of tools available. A skill that relies on the terminal toolset works fine in the CLI but is meaningless in a messaging platform where terminal access is not present. A skill that provides a DuckDuckGo search procedure is redundant if the web toolset is already installed and provides a better search capability.
Conditional activation solves this by making skill visibility dynamic. Rather than maintaining separate skill libraries for different environments, you write skills that know when they should appear and when they should stay hidden. The agent's Level 0 scan reflects the filtered view — skills outside their activation conditions do not show up at all, keeping the metadata compact and the agent's decision space clean.
fallback_for_toolsets: The Fallback Pattern
The most common conditional activation pattern is the fallback: a skill that provides functionality only when the preferred toolset for that functionality is not available.
The fallback_for_toolsets field contains an array of toolset names. When any of the listed toolsets is present in the current session, the skill is hidden. When none of the listed toolsets is present, the skill becomes visible.
The classic example is web search. Hermes has a web toolset that provides full-featured browser-based search. A DuckDuckGo skill provides search capability using only the terminal tool (via curl). In environments where the web toolset is installed, you want the web toolset to handle search — the DuckDuckGo skill would be redundant. In environments without the web toolset (a restricted server, for example), the DuckDuckGo skill becomes the agent's best available option.
The frontmatter for this skill would include:
fallback_for_toolsets: [web]
With this configuration, the skill is invisible in any session where the web toolset is present and visible in any session where it is not. Zero configuration required from the user.
requires_toolsets: The Requirement Pattern
The inverse pattern: a skill that should only appear when a specific toolset is present. Use requires_toolsets to hide skills that depend on tools that are not universally available.
For example, a skill that automates operations in a Docker environment makes no sense in a session without the Docker toolset. Rather than loading the skill and having every Docker command fail, configure it to only appear when Docker tools are present:
requires_toolsets: [docker]
This pattern keeps the Level 0 metadata accurate across different environments. A user without Docker never sees a Docker skill in their skills list. A user with Docker always has it available. The same skill file works correctly in both cases without any environment-specific configuration.
Tool-Level Precision: fallback_for_tools and requires_tools
The toolset-level fields control visibility based on an entire toolset being present or absent. Sometimes you need finer-grained control — visibility based on whether a specific tool within a toolset is available.
fallback_for_tools works like fallback_for_toolsets but checks for individual tool names rather than full toolsets. The skill is hidden when any of the listed tools is present and visible when none are present. Use this when a toolset includes multiple tools and you only want to fall back on the absence of a specific one.
requires_tools is the mirror: the skill is visible only when all of the listed tools are present. Use this for skills that depend on specific tools within a broader toolset that is not uniformly deployed.
In practice, toolset-level conditions handle the majority of real-world scenarios. Tool-level conditions are useful when a platform provides a toolset but omits specific tools within it — for example, a hosted environment that includes the development toolset but excludes the code execution tool for security reasons.
Designing Platform-Adaptive Skills
The conditional activation fields let you build skills that adapt gracefully across Hermes deployment contexts without maintaining separate versions for each platform.
A well-designed adaptive skill starts with an honest assessment of its dependencies. What toolsets does this skill need to work correctly? What tools within those toolsets are essential? Then:
- If the skill requires a toolset that may not be present, add
requires_toolsetsto prevent the skill from cluttering the list when it cannot function - If the skill is a fallback for a capability that a better toolset provides, add
fallback_for_toolsetsto suppress the skill when the better option is available - If the skill works in all environments, leave both fields empty — universal skills need no conditional activation
A complementary approach: pair skills for the same task at different capability levels. A sophisticated web research skill requires the web toolset; a simpler curl-based research skill is a fallback for the web toolset. Together they provide research capability in any Hermes environment, with the agent automatically using the best available option.
External Directories: Team-Shared Skill Libraries
Skills do not have to live in ~/.hermes/skills/. You can configure additional skill directories in config.yaml, and the agent treats them as part of the installed skill library:
skills: external_dirs: - ~/.agents/shared-skills - /home/shared/team-skills - ${SKILLS_REPO}/skills
Environment variables and tilde expansion work in path values. Non-existent paths are silently skipped — no errors if a configured directory is not present on a particular machine.
Local skills (in ~/.hermes/skills/) take precedence over external directory skills when names conflict. External directories are scanned in the order they appear in the config. This precedence order lets team members maintain personal overrides of shared skills without modifying the shared library.
Team-shared skill libraries are one of the most impactful applications of the Skills system in professional settings. A team can maintain a repository of skills for their internal tools, deployment procedures, and code review standards. Every team member who points an external_dirs entry at that repository gets the same skill library, with automatic updates whenever the repository changes.
- fallback_for_toolsets hides a skill when listed toolsets are present and reveals it when they are absent — enabling graceful degradation to simpler procedures in restricted environments.
- requires_toolsets is the inverse: the skill is visible only when all listed toolsets are present — preventing tool-dependent skills from cluttering the list in environments where they cannot function.
- fallback_for_tools and requires_tools provide tool-level precision within a toolset — useful when a platform provides a toolset but omits specific tools for security or configuration reasons.
- Designing adaptive skills means assessing tool dependencies first, then configuring conditional fields to ensure the skill is available exactly when it can function and invisible when it cannot.
- External directories in config.yaml support tilde expansion, environment variables, and silently skip missing paths — the right mechanism for team-shared skill libraries that need to work across different developer machines.