From 82113f1f1edd133251c38618bc541dd9361454c1 Mon Sep 17 00:00:00 2001 From: teknium1 Date: Wed, 11 Mar 2026 08:47:01 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20conditional=20skill=20activation=20?= =?UTF-8?q?=E2=80=94=20tag=20duckduckgo-search=20as=20web=20fallback=20and?= =?UTF-8?q?=20add=20documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Tag duckduckgo-search skill with fallback_for_toolsets: [web] so it auto-hides when Firecrawl is available and auto-shows when it isn't - Add 'Conditional Activation' section to CONTRIBUTING.md with full spec, semantics, and examples for all 4 frontmatter fields - Add 'Conditional Activation (Fallback Skills)' section to the user- facing skills docs with field reference table and practical example - Update SKILL.md format examples in both docs to show the new fields Follow-up to PR #785 (conditional skill activation feature). --- CONTRIBUTING.md | 44 ++++++++++++++++++++++ skills/research/duckduckgo-search/SKILL.md | 1 + website/docs/user-guide/features/skills.md | 26 +++++++++++++ 3 files changed, 71 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e66dbb3e..60e8706b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -333,6 +333,8 @@ metadata: hermes: tags: [Category, Subcategory, Keywords] related_skills: [other-skill-name] + fallback_for_toolsets: [web] # Optional — show only when toolset is unavailable + requires_toolsets: [terminal] # Optional — show only when toolset is available --- # Skill Title @@ -367,6 +369,48 @@ platforms: [windows] # Windows only If the field is omitted or empty, the skill loads on all platforms (backward compatible). See `skills/apple/` for examples of macOS-only skills. +### Conditional skill activation + +Skills can declare conditions that control when they appear in the system prompt, based on which tools and toolsets are available in the current session. This is primarily used for **fallback skills** — alternatives that should only be shown when a primary tool is unavailable. + +Four fields are supported under `metadata.hermes`: + +```yaml +metadata: + hermes: + fallback_for_toolsets: [web] # Show ONLY when these toolsets are unavailable + requires_toolsets: [terminal] # Show ONLY when these toolsets are available + fallback_for_tools: [web_search] # Show ONLY when these specific tools are unavailable + requires_tools: [terminal] # Show ONLY when these specific tools are available +``` + +**Semantics:** +- `fallback_for_*`: The skill is a backup. It is **hidden** when the listed tools/toolsets are available, and **shown** when they are unavailable. Use this for free alternatives to premium tools. +- `requires_*`: The skill needs certain tools to function. It is **hidden** when the listed tools/toolsets are unavailable. Use this for skills that depend on specific capabilities (e.g., a skill that only makes sense with terminal access). +- If both are specified, both conditions must be satisfied for the skill to appear. +- If neither is specified, the skill is always shown (backward compatible). + +**Examples:** + +```yaml +# DuckDuckGo search — shown when Firecrawl (web toolset) is unavailable +metadata: + hermes: + fallback_for_toolsets: [web] + +# Smart home skill — only useful when terminal is available +metadata: + hermes: + requires_toolsets: [terminal] + +# Local browser fallback — shown when Browserbase is unavailable +metadata: + hermes: + fallback_for_toolsets: [browser] +``` + +The filtering happens at prompt build time in `agent/prompt_builder.py`. The `build_skills_system_prompt()` function receives the set of available tools and toolsets from the agent and uses `_skill_should_show()` to evaluate each skill's conditions. + ### Skill guidelines - **No external dependencies unless absolutely necessary.** Prefer stdlib Python, curl, and existing Hermes tools (`web_extract`, `terminal`, `read_file`). diff --git a/skills/research/duckduckgo-search/SKILL.md b/skills/research/duckduckgo-search/SKILL.md index 6081581e..afe7858a 100644 --- a/skills/research/duckduckgo-search/SKILL.md +++ b/skills/research/duckduckgo-search/SKILL.md @@ -8,6 +8,7 @@ metadata: hermes: tags: [search, duckduckgo, web-search, free, fallback] related_skills: [arxiv] + fallback_for_toolsets: [web] --- # DuckDuckGo Search diff --git a/website/docs/user-guide/features/skills.md b/website/docs/user-guide/features/skills.md index 8eb838d2..8f02be20 100644 --- a/website/docs/user-guide/features/skills.md +++ b/website/docs/user-guide/features/skills.md @@ -55,6 +55,8 @@ metadata: hermes: tags: [python, automation] category: devops + fallback_for_toolsets: [web] # Optional — conditional activation (see below) + requires_toolsets: [terminal] # Optional — conditional activation (see below) --- # Skill Title @@ -90,6 +92,30 @@ platforms: [macos, linux] # macOS and Linux When set, the skill is automatically hidden from the system prompt, `skills_list()`, and slash commands on incompatible platforms. If omitted, the skill loads on all platforms. +### Conditional Activation (Fallback Skills) + +Skills can automatically show or hide themselves based on which tools are available in the current session. This is most useful for **fallback skills** — free or local alternatives that should only appear when a premium tool is unavailable. + +```yaml +metadata: + hermes: + fallback_for_toolsets: [web] # Show ONLY when these toolsets are unavailable + requires_toolsets: [terminal] # Show ONLY when these toolsets are available + fallback_for_tools: [web_search] # Show ONLY when these specific tools are unavailable + requires_tools: [terminal] # Show ONLY when these specific tools are available +``` + +| Field | Behavior | +|-------|----------| +| `fallback_for_toolsets` | Skill is **hidden** when the listed toolsets are available. Shown when they're missing. | +| `fallback_for_tools` | Same, but checks individual tools instead of toolsets. | +| `requires_toolsets` | Skill is **hidden** when the listed toolsets are unavailable. Shown when they're present. | +| `requires_tools` | Same, but checks individual tools. | + +**Example:** The built-in `duckduckgo-search` skill uses `fallback_for_toolsets: [web]`. When you have `FIRECRAWL_API_KEY` set, the web toolset is available and the agent uses `web_search` — the DuckDuckGo skill stays hidden. If the API key is missing, the web toolset is unavailable and the DuckDuckGo skill automatically appears as a fallback. + +Skills without any conditional fields behave exactly as before — they're always shown. + ## Skill Directory Structure ```