diff --git a/website/docs/developer-guide/creating-skills.md b/website/docs/developer-guide/creating-skills.md index ccec47c26..d3f0aeb57 100644 --- a/website/docs/developer-guide/creating-skills.md +++ b/website/docs/developer-guide/creating-skills.md @@ -173,4 +173,11 @@ Trust levels: - `builtin` — ships with Hermes (always trusted) - `official` — from `optional-skills/` in the repo (builtin trust, no third-party warning) - `trusted` — from openai/skills, anthropics/skills -- `community` — any findings = blocked unless `--force` +- `community` — non-dangerous findings can be overridden with `--force`; `dangerous` verdicts remain blocked + +Hermes can now consume third-party skills from multiple external discovery models: +- direct GitHub identifiers (for example `openai/skills/k8s`) +- `skills.sh` identifiers (for example `skills-sh/vercel-labs/json-render/json-render-react`) +- well-known endpoints served from `/.well-known/skills/index.json` + +If you want your skills to be discoverable without a GitHub-specific installer, consider serving them from a well-known endpoint in addition to publishing them in a repo or marketplace. diff --git a/website/docs/getting-started/quickstart.md b/website/docs/getting-started/quickstart.md index 68d41ab34..e743baf6a 100644 --- a/website/docs/getting-started/quickstart.md +++ b/website/docs/getting-started/quickstart.md @@ -141,10 +141,18 @@ The agent will set up a cron job that runs automatically via the gateway. ```bash hermes skills search kubernetes +hermes skills search react --source skills-sh +hermes skills search https://mintlify.com/docs --source well-known hermes skills install openai/skills/k8s hermes skills install official/security/1password +hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force ``` +Tips: +- Use `--source skills-sh` to search the public `skills.sh` directory. +- Use `--source well-known` with a docs/site URL to discover skills from `/.well-known/skills/index.json`. +- Use `--force` only after reviewing a third-party skill. It can override non-dangerous policy blocks, but not a `dangerous` scan verdict. + Or use the `/skills` slash command inside chat. ### Use Hermes inside an editor via ACP diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md index 71a76b071..1d6869743 100644 --- a/website/docs/reference/cli-commands.md +++ b/website/docs/reference/cli-commands.md @@ -246,6 +246,8 @@ Subcommands: | `install` | Install a skill. | | `inspect` | Preview a skill without installing it. | | `list` | List installed skills. | +| `check` | Check installed hub skills for upstream updates. | +| `update` | Reinstall hub skills with upstream changes when available. | | `audit` | Re-scan installed hub skills. | | `uninstall` | Remove a hub-installed skill. | | `publish` | Publish a skill to a registry. | @@ -258,12 +260,23 @@ Common examples: ```bash hermes skills browse hermes skills browse --source official -hermes skills search kubernetes +hermes skills search react --source skills-sh +hermes skills search https://mintlify.com/docs --source well-known 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 check +hermes skills update hermes skills config ``` +Notes: +- `--force` can override non-dangerous policy blocks for third-party/community skills. +- `--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`. + ## `hermes honcho` ```bash diff --git a/website/docs/user-guide/features/skills.md b/website/docs/user-guide/features/skills.md index 349791582..328086649 100644 --- a/website/docs/user-guide/features/skills.md +++ b/website/docs/user-guide/features/skills.md @@ -187,42 +187,98 @@ The `patch` action is preferred for updates — it's more token-efficient than ` ## Skills Hub -Browse, search, install, and manage skills from online registries and official optional skills: +Browse, search, install, and manage skills from online registries, `skills.sh`, direct well-known skill endpoints, and official optional skills. + +### Common commands ```bash -hermes skills browse # Browse all hub skills (official first) -hermes skills browse --source official # Browse only official optional skills -hermes skills search kubernetes # Search all sources -hermes skills install openai/skills/k8s # Install with security scan -hermes skills inspect openai/skills/k8s # Preview before installing -hermes skills list --source hub # List hub-installed skills -hermes skills audit # Re-scan all hub skills -hermes skills uninstall k8s # Remove a hub skill +hermes skills browse # Browse all hub skills (official first) +hermes skills browse --source official # Browse only official optional skills +hermes skills search kubernetes # Search all sources +hermes skills search react --source skills-sh # Search the skills.sh directory +hermes skills search https://mintlify.com/docs --source well-known +hermes skills inspect openai/skills/k8s # Preview before installing +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 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 +hermes skills audit # Re-scan all hub skills for security +hermes skills uninstall k8s # Remove a hub skill hermes skills publish skills/my-skill --to github --repo owner/repo -hermes skills snapshot export setup.json # Export skill config -hermes skills tap add myorg/skills-repo # Add a custom source +hermes skills snapshot export setup.json # Export skill config +hermes skills tap add myorg/skills-repo # Add a custom GitHub source ``` -All hub-installed skills go through a **security scanner** that checks for data exfiltration, prompt injection, destructive commands, and other threats. +### Supported hub sources -Official optional skills use identifiers like `official/security/1password` and `official/migration/openclaw-migration`. +| Source | Example | Notes | +|--------|---------|-------| +| `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. | +| `github` | `openai/skills/k8s` | Direct GitHub repo/path installs and custom taps. | +| `clawhub`, `lobehub`, `claude-marketplace` | Source-specific identifiers | Community or marketplace integrations. | -### Trust Levels +### 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. + +`hermes skills inspect ...` now also surfaces upstream metadata when available: +- repo URL +- skills.sh detail page URL +- install command +- weekly installs +- upstream security audit statuses +- well-known index/endpoint URLs + +Use `--force` when you have reviewed a third-party skill and want to override a non-dangerous policy block: + +```bash +hermes skills install skills-sh/anthropics/skills/pdf --force +``` + +Important behavior: +- `--force` can override policy blocks for caution/warn-style findings. +- `--force` does **not** override a `dangerous` scan verdict. +- Official optional skills (`official/...`) are treated as builtin trust and do not show the third-party warning panel. + +### Trust levels | Level | Source | Policy | |-------|--------|--------| | `builtin` | Ships with Hermes | Always trusted | | `official` | `optional-skills/` in the repo | Builtin trust, no third-party warning | -| `trusted` | openai/skills, anthropics/skills | Trusted sources | -| `community` | Everything else | Any findings = blocked unless `--force` | +| `trusted` | Trusted registries/repos such as `openai/skills`, `anthropics/skills` | More permissive policy than community sources | +| `community` | Everything else (`skills.sh`, well-known endpoints, custom GitHub repos, most marketplaces) | Non-dangerous findings can be overridden with `--force`; `dangerous` verdicts stay blocked | -### Slash Commands (Inside Chat) +### Update lifecycle -All the same commands work with `/skills` prefix: +The hub now tracks enough provenance to re-check upstream copies of installed skills: +```bash +hermes skills check # Report which installed hub skills changed upstream +hermes skills update # Reinstall only the skills with updates available +hermes skills update react # Update one specific installed hub skill ``` + +This uses the stored source identifier plus the current upstream bundle content hash to detect drift. + +### Slash commands (inside chat) + +All the same commands work with `/skills`: + +```text /skills browse -/skills search kubernetes -/skills install openai/skills/skill-creator +/skills search react --source skills-sh +/skills search https://mintlify.com/docs --source well-known +/skills inspect skills-sh/vercel-labs/json-render/json-render-react +/skills install openai/skills/skill-creator --force +/skills check +/skills update /skills list ``` + +Official optional skills still use identifiers like `official/security/1password` and `official/migration/openclaw-migration`.