From 235bfb192b91cbb496f5f635d3fffaa9174abd1d Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Sun, 26 Apr 2026 21:27:59 -0700 Subject: [PATCH] docs(skills): document URL install across features, reference, guide, and hermes-agent skill (#16355) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-up to #16323 — the UrlSource adapter is shipped but four user-facing docs surfaces still only listed the hub-identifier forms. - user-guide/features/skills.md: add ``url`` to the Supported-hub-sources table; add a new "#### 8. Direct URL (`url`)" section explaining scope (single-file SKILL.md only), name-resolution order (frontmatter → URL slug → interactive prompt → --name flag), and both TTY and non-interactive usage. Add two URL examples to the install-examples block near the top of the page. - reference/cli-commands.md: two URL install examples + one note explaining the name-resolution fallback chain. - guides/work-with-skills.md: one URL-install example alongside the existing hub-identifier examples. - skills/autonomous-ai-agents/hermes-agent/SKILL.md: Quick Reference block's ``hermes skills install`` line now spells out that ID can be a hub identifier OR a direct SKILL.md URL, and mentions --name for frontmatter-less skills. No code changes. No new dependencies. Website builds via the usual Docusaurus pipeline. Co-authored-by: teknium1 --- .../hermes-agent/SKILL.md | 2 +- website/docs/guides/work-with-skills.md | 4 +++ website/docs/reference/cli-commands.md | 3 ++ website/docs/user-guide/features/skills.md | 32 +++++++++++++++++++ 4 files changed, 40 insertions(+), 1 deletion(-) diff --git a/skills/autonomous-ai-agents/hermes-agent/SKILL.md b/skills/autonomous-ai-agents/hermes-agent/SKILL.md index 4603a37e2d..9cbd5ea203 100644 --- a/skills/autonomous-ai-agents/hermes-agent/SKILL.md +++ b/skills/autonomous-ai-agents/hermes-agent/SKILL.md @@ -115,7 +115,7 @@ hermes tools disable NAME Disable a toolset hermes skills list List installed skills hermes skills search QUERY Search the skills hub -hermes skills install ID Install a skill +hermes skills install ID Install a skill (ID can be a hub identifier OR a direct https://…/SKILL.md URL; pass --name to override when frontmatter has no name) hermes skills inspect ID Preview without installing hermes skills config Enable/disable skills per platform hermes skills check Check for updates diff --git a/website/docs/guides/work-with-skills.md b/website/docs/guides/work-with-skills.md index 80b43f83df..0798ccfd44 100644 --- a/website/docs/guides/work-with-skills.md +++ b/website/docs/guides/work-with-skills.md @@ -94,6 +94,10 @@ hermes skills install official/research/arxiv # Install from the hub in a chat session /skills install official/creative/songwriting-and-ai-music + +# Install a single-file SKILL.md directly from any HTTP(S) URL +hermes skills install https://sharethis.chat/SKILL.md +/skills install https://example.com/SKILL.md --name my-skill ``` What happens: diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md index 9a804859eb..0a5d57cc47 100644 --- a/website/docs/reference/cli-commands.md +++ b/website/docs/reference/cli-commands.md @@ -617,6 +617,8 @@ hermes skills inspect official/security/1password hermes skills inspect skills-sh/vercel-labs/json-render/json-render-react hermes skills install official/migration/openclaw-migration hermes skills install skills-sh/anthropics/skills/pdf --force +hermes skills install https://sharethis.chat/SKILL.md # Direct URL (single-file SKILL.md) +hermes skills install https://example.com/SKILL.md --name my-skill # Override name when frontmatter has none hermes skills check hermes skills update hermes skills config @@ -627,6 +629,7 @@ Notes: - `--force` does not override a `dangerous` scan verdict. - `--source skills-sh` searches the public `skills.sh` directory. - `--source well-known` lets you point Hermes at a site exposing `/.well-known/skills/index.json`. +- Passing an `http(s)://…/*.md` URL installs a single-file SKILL.md directly. When frontmatter has no `name:` and the URL slug isn't a valid identifier, an interactive terminal prompts for a name; non-interactive surfaces (`/skills install` inside the TUI, gateway platforms) require `--name ` instead. ## `hermes honcho` diff --git a/website/docs/user-guide/features/skills.md b/website/docs/user-guide/features/skills.md index 58cbd663e9..f0c1b34fd4 100644 --- a/website/docs/user-guide/features/skills.md +++ b/website/docs/user-guide/features/skills.md @@ -273,6 +273,8 @@ hermes skills install openai/skills/k8s # Install with security scan hermes skills install official/security/1password hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify +hermes skills install https://sharethis.chat/SKILL.md # Direct URL (single-file SKILL.md) +hermes skills install https://example.com/SKILL.md --name my-skill # Override name when frontmatter has none hermes skills list --source hub # List hub-installed skills hermes skills check # Check installed hub skills for upstream updates hermes skills update # Reinstall hub skills with upstream changes when needed @@ -292,6 +294,7 @@ hermes skills tap add myorg/skills-repo # Add a custom GitHub source | `official` | `official/security/1password` | Optional skills shipped with Hermes. | | `skills-sh` | `skills-sh/vercel-labs/agent-skills/vercel-react-best-practices` | Searchable via `hermes skills search --source skills-sh`. Hermes resolves alias-style skills when the skills.sh slug differs from the repo folder. | | `well-known` | `well-known:https://mintlify.com/docs/.well-known/skills/mintlify` | Skills served directly from `/.well-known/skills/index.json` on a website. Search using the site or docs URL. | +| `url` | `https://sharethis.chat/SKILL.md` | Direct HTTP(S) URL to a single-file `SKILL.md`. Name resolution: frontmatter → URL slug → interactive prompt → `--name` flag. | | `github` | `openai/skills/k8s` | Direct GitHub repo/path installs and custom taps. | | `clawhub`, `lobehub`, `claude-marketplace` | Source-specific identifiers | Community or marketplace integrations. | @@ -384,6 +387,35 @@ Hermes can search and convert agent entries from LobeHub's public catalog into i - Backing repo: [lobehub/lobe-chat-agents](https://github.com/lobehub/lobe-chat-agents) - Hermes source id: `lobehub` +#### 8. Direct URL (`url`) + +Install a single-file `SKILL.md` directly from any HTTP(S) URL — useful when an author hosts a skill on their own site (no hub listing, no GitHub path to type). Hermes fetches the URL, parses the YAML frontmatter, security-scans it, and installs. + +- Hermes source id: `url` +- Identifier: the URL itself (no prefix needed) +- Scope: **single-file `SKILL.md`** only. Multi-file skills with `references/` or `scripts/` need a manifest and should be published via one of the other sources above. + +```bash +hermes skills install https://sharethis.chat/SKILL.md +hermes skills install https://example.com/my-skill/SKILL.md --category productivity +``` + +Name resolution, in order: +1. `name:` field in the SKILL.md YAML frontmatter (recommended — every well-formed skill has one). +2. Parent directory name from the URL path (e.g. `.../my-skill/SKILL.md` → `my-skill`, or `.../my-skill.md` → `my-skill`), when it's a valid identifier (`^[a-z][a-z0-9_-]*$`). +3. Interactive prompt on a terminal with a TTY. +4. On non-interactive surfaces (the `/skills install` slash command inside the TUI, gateway platforms, scripts), a clean error pointing at the `--name` override. + +```bash +# Frontmatter has no name and the URL slug is unhelpful — supply one: +hermes skills install https://example.com/SKILL.md --name sharethis-chat + +# Or inside a chat session: +/skills install https://example.com/SKILL.md --name sharethis-chat +``` + +Trust level is always `community` — the same security scan runs as for every other source. The URL is stored as the install identifier, so `hermes skills update` re-fetches from the same URL automatically when you want to refresh. + ### Security scanning and `--force` All hub-installed skills go through a **security scanner** that checks for data exfiltration, prompt injection, destructive commands, supply-chain signals, and other threats.