optional-skills/DESCRIPTION.md

# Optional Skills

Official skills maintained by Nous Research that are **not activated by default**.

These skills ship with the hermes-agent repository but are not copied to
`~/.hermes/skills/` during setup. They are discoverable via the Skills Hub:

```bash
hermes skills browse               # browse all skills, official shown first
hermes skills browse --source official  # browse only official optional skills
hermes skills search <query>       # finds optional skills labeled "official"
hermes skills install <identifier> # copies to ~/.hermes/skills/ and activates
```

## Why optional?

Some skills are useful but not broadly needed by every user:

- **Niche integrations** — specific paid services, specialized tools
- **Experimental features** — promising but not yet proven
- **Heavyweight dependencies** — require significant setup (API keys, installs)

By keeping them optional, we keep the default skill set lean while still
providing curated, tested, official skills for users who want them.
feat: optional skills — official skills shipped but not activated by default Add 'optional-skills/' directory for official skills that ship with the repo but are not copied to ~/.hermes/skills/ during setup. They are: - NOT shown to the model in the system prompt - NOT copied during hermes setup/update - Discoverable via 'hermes skills search' labeled as 'official' - Installable via 'hermes skills install' with builtin trust (no third-party warning) - Auto-categorized on install based on directory structure Implementation: - OptionalSkillSource adapter in tools/skills_hub.py (search/fetch/inspect) - Added to create_source_router() as first source (highest priority) - Trust level 'builtin' for official skills in skills_guard.py - Friendly install message for official skills (no third-party warning) - 'official' label in cyan in search results and skill list First optional skill: Blackbox CLI (autonomous-ai-agents/blackbox) - Multi-model coding agent with built-in judge/Chairman pattern - Delegates to Claude, Codex, Gemini, and Blackbox models - Open-source CLI (GPL-3.0, TypeScript, forked from Gemini CLI) - Requires paid Blackbox AI API key Refs: #475 2026-03-06 01:24:11 -08:00			`# Optional Skills`

			`Official skills maintained by Nous Research that are not activated by default.`

			`These skills ship with the hermes-agent repository but are not copied to`
			`~/.hermes/skills/` during setup. They are discoverable via the Skills Hub:

			```bash
fix: review fixes — path traversal guard, trust_style consistency, edge cases Address code review findings: Security (Medium): - Path traversal guard in OptionalSkillSource.fetch() — resolve() and validate that the path stays within optional-skills/ before reading Bug fixes (Medium): - Add 'builtin' to trust_style dicts in do_inspect() and _resolve_short_name() — official skills now show bright_cyan 'official' label consistently across all display functions (5/5 dicts fixed) Edge cases (Low): - Clamp page_size to [1, 100] in do_browse() to prevent ZeroDivisionError - Update SkillMeta.source docstring to include 'official' - Add browse command to optional-skills/DESCRIPTION.md 2026-03-06 01:40:01 -08:00			`hermes skills browse # browse all skills, official shown first`
			`hermes skills browse --source official # browse only official optional skills`
			`hermes skills search <query> # finds optional skills labeled "official"`
			`hermes skills install <identifier> # copies to ~/.hermes/skills/ and activates`
feat: optional skills — official skills shipped but not activated by default Add 'optional-skills/' directory for official skills that ship with the repo but are not copied to ~/.hermes/skills/ during setup. They are: - NOT shown to the model in the system prompt - NOT copied during hermes setup/update - Discoverable via 'hermes skills search' labeled as 'official' - Installable via 'hermes skills install' with builtin trust (no third-party warning) - Auto-categorized on install based on directory structure Implementation: - OptionalSkillSource adapter in tools/skills_hub.py (search/fetch/inspect) - Added to create_source_router() as first source (highest priority) - Trust level 'builtin' for official skills in skills_guard.py - Friendly install message for official skills (no third-party warning) - 'official' label in cyan in search results and skill list First optional skill: Blackbox CLI (autonomous-ai-agents/blackbox) - Multi-model coding agent with built-in judge/Chairman pattern - Delegates to Claude, Codex, Gemini, and Blackbox models - Open-source CLI (GPL-3.0, TypeScript, forked from Gemini CLI) - Requires paid Blackbox AI API key Refs: #475 2026-03-06 01:24:11 -08:00			```

			`## Why optional?`

			`Some skills are useful but not broadly needed by every user:`

			`- Niche integrations — specific paid services, specialized tools`
			`- Experimental features — promising but not yet proven`
			`- Heavyweight dependencies — require significant setup (API keys, installs)`

			`By keeping them optional, we keep the default skill set lean while still`
			`providing curated, tested, official skills for users who want them.`