From 5ce2c47d603a05bc5590ed35b946dc9b8e768870 Mon Sep 17 00:00:00 2001 From: teknium1 Date: Fri, 6 Mar 2026 01:46:34 -0800 Subject: [PATCH] docs: update all docs for optional-skills and browse command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update 7 documentation files to reflect: - optional-skills/ directory in all project structure trees - 'hermes skills browse' in all CLI command listings - '/skills browse' in all slash command references - Three-tier skill placement (bundled → optional → hub) - 'official' trust level in trust level tables - Updated /skills description from 'Search, install...' to 'Browse, search...' Files updated: - CONTRIBUTING.md (skill classification, project tree, section title) - AGENTS.md (project tree, Skills Hub description, source adapters list) - website/docs/reference/cli-commands.md (CLI table, slash command table) - website/docs/developer-guide/creating-skills.md (structure, classification, trust) - website/docs/user-guide/features/skills.md (hub commands, trust table, slash commands) - website/docs/user-guide/cli.md (slash command description) - website/docs/developer-guide/architecture.md (project tree) --- AGENTS.md | 5 +++-- CONTRIBUTING.md | 9 ++++++--- website/docs/developer-guide/architecture.md | 1 + website/docs/developer-guide/creating-skills.md | 9 ++++++--- website/docs/reference/cli-commands.md | 3 ++- website/docs/user-guide/cli.md | 2 +- website/docs/user-guide/features/skills.md | 6 +++++- 7 files changed, 24 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 49387900..3cde8bb4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,6 +55,7 @@ hermes-agent/ ├── cron/ # Scheduler implementation ├── environments/ # RL training environments (Atropos integration) ├── skills/ # Bundled skill sources +├── optional-skills/ # Official optional skills (not activated by default) ├── cli.py # Interactive CLI orchestrator (HermesCLI class) ├── run_agent.py # AIAgent class (core conversation loop) ├── model_tools.py # Tool orchestration (thin layer over tools/registry.py) @@ -661,12 +662,12 @@ metadata: # Skill Content... ``` -**Skills Hub** — user-driven skill search/install from online registries (GitHub, ClawHub, Claude marketplaces, LobeHub). Not exposed as an agent tool — the model cannot search for or install skills. Users manage skills via `hermes skills ...` CLI commands or the `/skills` slash command in chat. +**Skills Hub** — user-driven skill search/install from online registries and official optional skills. Sources: official optional skills (shipped with repo, labeled "official"), GitHub (openai/skills, anthropics/skills, custom taps), ClawHub, Claude marketplace, LobeHub. Not exposed as an agent tool — the model cannot search for or install skills. Users manage skills via `hermes skills browse/search/install` CLI commands or the `/skills` slash command in chat. Key files: - `tools/skills_tool.py` — Agent-facing skill list/view (progressive disclosure) - `tools/skills_guard.py` — Security scanner (regex + LLM audit, trust-aware install policy) -- `tools/skills_hub.py` — Source adapters (GitHub, ClawHub, Claude marketplace, LobeHub), lock file, auth +- `tools/skills_hub.py` — Source adapters (OptionalSkillSource, GitHub, ClawHub, Claude marketplace, LobeHub), lock file, auth - `hermes_cli/skills_hub.py` — CLI subcommands + `/skills` slash command handler --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0a3e0354..433f10d1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,7 +43,9 @@ Bundled skills (in `skills/`) ship with every Hermes install. They should be **b - Document handling, web research, common dev workflows, system administration - Used regularly by a wide range of people -If your skill is specialized (a niche engineering tool, a specific SaaS integration, a game), it's better suited for a **Skills Hub** — upload it to a skills registry and share it in the [Nous Research Discord](https://discord.gg/NousResearch). Users can install it with `hermes skills install`. +If your skill is official and useful but not universally needed (e.g., a paid service integration, a heavyweight dependency), put it in **`optional-skills/`** — it ships with the repo but isn't activated by default. Users can discover it via `hermes skills browse` (labeled "official") and install it with `hermes skills install` (no third-party warning, builtin trust). + +If your skill is specialized, community-contributed, or niche, it's better suited for a **Skills Hub** — upload it to a skills registry and share it in the [Nous Research Discord](https://discord.gg/NousResearch). Users can install it with `hermes skills install`. --- @@ -168,6 +170,7 @@ hermes-agent/ │ └── whatsapp-bridge/ # Node.js WhatsApp bridge (Baileys) │ ├── skills/ # Bundled skills (copied to ~/.hermes/skills/ on install) +├── optional-skills/ # Official optional skills (discoverable via hub, not activated by default) ├── environments/ # RL training environments (Atropos integration) ├── tests/ # Test suite ├── website/ # Documentation site (hermes-agent.nousresearch.com) @@ -294,9 +297,9 @@ If it's a new toolset, add it to `toolsets.py` and to the relevant platform pres --- -## Adding a Bundled Skill +## Adding a Skill -Bundled skills live in `skills/` organized by category: +Bundled skills live in `skills/` organized by category. Official optional skills use the same structure in `optional-skills/`: ``` skills/ diff --git a/website/docs/developer-guide/architecture.md b/website/docs/developer-guide/architecture.md index 89d255bc..b8ae1fc1 100644 --- a/website/docs/developer-guide/architecture.md +++ b/website/docs/developer-guide/architecture.md @@ -70,6 +70,7 @@ hermes-agent/ │ └── whatsapp-bridge/ # Node.js WhatsApp bridge (Baileys) │ ├── skills/ # Bundled skills (copied to ~/.hermes/skills/) +├── optional-skills/ # Official optional skills (discoverable via hub, not activated by default) ├── environments/ # RL training environments (Atropos integration) └── tests/ # Test suite ``` diff --git a/website/docs/developer-guide/creating-skills.md b/website/docs/developer-guide/creating-skills.md index f2f3550c..f6012403 100644 --- a/website/docs/developer-guide/creating-skills.md +++ b/website/docs/developer-guide/creating-skills.md @@ -24,7 +24,7 @@ Make it a **Tool** when: ## Skill Directory Structure -Bundled skills live in `skills/` organized by category: +Bundled skills live in `skills/` organized by category. Official optional skills use the same structure in `optional-skills/`: ``` skills/ @@ -98,14 +98,16 @@ Run the skill and verify the agent follows the instructions correctly: hermes chat --toolsets skills -q "Use the X skill to do Y" ``` -## Should the Skill Be Bundled? +## Where Should the Skill Live? Bundled skills (in `skills/`) ship with every Hermes install. They should be **broadly useful to most users**: - Document handling, web research, common dev workflows, system administration - Used regularly by a wide range of people -If your skill is specialized (a niche engineering tool, a specific SaaS integration, a game), it's better suited for a **Skills Hub** — upload it to a registry and share it via `hermes skills install`. +If your skill is official and useful but not universally needed (e.g., a paid service integration, a heavyweight dependency), put it in **`optional-skills/`** — it ships with the repo, is discoverable via `hermes skills browse` (labeled "official"), and installs with builtin trust. + +If your skill is specialized, community-contributed, or niche, it's better suited for a **Skills Hub** — upload it to a registry and share it via `hermes skills install`. ## Publishing Skills @@ -136,5 +138,6 @@ All hub-installed skills go through a security scanner that checks for: 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` diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md index ad21d80c..728b8141 100644 --- a/website/docs/reference/cli-commands.md +++ b/website/docs/reference/cli-commands.md @@ -71,6 +71,7 @@ These are commands you run from your shell. | Command | Description | |---------|-------------| +| `hermes skills browse` | Browse all available skills with pagination (official first) | | `hermes skills search ` | Search skill registries | | `hermes skills install ` | Install a skill (with security scan) | | `hermes skills inspect ` | Preview before installing | @@ -156,7 +157,7 @@ Type `/` in the interactive CLI to see an autocomplete dropdown. | Command | Description | |---------|-------------| | `/cron` | Manage scheduled tasks | -| `/skills` | Search, install, inspect, or manage skills | +| `/skills` | Browse, search, install, inspect, or manage skills | | `/platforms` | Show gateway/messaging platform status | | `/verbose` | Cycle tool progress: off → new → all → verbose | | `/` | Invoke any installed skill | diff --git a/website/docs/user-guide/cli.md b/website/docs/user-guide/cli.md index a0944aca..e31463e2 100644 --- a/website/docs/user-guide/cli.md +++ b/website/docs/user-guide/cli.md @@ -112,7 +112,7 @@ Type `/` to see an autocomplete dropdown of all available commands. | Command | Description | |---------|-------------| | `/cron` | Manage scheduled tasks | -| `/skills` | Search, install, inspect, or manage skills | +| `/skills` | Browse, search, install, inspect, or manage skills | | `/platforms` | Show gateway/messaging platform status | | `/verbose` | Cycle tool progress display: off → new → all → verbose | | `/` | Invoke any installed skill (e.g., `/axolotl`, `/gif-search`) | diff --git a/website/docs/user-guide/features/skills.md b/website/docs/user-guide/features/skills.md index 9a3063fc..053f2171 100644 --- a/website/docs/user-guide/features/skills.md +++ b/website/docs/user-guide/features/skills.md @@ -123,9 +123,11 @@ The `patch` action is preferred for updates — it's more token-efficient than ` ## Skills Hub -Search, install, and manage skills from online registries: +Browse, search, install, and manage skills from online registries and official optional skills: ```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 @@ -144,6 +146,7 @@ All hub-installed skills go through a **security scanner** that checks for data | 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` | @@ -152,6 +155,7 @@ All hub-installed skills go through a **security scanner** that checks for data All the same commands work with `/skills` prefix: ``` +/skills browse /skills search kubernetes /skills install openai/skills/skill-creator /skills list