Skip to content

The agent that grows with you

chore(skills): move niche built-in skills to optional

Teknium183b5ddd5fbc
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cee00aff123..f5cdc740411 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -601,7 +601,7 @@ Gateway and messaging sessions never collect secrets in-band; they instruct the
- The skill relies on a CLI tool that may not be installed (e.g., `himalaya`, `openhue`, `ddgs`)
- Treat command checks as guidance, not discovery-time hiding
-See `skills/gifs/gif-search/` and `skills/email/himalaya/` for examples.
+See `optional-skills/media/gif-search/` and `skills/email/himalaya/` for examples.
### Skill authoring standards (HARDLINE)
diff --git a/agent/onboarding_first_tasks.py b/agent/onboarding_first_tasks.py
index 9ae23325be5..f5daeb09a33 100644
--- a/agent/onboarding_first_tasks.py
+++ b/agent/onboarding_first_tasks.py
@@ -171,7 +171,7 @@ FIRST_TASKS: tuple[FirstTask, ...] = (
quality="Real items they asked for. No test items.",
done="The reminder and note exist, and the morning job is set up or declined."),
FirstTask(
- "notes", "Turn my notes into a wiki", _always, ("obsidian", "llm-wiki"),
+ "notes", "Turn my notes into a wiki", _always, ("obsidian",),
goal="turn their notes into a small linked wiki",
steps=(
"Ask which folder holds their notes. Never search the disk for it.",
@@ -223,7 +223,7 @@ FIRST_TASKS: tuple[FirstTask, ...] = (
quality="Every finding has a source link. Nothing invented.",
done="The first report is shown and the daily job is set up or declined."),
FirstTask(
- "site", "Design a page for me", _always, ("claude-design", "popular-web-designs", "design-md", "p5js"),
+ "site", "Design a page for me", _always, ("claude-design", "popular-web-designs", "p5js"),
goal="design one web page for them",
steps=(
"If you do not know what the page is for, ask in one line.",
diff --git a/skills/autonomous-ai-agents/opencode/SKILL.md b/optional-skills/autonomous-ai-agents/opencode/SKILL.md
similarity index 100%
rename from skills/autonomous-ai-agents/opencode/SKILL.md
rename to optional-skills/autonomous-ai-agents/opencode/SKILL.md
diff --git a/skills/creative/design-md/SKILL.md b/optional-skills/creative/design-md/SKILL.md
similarity index 100%
rename from skills/creative/design-md/SKILL.md
rename to optional-skills/creative/design-md/SKILL.md
diff --git a/skills/creative/design-md/templates/starter.md b/optional-skills/creative/design-md/templates/starter.md
similarity index 100%
rename from skills/creative/design-md/templates/starter.md
rename to optional-skills/creative/design-md/templates/starter.md
diff --git a/optional-skills/media/DESCRIPTION.md b/optional-skills/media/DESCRIPTION.md
new file mode 100644
index 00000000000..50453dc5faf
--- /dev/null
+++ b/optional-skills/media/DESCRIPTION.md
@@ -0,0 +1,3 @@
+---
+description: Optional media skills — GIF search and audio visualization.
+---
diff --git a/skills/media/gif-search/SKILL.md b/optional-skills/media/gif-search/SKILL.md
similarity index 100%
rename from skills/media/gif-search/SKILL.md
rename to optional-skills/media/gif-search/SKILL.md
diff --git a/skills/media/songsee/SKILL.md b/optional-skills/media/songsee/SKILL.md
similarity index 100%
rename from skills/media/songsee/SKILL.md
rename to optional-skills/media/songsee/SKILL.md
diff --git a/skills/productivity/airtable/SKILL.md b/optional-skills/productivity/airtable/SKILL.md
similarity index 100%
rename from skills/productivity/airtable/SKILL.md
rename to optional-skills/productivity/airtable/SKILL.md
diff --git a/skills/productivity/box/SKILL.md b/optional-skills/productivity/box/SKILL.md
similarity index 100%
rename from skills/productivity/box/SKILL.md
rename to optional-skills/productivity/box/SKILL.md
diff --git a/skills/productivity/box/references/bulk-operations.md b/optional-skills/productivity/box/references/bulk-operations.md
similarity index 100%
rename from skills/productivity/box/references/bulk-operations.md
rename to optional-skills/productivity/box/references/bulk-operations.md
diff --git a/skills/productivity/box/references/cli-guide.md b/optional-skills/productivity/box/references/cli-guide.md
similarity index 100%
rename from skills/productivity/box/references/cli-guide.md
rename to optional-skills/productivity/box/references/cli-guide.md
diff --git a/skills/productivity/box/references/content-workflows.md b/optional-skills/productivity/box/references/content-workflows.md
similarity index 100%
rename from skills/productivity/box/references/content-workflows.md
rename to optional-skills/productivity/box/references/content-workflows.md
diff --git a/skills/productivity/box/references/hubs.md b/optional-skills/productivity/box/references/hubs.md
similarity index 100%
rename from skills/productivity/box/references/hubs.md
rename to optional-skills/productivity/box/references/hubs.md
diff --git a/skills/productivity/box/references/oauth-setup.md b/optional-skills/productivity/box/references/oauth-setup.md
similarity index 100%
rename from skills/productivity/box/references/oauth-setup.md
rename to optional-skills/productivity/box/references/oauth-setup.md
diff --git a/skills/productivity/box/references/rest-api.md b/optional-skills/productivity/box/references/rest-api.md
similarity index 100%
rename from skills/productivity/box/references/rest-api.md
rename to optional-skills/productivity/box/references/rest-api.md
diff --git a/skills/productivity/box/references/sdk-development.md b/optional-skills/productivity/box/references/sdk-development.md
similarity index 100%
rename from skills/productivity/box/references/sdk-development.md
rename to optional-skills/productivity/box/references/sdk-development.md
diff --git a/skills/productivity/box/references/search-and-ai.md b/optional-skills/productivity/box/references/search-and-ai.md
similarity index 100%
rename from skills/productivity/box/references/search-and-ai.md
rename to optional-skills/productivity/box/references/search-and-ai.md
diff --git a/skills/productivity/box/references/troubleshooting.md b/optional-skills/productivity/box/references/troubleshooting.md
similarity index 100%
rename from skills/productivity/box/references/troubleshooting.md
rename to optional-skills/productivity/box/references/troubleshooting.md
diff --git a/skills/productivity/box/references/webhooks-and-events.md b/optional-skills/productivity/box/references/webhooks-and-events.md
similarity index 100%
rename from skills/productivity/box/references/webhooks-and-events.md
rename to optional-skills/productivity/box/references/webhooks-and-events.md
diff --git a/skills/productivity/notion/SKILL.md b/optional-skills/productivity/notion/SKILL.md
similarity index 100%
rename from skills/productivity/notion/SKILL.md
rename to optional-skills/productivity/notion/SKILL.md
diff --git a/skills/productivity/notion/references/block-types.md b/optional-skills/productivity/notion/references/block-types.md
similarity index 100%
rename from skills/productivity/notion/references/block-types.md
rename to optional-skills/productivity/notion/references/block-types.md
diff --git a/skills/research/llm-wiki/SKILL.md b/optional-skills/research/llm-wiki/SKILL.md
similarity index 100%
rename from skills/research/llm-wiki/SKILL.md
rename to optional-skills/research/llm-wiki/SKILL.md
diff --git a/skills/software-development/hermes-agent-skill-authoring/SKILL.md b/optional-skills/software-development/hermes-agent-skill-authoring/SKILL.md
similarity index 100%
rename from skills/software-development/hermes-agent-skill-authoring/SKILL.md
rename to optional-skills/software-development/hermes-agent-skill-authoring/SKILL.md
diff --git a/skills/software-development/inspecting-hermes-desktop-dom/SKILL.md b/optional-skills/software-development/inspecting-hermes-desktop-dom/SKILL.md
similarity index 100%
rename from skills/software-development/inspecting-hermes-desktop-dom/SKILL.md
rename to optional-skills/software-development/inspecting-hermes-desktop-dom/SKILL.md
diff --git a/skills/software-development/node-inspect-debugger/SKILL.md b/optional-skills/software-development/node-inspect-debugger/SKILL.md
similarity index 100%
rename from skills/software-development/node-inspect-debugger/SKILL.md
rename to optional-skills/software-development/node-inspect-debugger/SKILL.md
diff --git a/skills/software-development/python-debugpy/SKILL.md b/optional-skills/software-development/python-debugpy/SKILL.md
similarity index 100%
rename from skills/software-development/python-debugpy/SKILL.md
rename to optional-skills/software-development/python-debugpy/SKILL.md
diff --git a/skills/creative/claude-design/SKILL.md b/skills/creative/claude-design/SKILL.md
index d67fa6ce1ba..1e6382d9ea6 100644
--- a/skills/creative/claude-design/SKILL.md
+++ b/skills/creative/claude-design/SKILL.md
@@ -17,7 +17,7 @@ Use this skill when the user asks for design work that would normally fit Claude
The goal is to preserve Claude Design's useful design behavior and taste while removing hosted-tool plumbing that does not exist in normal agent environments.
-**Before starting, check for other web-design skills like `popular-web-designs` (ready-to-paste design systems for Stripe, Linear, Vercel, Notion, etc.) and `design-md` (Google's DESIGN.md token spec format).** If the user wants a known brand's look, load `popular-web-designs` alongside this one and let it supply the visual vocabulary. If the deliverable is a token spec file rather than a rendered artifact, use `design-md` instead. Full decision table below.
+**Before starting, check for other web-design skills like `popular-web-designs` (ready-to-paste design systems for Stripe, Linear, Vercel, Notion, etc.) and `design-md` (Google's DESIGN.md token spec format; an optional skill, installed with `hermes skills install official/creative/design-md`).** If the user wants a known brand's look, load `popular-web-designs` alongside this one and let it supply the visual vocabulary. If the deliverable is a token spec file rather than a rendered artifact, use `design-md` instead. Full decision table below.
## When To Use This Skill vs `popular-web-designs` vs `design-md`
diff --git a/skills/creative/popular-web-designs/SKILL.md b/skills/creative/popular-web-designs/SKILL.md
index 8b569397f57..a45e2e504fe 100644
--- a/skills/creative/popular-web-designs/SKILL.md
+++ b/skills/creative/popular-web-designs/SKILL.md
@@ -31,8 +31,8 @@ system, shadows, responsive behavior, and practical agent prompts with exact CSS
Pair it with this skill when the user wants a thoughtfully-designed page styled
after a known brand: `claude-design` drives the workflow, this skill supplies
the visual vocabulary.
-- **`design-md`** — use when the deliverable is a formal DESIGN.md token spec
- file, not a rendered artifact.
+- **`design-md`** (optional: `hermes skills install official/creative/design-md`) —
+ use when the deliverable is a formal DESIGN.md token spec file, not a rendered artifact.
## How to Use
diff --git a/skills/media/DESCRIPTION.md b/skills/media/DESCRIPTION.md
index f9bfe046988..61e3de7d895 100644
--- a/skills/media/DESCRIPTION.md
+++ b/skills/media/DESCRIPTION.md
@@ -1,3 +1,3 @@
---
-description: Skills for working with media content — YouTube transcripts, GIF search, music generation, and audio visualization.
+description: Skills for working with media content — YouTube transcripts and summaries.
---
diff --git a/tests/hermes_cli/test_skills_hub.py b/tests/hermes_cli/test_skills_hub.py
index 89ec80ee7a6..2058aa3ac2e 100644
--- a/tests/hermes_cli/test_skills_hub.py
+++ b/tests/hermes_cli/test_skills_hub.py
@@ -747,7 +747,7 @@ def test_install_by_name_resolves_to_the_skill_it_names(monkeypatch, tmp_path, i
def test_built_in_restore_survives_leftovers_and_records_every_outcome_as_bundled(monkeypatch, tmp_path):
- """Post-fix telemetry still showed `llm-wiki` failing as source=hub, filesystem_error: the
+ """Post-fix telemetry still showed `llm-wiki` (bundled then) failing as source=hub, filesystem_error: the
restore copied with copytree onto a dest dir left behind without its SKILL.md (EEXIST on every
retry), refused a skill already present behind a symlinked category the loader follows, and a
failed restore was labelled a hub install."""
@@ -761,22 +761,22 @@ def test_built_in_restore_survives_leftovers_and_records_every_outcome_as_bundle
rows = []
monkeypatch.setattr("hermes_cli.observability.shared_metrics_events.record_extension_install",
lambda **row: rows.append((row["source"], row["outcome"])))
- src = dict(skills_sync._discover_bundled_skills(skills_sync._get_bundled_dir()))["llm-wiki"]
- dest = skill_usage._skills_dir() / src.parent.name / "llm-wiki"
+ src = dict(skills_sync._discover_bundled_skills(skills_sync._get_bundled_dir()))["obsidian"]
+ dest = skill_usage._skills_dir() / src.parent.name / "obsidian"
console, _sink = _sink_console()
(dest / "wiki").mkdir(parents=True) # stranded: user data kept, SKILL.md gone
(dest / "wiki" / "index.md").write_text("mine\n")
- assert cli_hub.do_install("llm-wiki", console=console, skip_confirm=True) is True
+ assert cli_hub.do_install("obsidian", console=console, skip_confirm=True) is True
assert (dest / "SKILL.md").is_file() and (dest / "wiki" / "index.md").read_text() == "mine\n"
real = tmp_path / "real-category"
dest.parent.rename(real)
dest.parent.symlink_to(real, target_is_directory=True)
- assert cli_hub.do_install("llm-wiki", console=console, skip_confirm=True) is None # present, no-op
+ assert cli_hub.do_install("obsidian", console=console, skip_confirm=True) is None # present, no-op
- (real / "llm-wiki" / "SKILL.md").unlink() # missing behind the symlink: refused, and still bundled
- assert cli_hub.do_install("llm-wiki", console=console, skip_confirm=True) is False
+ (real / "obsidian" / "SKILL.md").unlink() # missing behind the symlink: refused, and still bundled
+ assert cli_hub.do_install("obsidian", console=console, skip_confirm=True) is False
assert rows == [("bundled", "success"), ("bundled", "failed")]
diff --git a/website/docs/reference/slash-commands.md b/website/docs/reference/slash-commands.md
index 00fd3815f4c..176a8fb91a7 100644
--- a/website/docs/reference/slash-commands.md
+++ b/website/docs/reference/slash-commands.md
@@ -157,7 +157,7 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
| Command | Description |
|---------|-------------|
-| `/<skill-name>` | Load any installed skill as an on-demand command. Example: `/gif-search`, `/github-pr-workflow`, `/excalidraw`. |
+| `/<skill-name>` | Load any installed skill as an on-demand command. Example: `/youtube-content`, `/github-pr-workflow`, `/excalidraw`. |
| `/skills ...` | Search, browse, inspect, install, audit, publish, and configure skills from registries and the official optional-skills catalog. |
### Quick Commands
diff --git a/website/docs/user-guide/cli.md b/website/docs/user-guide/cli.md
index 2adca4b4c50..d88f366bcee 100644
--- a/website/docs/user-guide/cli.md
+++ b/website/docs/user-guide/cli.md
@@ -384,7 +384,7 @@ Each entry is a skill name. The list is resolved once when a session's system pr
Every installed skill in `~/.hermes/skills/` is automatically registered as a slash command. The skill name becomes the command:
```
-/gif-search funny cats
+/excalidraw sketch the request flow for our API
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor
diff --git a/website/docs/user-guide/messaging/telegram.md b/website/docs/user-guide/messaging/telegram.md
index 2ab887a536b..557ecc24a24 100644
--- a/website/docs/user-guide/messaging/telegram.md
+++ b/website/docs/user-guide/messaging/telegram.md
@@ -176,7 +176,7 @@ platforms:
priority_mode: prepend # prepend | append | replace
priority:
- my_plugin_command
- - songsee # skill commands work here too
+ - excalidraw # skill commands work here too
```
`priority_mode` controls how your list combines with Hermes' built-in priority list: