docs: guides section overhaul — fix existing + add 3 new tutorials (#5735)
* docs: fix guides section — sidebar ordering, broken links, position conflicts - Add local-llm-on-mac.md to sidebars.ts (was missing after salvage PR) - Reorder sidebar: tips first, then local LLM guide, then tutorials - Fix 10 broken links in team-telegram-assistant.md (missing /docs/ prefix) - Fix relative link in migrate-from-openclaw.md - Fix installation link pointing to learning-path instead of installation - Renumber all sidebar_position values to eliminate conflicts and match the explicit sidebars.ts ordering * docs: add 3 new guides — cron automation, skills, delegation New tutorial-style guides covering core features: - automate-with-cron.md (261 lines): 5 real-world patterns — website monitoring with scripts, weekly reports, GitHub watchers, data collection pipelines, multi-skill workflows. Covers [SILENT] trick, delivery targets, job management. - work-with-skills.md (268 lines): End-to-end skill workflow — finding, installing from Hub, configuring, creating from scratch with reference files, per-platform management, skills vs memory comparison. - delegation-patterns.md (239 lines): 5 patterns — parallel research, code review, alternative comparison, multi-file refactoring, gather-then-analyze (execute_code + delegate). Covers the context problem, toolset selection, constraints. Added all three to sidebars.ts in the Guides & Tutorials section.
This commit is contained in:
Teknium
261
website/docs/guides/automate-with-cron.md
Normal file
261
website/docs/guides/automate-with-cron.md
Normal file
@@ -0,0 +1,261 @@
|
||||
---
|
||||
sidebar_position: 11
|
||||
title: "Automate Anything with Cron"
|
||||
description: "Real-world automation patterns using Hermes cron — monitoring, reports, pipelines, and multi-skill workflows"
|
||||
---
|
||||
|
||||
# Automate Anything with Cron
|
||||
|
||||
The [daily briefing bot tutorial](/docs/guides/daily-briefing-bot) covers the basics. This guide goes further — five real-world automation patterns you can adapt for your own workflows.
|
||||
|
||||
For the full feature reference, see [Scheduled Tasks (Cron)](/docs/user-guide/features/cron).
|
||||
|
||||
:::info Key Concept
|
||||
Cron jobs run in fresh agent sessions with no memory of your current chat. Prompts must be **completely self-contained** — include everything the agent needs to know.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Pattern 1: Website Change Monitor
|
||||
|
||||
Watch a URL for changes and get notified only when something is different.
|
||||
|
||||
The `script` parameter is the secret weapon here. A Python script runs before each execution, and its stdout becomes context for the agent. The script handles the mechanical work (fetching, diffing); the agent handles the reasoning (is this change interesting?).
|
||||
|
||||
Create the monitoring script:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.hermes/scripts
|
||||
```
|
||||
|
||||
```python title="~/.hermes/scripts/watch-site.py"
|
||||
import hashlib, json, os, urllib.request
|
||||
|
||||
URL = "https://example.com/pricing"
|
||||
STATE_FILE = os.path.expanduser("~/.hermes/scripts/.watch-site-state.json")
|
||||
|
||||
# Fetch current content
|
||||
req = urllib.request.Request(URL, headers={"User-Agent": "Hermes-Monitor/1.0"})
|
||||
content = urllib.request.urlopen(req, timeout=30).read().decode()
|
||||
current_hash = hashlib.sha256(content.encode()).hexdigest()
|
||||
|
||||
# Load previous state
|
||||
prev_hash = None
|
||||
if os.path.exists(STATE_FILE):
|
||||
with open(STATE_FILE) as f:
|
||||
prev_hash = json.load(f).get("hash")
|
||||
|
||||
# Save current state
|
||||
with open(STATE_FILE, "w") as f:
|
||||
json.dump({"hash": current_hash, "url": URL}, f)
|
||||
|
||||
# Output for the agent
|
||||
if prev_hash and prev_hash != current_hash:
|
||||
print(f"CHANGE DETECTED on {URL}")
|
||||
print(f"Previous hash: {prev_hash}")
|
||||
print(f"Current hash: {current_hash}")
|
||||
print(f"\nCurrent content (first 2000 chars):\n{content[:2000]}")
|
||||
else:
|
||||
print("NO_CHANGE")
|
||||
```
|
||||
|
||||
Set up the cron job:
|
||||
|
||||
```bash
|
||||
/cron add "every 1h" "If the script output says CHANGE DETECTED, summarize what changed on the page and why it might matter. If it says NO_CHANGE, respond with just [SILENT]." --script ~/.hermes/scripts/watch-site.py --name "Pricing monitor" --deliver telegram
|
||||
```
|
||||
|
||||
:::tip The [SILENT] Trick
|
||||
When the agent's final response contains `[SILENT]`, delivery is suppressed. This means you only get notified when something actually happens — no spam on quiet hours.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Pattern 2: Weekly Report
|
||||
|
||||
Compile information from multiple sources into a formatted summary. This runs once a week and delivers to your home channel.
|
||||
|
||||
```bash
|
||||
/cron add "0 9 * * 1" "Generate a weekly report covering:
|
||||
|
||||
1. Search the web for the top 5 AI news stories from the past week
|
||||
2. Search GitHub for trending repositories in the 'machine-learning' topic
|
||||
3. Check Hacker News for the most discussed AI/ML posts
|
||||
|
||||
Format as a clean summary with sections for each source. Include links.
|
||||
Keep it under 500 words — highlight only what matters." --name "Weekly AI digest" --deliver telegram
|
||||
```
|
||||
|
||||
From the CLI:
|
||||
|
||||
```bash
|
||||
hermes cron create "0 9 * * 1" \
|
||||
"Generate a weekly report covering the top AI news, trending ML GitHub repos, and most-discussed HN posts. Format with sections, include links, keep under 500 words." \
|
||||
--name "Weekly AI digest" \
|
||||
--deliver telegram
|
||||
```
|
||||
|
||||
The `0 9 * * 1` is a standard cron expression: 9:00 AM every Monday.
|
||||
|
||||
---
|
||||
|
||||
## Pattern 3: GitHub Repository Watcher
|
||||
|
||||
Monitor a repository for new issues, PRs, or releases.
|
||||
|
||||
```bash
|
||||
/cron add "every 6h" "Check the GitHub repository NousResearch/hermes-agent for:
|
||||
- New issues opened in the last 6 hours
|
||||
- New PRs opened or merged in the last 6 hours
|
||||
- Any new releases
|
||||
|
||||
Use the terminal to run gh commands:
|
||||
gh issue list --repo NousResearch/hermes-agent --state open --json number,title,author,createdAt --limit 10
|
||||
gh pr list --repo NousResearch/hermes-agent --state all --json number,title,author,createdAt,mergedAt --limit 10
|
||||
|
||||
Filter to only items from the last 6 hours. If nothing new, respond with [SILENT].
|
||||
Otherwise, provide a concise summary of the activity." --name "Repo watcher" --deliver discord
|
||||
```
|
||||
|
||||
:::warning Self-Contained Prompts
|
||||
Notice how the prompt includes the exact `gh` commands. The cron agent has no memory of previous runs or your preferences — spell everything out.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Pattern 4: Data Collection Pipeline
|
||||
|
||||
Scrape data at regular intervals, save to files, and detect trends over time. This pattern combines a script (for collection) with the agent (for analysis).
|
||||
|
||||
```python title="~/.hermes/scripts/collect-prices.py"
|
||||
import json, os, urllib.request
|
||||
from datetime import datetime
|
||||
|
||||
DATA_DIR = os.path.expanduser("~/.hermes/data/prices")
|
||||
os.makedirs(DATA_DIR, exist_ok=True)
|
||||
|
||||
# Fetch current data (example: crypto prices)
|
||||
url = "https://api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum&vs_currencies=usd"
|
||||
data = json.loads(urllib.request.urlopen(url, timeout=30).read())
|
||||
|
||||
# Append to history file
|
||||
entry = {"timestamp": datetime.now().isoformat(), "prices": data}
|
||||
history_file = os.path.join(DATA_DIR, "history.jsonl")
|
||||
with open(history_file, "a") as f:
|
||||
f.write(json.dumps(entry) + "\n")
|
||||
|
||||
# Load recent history for analysis
|
||||
lines = open(history_file).readlines()
|
||||
recent = [json.loads(l) for l in lines[-24:]] # Last 24 data points
|
||||
|
||||
# Output for the agent
|
||||
print(f"Current: BTC=${data['bitcoin']['usd']}, ETH=${data['ethereum']['usd']}")
|
||||
print(f"Data points collected: {len(lines)} total, showing last {len(recent)}")
|
||||
print(f"\nRecent history:")
|
||||
for r in recent[-6:]:
|
||||
print(f" {r['timestamp']}: BTC=${r['prices']['bitcoin']['usd']}, ETH=${r['prices']['ethereum']['usd']}")
|
||||
```
|
||||
|
||||
```bash
|
||||
/cron add "every 1h" "Analyze the price data from the script output. Report:
|
||||
1. Current prices
|
||||
2. Trend direction over the last 6 data points (up/down/flat)
|
||||
3. Any notable movements (>5% change)
|
||||
|
||||
If prices are flat and nothing notable, respond with [SILENT].
|
||||
If there's a significant move, explain what happened." \
|
||||
--script ~/.hermes/scripts/collect-prices.py \
|
||||
--name "Price tracker" \
|
||||
--deliver telegram
|
||||
```
|
||||
|
||||
The script does the mechanical collection; the agent adds the reasoning layer.
|
||||
|
||||
---
|
||||
|
||||
## Pattern 5: Multi-Skill Workflow
|
||||
|
||||
Chain skills together for complex scheduled tasks. Skills are loaded in order before the prompt executes.
|
||||
|
||||
```bash
|
||||
# Use the arxiv skill to find papers, then the obsidian skill to save notes
|
||||
/cron add "0 8 * * *" "Search arXiv for the 3 most interesting papers on 'language model reasoning' from the past day. For each paper, create an Obsidian note with the title, authors, abstract summary, and key contribution." \
|
||||
--skill arxiv \
|
||||
--skill obsidian \
|
||||
--name "Paper digest"
|
||||
```
|
||||
|
||||
From the tool directly:
|
||||
|
||||
```python
|
||||
cronjob(
|
||||
action="create",
|
||||
skills=["arxiv", "obsidian"],
|
||||
prompt="Search arXiv for papers on 'language model reasoning' from the past day. Save the top 3 as Obsidian notes.",
|
||||
schedule="0 8 * * *",
|
||||
name="Paper digest",
|
||||
deliver="local"
|
||||
)
|
||||
```
|
||||
|
||||
Skills are loaded in order — `arxiv` first (teaches the agent how to search papers), then `obsidian` (teaches how to write notes). The prompt ties them together.
|
||||
|
||||
---
|
||||
|
||||
## Managing Your Jobs
|
||||
|
||||
```bash
|
||||
# List all active jobs
|
||||
/cron list
|
||||
|
||||
# Trigger a job immediately (for testing)
|
||||
/cron run <job_id>
|
||||
|
||||
# Pause a job without deleting it
|
||||
/cron pause <job_id>
|
||||
|
||||
# Edit a running job's schedule or prompt
|
||||
/cron edit <job_id> --schedule "every 4h"
|
||||
/cron edit <job_id> --prompt "Updated task description"
|
||||
|
||||
# Add or remove skills from an existing job
|
||||
/cron edit <job_id> --skill arxiv --skill obsidian
|
||||
/cron edit <job_id> --clear-skills
|
||||
|
||||
# Remove a job permanently
|
||||
/cron remove <job_id>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Delivery Targets
|
||||
|
||||
The `--deliver` flag controls where results go:
|
||||
|
||||
| Target | Example | Use case |
|
||||
|--------|---------|----------|
|
||||
| `origin` | `--deliver origin` | Same chat that created the job (default) |
|
||||
| `local` | `--deliver local` | Save to local file only |
|
||||
| `telegram` | `--deliver telegram` | Your Telegram home channel |
|
||||
| `discord` | `--deliver discord` | Your Discord home channel |
|
||||
| `slack` | `--deliver slack` | Your Slack home channel |
|
||||
| Specific chat | `--deliver telegram:-1001234567890` | A specific Telegram group |
|
||||
| Threaded | `--deliver telegram:-1001234567890:17585` | A specific Telegram topic thread |
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
**Make prompts self-contained.** The agent in a cron job has no memory of your conversations. Include URLs, repo names, format preferences, and delivery instructions directly in the prompt.
|
||||
|
||||
**Use `[SILENT]` liberally.** For monitoring jobs, always include instructions like "if nothing changed, respond with `[SILENT]`." This prevents notification noise.
|
||||
|
||||
**Use scripts for data collection.** The `script` parameter lets a Python script handle the boring parts (HTTP requests, file I/O, state tracking). The agent only sees the script's stdout and applies reasoning to it. This is cheaper and more reliable than having the agent do the fetching itself.
|
||||
|
||||
**Test with `/cron run`.** Before waiting for the schedule to trigger, use `/cron run <job_id>` to execute immediately and verify the output looks right.
|
||||
|
||||
**Schedule expressions.** Human-readable formats like `every 2h`, `30m`, and `daily at 9am` all work alongside standard cron expressions like `0 9 * * *`.
|
||||
|
||||
---
|
||||
|
||||
*For the complete cron reference — all parameters, edge cases, and internals — see [Scheduled Tasks (Cron)](/docs/user-guide/features/cron).*
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 8
|
||||
sidebar_position: 9
|
||||
sidebar_label: "Build a Plugin"
|
||||
title: "Build a Hermes Plugin"
|
||||
description: "Step-by-step guide to building a complete Hermes plugin with tools, hooks, data files, and skills"
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
sidebar_position: 3
|
||||
title: "Tutorial: Daily Briefing Bot"
|
||||
description: "Build an automated daily briefing bot that researches topics, summarizes findings, and delivers them to Telegram or Discord every morning"
|
||||
---
|
||||
|
||||
239
website/docs/guides/delegation-patterns.md
Normal file
239
website/docs/guides/delegation-patterns.md
Normal file
@@ -0,0 +1,239 @@
|
||||
---
|
||||
sidebar_position: 13
|
||||
title: "Delegation & Parallel Work"
|
||||
description: "When and how to use subagent delegation — patterns for parallel research, code review, and multi-file work"
|
||||
---
|
||||
|
||||
# Delegation & Parallel Work
|
||||
|
||||
Hermes can spawn isolated child agents to work on tasks in parallel. Each subagent gets its own conversation, terminal session, and toolset. Only the final summary comes back — intermediate tool calls never enter your context window.
|
||||
|
||||
For the full feature reference, see [Subagent Delegation](/docs/user-guide/features/delegation).
|
||||
|
||||
---
|
||||
|
||||
## When to Delegate
|
||||
|
||||
**Good candidates for delegation:**
|
||||
- Reasoning-heavy subtasks (debugging, code review, research synthesis)
|
||||
- Tasks that would flood your context with intermediate data
|
||||
- Parallel independent workstreams (research A and B simultaneously)
|
||||
- Fresh-context tasks where you want the agent to approach without bias
|
||||
|
||||
**Use something else:**
|
||||
- Single tool call → just use the tool directly
|
||||
- Mechanical multi-step work with logic between steps → `execute_code`
|
||||
- Tasks needing user interaction → subagents can't use `clarify`
|
||||
- Quick file edits → do them directly
|
||||
|
||||
---
|
||||
|
||||
## Pattern: Parallel Research
|
||||
|
||||
Research three topics simultaneously and get structured summaries back:
|
||||
|
||||
```
|
||||
Research these three topics in parallel:
|
||||
1. Current state of WebAssembly outside the browser
|
||||
2. RISC-V server chip adoption in 2025
|
||||
3. Practical quantum computing applications
|
||||
|
||||
Focus on recent developments and key players.
|
||||
```
|
||||
|
||||
Behind the scenes, Hermes uses:
|
||||
|
||||
```python
|
||||
delegate_task(tasks=[
|
||||
{
|
||||
"goal": "Research WebAssembly outside the browser in 2025",
|
||||
"context": "Focus on: runtimes (Wasmtime, Wasmer), cloud/edge use cases, WASI progress",
|
||||
"toolsets": ["web"]
|
||||
},
|
||||
{
|
||||
"goal": "Research RISC-V server chip adoption",
|
||||
"context": "Focus on: server chips shipping, cloud providers adopting, software ecosystem",
|
||||
"toolsets": ["web"]
|
||||
},
|
||||
{
|
||||
"goal": "Research practical quantum computing applications",
|
||||
"context": "Focus on: error correction breakthroughs, real-world use cases, key companies",
|
||||
"toolsets": ["web"]
|
||||
}
|
||||
])
|
||||
```
|
||||
|
||||
All three run concurrently. Each subagent searches the web independently and returns a summary. The parent agent then synthesizes them into a coherent briefing.
|
||||
|
||||
---
|
||||
|
||||
## Pattern: Code Review
|
||||
|
||||
Delegate a security review to a fresh-context subagent that approaches the code without preconceptions:
|
||||
|
||||
```
|
||||
Review the authentication module at src/auth/ for security issues.
|
||||
Check for SQL injection, JWT validation problems, password handling,
|
||||
and session management. Fix anything you find and run the tests.
|
||||
```
|
||||
|
||||
The key is the `context` field — it must include everything the subagent needs:
|
||||
|
||||
```python
|
||||
delegate_task(
|
||||
goal="Review src/auth/ for security issues and fix any found",
|
||||
context="""Project at /home/user/webapp. Python 3.11, Flask, PyJWT, bcrypt.
|
||||
Auth files: src/auth/login.py, src/auth/jwt.py, src/auth/middleware.py
|
||||
Test command: pytest tests/auth/ -v
|
||||
Focus on: SQL injection, JWT validation, password hashing, session management.
|
||||
Fix issues found and verify tests pass.""",
|
||||
toolsets=["terminal", "file"]
|
||||
)
|
||||
```
|
||||
|
||||
:::warning The Context Problem
|
||||
Subagents know **absolutely nothing** about your conversation. They start completely fresh. If you delegate "fix the bug we were discussing," the subagent has no idea what bug you mean. Always pass file paths, error messages, project structure, and constraints explicitly.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Pattern: Compare Alternatives
|
||||
|
||||
Evaluate multiple approaches to the same problem in parallel, then pick the best:
|
||||
|
||||
```
|
||||
I need to add full-text search to our Django app. Evaluate three approaches
|
||||
in parallel:
|
||||
1. PostgreSQL tsvector (built-in)
|
||||
2. Elasticsearch via django-elasticsearch-dsl
|
||||
3. Meilisearch via meilisearch-python
|
||||
|
||||
For each: setup complexity, query capabilities, resource requirements,
|
||||
and maintenance overhead. Compare them and recommend one.
|
||||
```
|
||||
|
||||
Each subagent researches one option independently. Because they're isolated, there's no cross-contamination — each evaluation stands on its own merits. The parent agent gets all three summaries and makes the comparison.
|
||||
|
||||
---
|
||||
|
||||
## Pattern: Multi-File Refactoring
|
||||
|
||||
Split a large refactoring task across parallel subagents, each handling a different part of the codebase:
|
||||
|
||||
```python
|
||||
delegate_task(tasks=[
|
||||
{
|
||||
"goal": "Refactor all API endpoint handlers to use the new response format",
|
||||
"context": """Project at /home/user/api-server.
|
||||
Files: src/handlers/users.py, src/handlers/auth.py, src/handlers/billing.py
|
||||
Old format: return {"data": result, "status": "ok"}
|
||||
New format: return APIResponse(data=result, status=200).to_dict()
|
||||
Import: from src.responses import APIResponse
|
||||
Run tests after: pytest tests/handlers/ -v""",
|
||||
"toolsets": ["terminal", "file"]
|
||||
},
|
||||
{
|
||||
"goal": "Update all client SDK methods to handle the new response format",
|
||||
"context": """Project at /home/user/api-server.
|
||||
Files: sdk/python/client.py, sdk/python/models.py
|
||||
Old parsing: result = response.json()["data"]
|
||||
New parsing: result = response.json()["data"] (same key, but add status code checking)
|
||||
Also update sdk/python/tests/test_client.py""",
|
||||
"toolsets": ["terminal", "file"]
|
||||
},
|
||||
{
|
||||
"goal": "Update API documentation to reflect the new response format",
|
||||
"context": """Project at /home/user/api-server.
|
||||
Docs at: docs/api/. Format: Markdown with code examples.
|
||||
Update all response examples from old format to new format.
|
||||
Add a 'Response Format' section to docs/api/overview.md explaining the schema.""",
|
||||
"toolsets": ["terminal", "file"]
|
||||
}
|
||||
])
|
||||
```
|
||||
|
||||
:::tip
|
||||
Each subagent gets its own terminal session. They can work on the same project directory without stepping on each other — as long as they're editing different files. If two subagents might touch the same file, handle that file yourself after the parallel work completes.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Pattern: Gather Then Analyze
|
||||
|
||||
Use `execute_code` for mechanical data gathering, then delegate the reasoning-heavy analysis:
|
||||
|
||||
```python
|
||||
# Step 1: Mechanical gathering (execute_code is better here — no reasoning needed)
|
||||
execute_code("""
|
||||
from hermes_tools import web_search, web_extract
|
||||
|
||||
results = []
|
||||
for query in ["AI funding Q1 2026", "AI startup acquisitions 2026", "AI IPOs 2026"]:
|
||||
r = web_search(query, limit=5)
|
||||
for item in r["data"]["web"]:
|
||||
results.append({"title": item["title"], "url": item["url"], "desc": item["description"]})
|
||||
|
||||
# Extract full content from top 5 most relevant
|
||||
urls = [r["url"] for r in results[:5]]
|
||||
content = web_extract(urls)
|
||||
|
||||
# Save for the analysis step
|
||||
import json
|
||||
with open("/tmp/ai-funding-data.json", "w") as f:
|
||||
json.dump({"search_results": results, "extracted": content["results"]}, f)
|
||||
print(f"Collected {len(results)} results, extracted {len(content['results'])} pages")
|
||||
""")
|
||||
|
||||
# Step 2: Reasoning-heavy analysis (delegation is better here)
|
||||
delegate_task(
|
||||
goal="Analyze AI funding data and write a market report",
|
||||
context="""Raw data at /tmp/ai-funding-data.json contains search results and
|
||||
extracted web pages about AI funding, acquisitions, and IPOs in Q1 2026.
|
||||
Write a structured market report: key deals, trends, notable players,
|
||||
and outlook. Focus on deals over $100M.""",
|
||||
toolsets=["terminal", "file"]
|
||||
)
|
||||
```
|
||||
|
||||
This is often the most efficient pattern: `execute_code` handles the 10+ sequential tool calls cheaply, then a subagent does the single expensive reasoning task with a clean context.
|
||||
|
||||
---
|
||||
|
||||
## Toolset Selection
|
||||
|
||||
Choose toolsets based on what the subagent needs:
|
||||
|
||||
| Task type | Toolsets | Why |
|
||||
|-----------|----------|-----|
|
||||
| Web research | `["web"]` | web_search + web_extract only |
|
||||
| Code work | `["terminal", "file"]` | Shell access + file operations |
|
||||
| Full-stack | `["terminal", "file", "web"]` | Everything except messaging |
|
||||
| Read-only analysis | `["file"]` | Can only read files, no shell |
|
||||
|
||||
Restricting toolsets keeps the subagent focused and prevents accidental side effects (like a research subagent running shell commands).
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- **Max 3 parallel tasks** — batches are capped at 3 concurrent subagents
|
||||
- **No nesting** — subagents cannot call `delegate_task`, `clarify`, `memory`, `send_message`, or `execute_code`
|
||||
- **Separate terminals** — each subagent gets its own terminal session with separate working directory and state
|
||||
- **No conversation history** — subagents see only what you put in `goal` and `context`
|
||||
- **Default 50 iterations** — set `max_iterations` lower for simple tasks to save cost
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
**Be specific in goals.** "Fix the bug" is too vague. "Fix the TypeError in api/handlers.py line 47 where process_request() receives None from parse_body()" gives the subagent enough to work with.
|
||||
|
||||
**Include file paths.** Subagents don't know your project structure. Always include absolute paths to relevant files, the project root, and the test command.
|
||||
|
||||
**Use delegation for context isolation.** Sometimes you want a fresh perspective. Delegating forces you to articulate the problem clearly, and the subagent approaches it without the assumptions that built up in your conversation.
|
||||
|
||||
**Check results.** Subagent summaries are just that — summaries. If a subagent says "fixed the bug and tests pass," verify by running the tests yourself or reading the diff.
|
||||
|
||||
---
|
||||
|
||||
*For the complete delegation reference — all parameters, ACP integration, and advanced configuration — see [Subagent Delegation](/docs/user-guide/features/delegation).*
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 8
|
||||
sidebar_position: 2
|
||||
title: "Run Local LLMs on Mac"
|
||||
description: "Set up a local OpenAI-compatible LLM server on macOS with llama.cpp or MLX, including model selection, memory optimization, and real benchmarks on Apple Silicon"
|
||||
---
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 7
|
||||
sidebar_position: 10
|
||||
title: "Migrate from OpenClaw"
|
||||
description: "Complete guide to migrating your OpenClaw / Clawdbot setup to Hermes Agent — what gets migrated, how config maps, and what to check after."
|
||||
---
|
||||
@@ -166,7 +166,7 @@ These are saved to `~/.hermes/migration/openclaw/<timestamp>/archive/` for manua
|
||||
| `HEARTBEAT.md` | `archive/workspace/HEARTBEAT.md` | Use cron jobs for periodic tasks |
|
||||
| `BOOTSTRAP.md` | `archive/workspace/BOOTSTRAP.md` | Use context files or skills |
|
||||
| Cron jobs | `archive/cron-config.json` | Recreate with `hermes cron create` |
|
||||
| Plugins | `archive/plugins-config.json` | See [plugins guide](../user-guide/features/hooks.md) |
|
||||
| Plugins | `archive/plugins-config.json` | See [plugins guide](/docs/user-guide/features/hooks) |
|
||||
| Hooks/webhooks | `archive/hooks-config.json` | Use `hermes webhook` or gateway hooks |
|
||||
| Memory backend | `archive/memory-backend-config.json` | Configure via `hermes honcho` |
|
||||
| Skills registry | `archive/skills-registry-config.json` | Use `hermes skills config` |
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
sidebar_position: 5
|
||||
title: "Using Hermes as a Python Library"
|
||||
description: "Embed AIAgent in your own Python scripts, web apps, or automation pipelines — no CLI required"
|
||||
---
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
sidebar_position: 4
|
||||
title: "Tutorial: Team Telegram Assistant"
|
||||
description: "Step-by-step guide to setting up a Telegram bot that your whole team can use for code help, research, system admin, and more"
|
||||
---
|
||||
@@ -24,7 +24,7 @@ A Telegram bot that:
|
||||
|
||||
Before starting, make sure you have:
|
||||
|
||||
- **Hermes Agent installed** on a server or VPS (not your laptop — the bot needs to stay running). Follow the [installation guide](/getting-started/learning-path) if you haven't yet.
|
||||
- **Hermes Agent installed** on a server or VPS (not your laptop — the bot needs to stay running). Follow the [installation guide](/docs/getting-started/installation) if you haven't yet.
|
||||
- **A Telegram account** for yourself (the bot owner)
|
||||
- **An LLM provider configured** — at minimum, an API key for OpenAI, Anthropic, or another supported provider in `~/.hermes/.env`
|
||||
|
||||
@@ -428,13 +428,13 @@ hermes gateway stop && hermes gateway start
|
||||
|
||||
You've got a working team Telegram assistant. Here are some next steps:
|
||||
|
||||
- **[Security Guide](/user-guide/security)** — deep dive into authorization, container isolation, and command approval
|
||||
- **[Messaging Gateway](/user-guide/messaging)** — full reference for gateway architecture, session management, and chat commands
|
||||
- **[Telegram Setup](/user-guide/messaging/telegram)** — platform-specific details including voice messages and TTS
|
||||
- **[Scheduled Tasks](/user-guide/features/cron)** — advanced cron scheduling with delivery options and cron expressions
|
||||
- **[Context Files](/user-guide/features/context-files)** — AGENTS.md, SOUL.md, and .cursorrules for project knowledge
|
||||
- **[Personality](/user-guide/features/personality)** — built-in personality presets and custom persona definitions
|
||||
- **Add more platforms** — the same gateway can simultaneously run [Discord](/user-guide/messaging/discord), [Slack](/user-guide/messaging/slack), and [WhatsApp](/user-guide/messaging/whatsapp)
|
||||
- **[Security Guide](/docs/user-guide/security)** — deep dive into authorization, container isolation, and command approval
|
||||
- **[Messaging Gateway](/docs/user-guide/messaging)** — full reference for gateway architecture, session management, and chat commands
|
||||
- **[Telegram Setup](/docs/user-guide/messaging/telegram)** — platform-specific details including voice messages and TTS
|
||||
- **[Scheduled Tasks](/docs/user-guide/features/cron)** — advanced cron scheduling with delivery options and cron expressions
|
||||
- **[Context Files](/docs/user-guide/features/context-files)** — AGENTS.md, SOUL.md, and .cursorrules for project knowledge
|
||||
- **[Personality](/docs/user-guide/features/personality)** — built-in personality presets and custom persona definitions
|
||||
- **Add more platforms** — the same gateway can simultaneously run [Discord](/docs/user-guide/messaging/discord), [Slack](/docs/user-guide/messaging/slack), and [WhatsApp](/docs/user-guide/messaging/whatsapp)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
sidebar_position: 6
|
||||
title: "Use MCP with Hermes"
|
||||
description: "A practical guide to connecting MCP servers to Hermes Agent, filtering their tools, and using them safely in real workflows"
|
||||
---
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 6
|
||||
sidebar_position: 7
|
||||
title: "Use SOUL.md with Hermes"
|
||||
description: "How to use SOUL.md to shape Hermes Agent's default voice, what belongs there, and how it differs from AGENTS.md and /personality"
|
||||
---
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 7
|
||||
sidebar_position: 8
|
||||
title: "Use Voice Mode with Hermes"
|
||||
description: "A practical guide to setting up and using Hermes voice mode across CLI, Telegram, Discord, and Discord voice channels"
|
||||
---
|
||||
|
||||
268
website/docs/guides/work-with-skills.md
Normal file
268
website/docs/guides/work-with-skills.md
Normal file
@@ -0,0 +1,268 @@
|
||||
---
|
||||
sidebar_position: 12
|
||||
title: "Working with Skills"
|
||||
description: "Find, install, use, and create skills — on-demand knowledge that teaches Hermes new workflows"
|
||||
---
|
||||
|
||||
# Working with Skills
|
||||
|
||||
Skills are on-demand knowledge documents that teach Hermes how to handle specific tasks — from generating ASCII art to managing GitHub PRs. This guide walks you through using them day to day.
|
||||
|
||||
For the full technical reference, see [Skills System](/docs/user-guide/features/skills).
|
||||
|
||||
---
|
||||
|
||||
## Finding Skills
|
||||
|
||||
Every Hermes installation ships with bundled skills. See what's available:
|
||||
|
||||
```bash
|
||||
# In any chat session:
|
||||
/skills
|
||||
|
||||
# Or from the CLI:
|
||||
hermes skills list
|
||||
```
|
||||
|
||||
This shows a compact list with names and descriptions:
|
||||
|
||||
```
|
||||
ascii-art Generate ASCII art using pyfiglet, cowsay, boxes...
|
||||
arxiv Search and retrieve academic papers from arXiv...
|
||||
github-pr-workflow Full PR lifecycle — create branches, commit...
|
||||
plan Plan mode — inspect context, write a markdown...
|
||||
excalidraw Create hand-drawn style diagrams using Excalidraw...
|
||||
```
|
||||
|
||||
### Searching for a Skill
|
||||
|
||||
```bash
|
||||
# Search by keyword
|
||||
/skills search docker
|
||||
/skills search music
|
||||
```
|
||||
|
||||
### The Skills Hub
|
||||
|
||||
Official optional skills (heavier or niche skills not active by default) are available via the Hub:
|
||||
|
||||
```bash
|
||||
# Browse official optional skills
|
||||
/skills browse
|
||||
|
||||
# Search the hub
|
||||
/skills search blockchain
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Using a Skill
|
||||
|
||||
Every installed skill is automatically a slash command. Just type its name:
|
||||
|
||||
```bash
|
||||
# Load a skill and give it a task
|
||||
/ascii-art Make a banner that says "HELLO WORLD"
|
||||
/plan Design a REST API for a todo app
|
||||
/github-pr-workflow Create a PR for the auth refactor
|
||||
|
||||
# Just the skill name (no task) loads it and lets you describe what you need
|
||||
/excalidraw
|
||||
```
|
||||
|
||||
You can also trigger skills through natural conversation — ask Hermes to use a specific skill, and it will load it via the `skill_view` tool.
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
Skills use a token-efficient loading pattern. The agent doesn't load everything at once:
|
||||
|
||||
1. **`skills_list()`** — compact list of all skills (~3k tokens). Loaded at session start.
|
||||
2. **`skill_view(name)`** — full SKILL.md content for one skill. Loaded when the agent decides it needs that skill.
|
||||
3. **`skill_view(name, file_path)`** — a specific reference file within the skill. Only loaded if needed.
|
||||
|
||||
This means skills don't cost tokens until they're actually used.
|
||||
|
||||
---
|
||||
|
||||
## Installing from the Hub
|
||||
|
||||
Official optional skills ship with Hermes but aren't active by default. Install them explicitly:
|
||||
|
||||
```bash
|
||||
# Install an official optional skill
|
||||
hermes skills install official/research/arxiv
|
||||
|
||||
# Install from the hub in a chat session
|
||||
/skills install official/creative/songwriting-and-ai-music
|
||||
```
|
||||
|
||||
What happens:
|
||||
1. The skill directory is copied to `~/.hermes/skills/`
|
||||
2. It appears in your `skills_list` output
|
||||
3. It becomes available as a slash command
|
||||
|
||||
:::tip
|
||||
Installed skills take effect in new sessions. If you want it available in the current session, use `/reset` to start fresh, or add `--now` to invalidate the prompt cache immediately (costs more tokens on the next turn).
|
||||
:::
|
||||
|
||||
### Verifying Installation
|
||||
|
||||
```bash
|
||||
# Check it's there
|
||||
hermes skills list | grep arxiv
|
||||
|
||||
# Or in chat
|
||||
/skills search arxiv
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuring Skill Settings
|
||||
|
||||
Some skills declare configuration they need in their frontmatter:
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
hermes:
|
||||
config:
|
||||
- key: tenor.api_key
|
||||
description: "Tenor API key for GIF search"
|
||||
prompt: "Enter your Tenor API key"
|
||||
url: "https://developers.google.com/tenor/guides/quickstart"
|
||||
```
|
||||
|
||||
When a skill with config is first loaded, Hermes prompts you for the values. They're stored in `config.yaml` under `skills.config.*`.
|
||||
|
||||
Manage skill config from the CLI:
|
||||
|
||||
```bash
|
||||
# Interactive config for a specific skill
|
||||
hermes skills config gif-search
|
||||
|
||||
# View all skill config
|
||||
hermes config get skills.config
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Creating Your Own Skill
|
||||
|
||||
Skills are just markdown files with YAML frontmatter. Creating one takes under five minutes.
|
||||
|
||||
### 1. Create the Directory
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.hermes/skills/my-category/my-skill
|
||||
```
|
||||
|
||||
### 2. Write SKILL.md
|
||||
|
||||
```markdown title="~/.hermes/skills/my-category/my-skill/SKILL.md"
|
||||
---
|
||||
name: my-skill
|
||||
description: Brief description of what this skill does
|
||||
version: 1.0.0
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [my-tag, automation]
|
||||
category: my-category
|
||||
---
|
||||
|
||||
# My Skill
|
||||
|
||||
## When to Use
|
||||
Use this skill when the user asks about [specific topic] or needs to [specific task].
|
||||
|
||||
## Procedure
|
||||
1. First, check if [prerequisite] is available
|
||||
2. Run `command --with-flags`
|
||||
3. Parse the output and present results
|
||||
|
||||
## Pitfalls
|
||||
- Common failure: [description]. Fix: [solution]
|
||||
- Watch out for [edge case]
|
||||
|
||||
## Verification
|
||||
Run `check-command` to confirm the result is correct.
|
||||
```
|
||||
|
||||
### 3. Add Reference Files (Optional)
|
||||
|
||||
Skills can include supporting files the agent loads on demand:
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Main skill document
|
||||
├── references/
|
||||
│ ├── api-docs.md # API reference the agent can consult
|
||||
│ └── examples.md # Example inputs/outputs
|
||||
├── templates/
|
||||
│ └── config.yaml # Template files the agent can use
|
||||
└── scripts/
|
||||
└── setup.sh # Scripts the agent can execute
|
||||
```
|
||||
|
||||
Reference these in your SKILL.md:
|
||||
|
||||
```markdown
|
||||
For API details, load the reference: `skill_view("my-skill", "references/api-docs.md")`
|
||||
```
|
||||
|
||||
### 4. Test It
|
||||
|
||||
Start a new session and try your skill:
|
||||
|
||||
```bash
|
||||
hermes chat -q "/my-skill help me with the thing"
|
||||
```
|
||||
|
||||
The skill appears automatically — no registration needed. Drop it in `~/.hermes/skills/` and it's live.
|
||||
|
||||
:::info
|
||||
The agent can also create and update skills itself using `skill_manage`. After solving a complex problem, Hermes may offer to save the approach as a skill for next time.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Per-Platform Skill Management
|
||||
|
||||
Control which skills are available on which platforms:
|
||||
|
||||
```bash
|
||||
hermes skills
|
||||
```
|
||||
|
||||
This opens an interactive TUI where you can enable or disable skills per platform (CLI, Telegram, Discord, etc.). Useful when you want certain skills only available in specific contexts — for example, keeping development skills off Telegram.
|
||||
|
||||
---
|
||||
|
||||
## Skills vs Memory
|
||||
|
||||
Both are persistent across sessions, but they serve different purposes:
|
||||
|
||||
| | Skills | Memory |
|
||||
|---|---|---|
|
||||
| **What** | Procedural knowledge — how to do things | Factual knowledge — what things are |
|
||||
| **When** | Loaded on demand, only when relevant | Injected into every session automatically |
|
||||
| **Size** | Can be large (hundreds of lines) | Should be compact (key facts only) |
|
||||
| **Cost** | Zero tokens until loaded | Small but constant token cost |
|
||||
| **Examples** | "How to deploy to Kubernetes" | "User prefers dark mode, lives in PST" |
|
||||
| **Who creates** | You, the agent, or installed from Hub | The agent, based on conversations |
|
||||
|
||||
**Rule of thumb:** If you'd put it in a reference document, it's a skill. If you'd put it on a sticky note, it's memory.
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
**Keep skills focused.** A skill that tries to cover "all of DevOps" will be too long and too vague. A skill that covers "deploy a Python app to Fly.io" is specific enough to be genuinely useful.
|
||||
|
||||
**Let the agent create skills.** After a complex multi-step task, Hermes will often offer to save the approach as a skill. Say yes — these agent-authored skills capture the exact workflow including pitfalls that were discovered along the way.
|
||||
|
||||
**Use categories.** Organize skills into subdirectories (`~/.hermes/skills/devops/`, `~/.hermes/skills/research/`, etc.). This keeps the list manageable and helps the agent find relevant skills faster.
|
||||
|
||||
**Update skills when they go stale.** If you use a skill and hit issues not covered by it, tell Hermes to update the skill with what you learned. Skills that aren't maintained become liabilities.
|
||||
|
||||
---
|
||||
|
||||
*For the complete skills reference — frontmatter fields, conditional activation, external directories, and more — see [Skills System](/docs/user-guide/features/skills).*
|
||||
@@ -132,13 +132,17 @@ const sidebars: SidebarsConfig = {
|
||||
collapsed: true,
|
||||
items: [
|
||||
'guides/tips',
|
||||
'guides/build-a-hermes-plugin',
|
||||
'guides/local-llm-on-mac',
|
||||
'guides/daily-briefing-bot',
|
||||
'guides/team-telegram-assistant',
|
||||
'guides/python-library',
|
||||
'guides/use-mcp-with-hermes',
|
||||
'guides/use-soul-with-hermes',
|
||||
'guides/use-voice-mode-with-hermes',
|
||||
'guides/build-a-hermes-plugin',
|
||||
'guides/automate-with-cron',
|
||||
'guides/work-with-skills',
|
||||
'guides/delegation-patterns',
|
||||
'guides/migrate-from-openclaw',
|
||||
],
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user