docs: update all docs for optional-skills and browse command
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)
This commit is contained in:
teknium1
@@ -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
|
||||
|
||||
---
|
||||
|
||||
@@ -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/
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -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 <query>` | Search skill registries |
|
||||
| `hermes skills install <identifier>` | Install a skill (with security scan) |
|
||||
| `hermes skills inspect <identifier>` | 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 |
|
||||
| `/<skill-name>` | Invoke any installed skill |
|
||||
|
||||
@@ -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 |
|
||||
| `/<skill-name>` | Invoke any installed skill (e.g., `/axolotl`, `/gif-search`) |
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user