Hermes Skills Upgrade

hermes skills CLI — the built-in subcommand for browsing, searching, and installing hub skills (hermes skills browse/search/install/check/update)

Key Files & Paths

| Path | Purpose | |------|---------| | ~/.hermes/skills/ | Installed skill directories (gateway scans depth 2) | | ~/.hermes/skill-repos/ | Cloned git repos for persistence + future pulls | | /usr/local/lib/hermes-agent/optional-skills/ | Hub-installed skills (via hermes skills install) | | /tmp/awesome-hermes-agent/ | Ephemeral clone of curated list (refreshed each run) | | /tmp/new-skill-checks/ | Temp dir for cloning candidate repos before installing | | scripts/gateway-smoke-test.sh | Hermes gateway health verification (8 checks) | | scripts/openclaw-smoke-test.sh | OpenClaw deployment health verification (6 checks) | | scripts/skill-verify.sh | Validate SKILL.md meets quality standards (6 checks) | | references/llm-council-scoring.md | Full LLM council evaluation workflow, rubric, provider pitfalls, and historical results |

Upgrade Workflow (7 Steps)

Step 1: Audit Current State

# Count discoverable vs total
find ~/.hermes/skills -maxdepth 2 -name "SKILL.md" -type f | wc -l  # discoverable
find ~/.hermes/skills -name "SKILL.md" -type f | wc -l              # total
Check for broken files
find ~/.hermes/skills -maxdepth 2 -name "SKILL.md" -type f | while read f; do
  head -5 "$f" | grep -q "^name:" || echo "BROKEN: $f"
done
Check broken symlinks
find ~/.hermes/skills -type l ! -exec test -e {} \; -print
Token impact
find ~/.hermes/skills -maxdepth 2 -name "SKILL.md" -type f -exec grep "^description:" {} \; | wc -c
Divide by 4 for estimated tokens

Step 2: Pull All Tracked Repos

cd ~/.hermes/skills
for dir in */; do
  [ -d "$dir/.git" ] && (cd "$dir" && git pull --ff-only 2>&1 | tail -1)
done
Also update skill-repos
cd ~/.hermes/skill-repos
for dir in */; do
  [ -d "$dir/.git" ] && (cd "$dir" && git pull --ff-only 2>&1 | tail -1)
done

Step 3: Discover New Skills (Hub + Awesome List)

Step 3a: Check official hub for new skills (fastest, no GitHub auth needed):

# List all available official hub skills
hermes skills browse --size 100 --source official
Parse skill names (the '#' column has row numbers, name is column 2)
hermes skills browse --size 100 --source official 2>&1 > /tmp/hub_browse.txt
python3 -c "
import re
with open('/tmp/hub_browse.txt') as f:
    content = f.read()
skills = re.findall(r'│\s+\d+\s+│\s+(\S+)\s+│', content)
print(f'Hub has {len(skills)} skills')
for s in skills: print(s)
" > /tmp/hub_skill_names.txt
Compare against installed (at depth 2 in ~/.hermes/skills/ + hub optional-skills/)
find ~/.hermes/skills -maxdepth 2 -name "SKILL.md" -type f | while read f; do
  dir=\$(dirname "\$f"); basename "\$dir"
done | sort -u > /tmp/installed_local.txt
find /usr/local/lib/hermes-agent/optional-skills -maxdepth 3 -name "SKILL.md" -type f | while read f; do
  grep "^name:" "\$f" | head -1 | sed 's/name: *//'
done | sort -u > /tmp/installed_hub.txt
cat /tmp/installed_local.txt /tmp/installed_hub.txt | sort -u > /tmp/installed_all.txt
Find missing skills
comm -23 /tmp/hub_skill_names.txt /tmp/installed_all.txt

Install missing ones directly (no git clone needed):

hermes skills install    # e.g. hermes skills install sherlock

Step 3b: Refresh awesome-hermes-agent (for community/repo-based skills):

# Clone or pull the curated list
if [ -d /tmp/awesome-hermes-agent ]; then
  cd /tmp/awesome-hermes-agent && git pull --ff-only
else
  git clone --depth 1 https://github.com/0xNyk/awesome-hermes-agent /tmp/awesome-hermes-agent
fi
Extract repo URLs — filter to actual repos (must have owner/repo, not just user profiles)
grep -o 'https://github\.com/[^)"]*' /tmp/awesome-hermes-agent/README.md \
  | grep -E 'github\.com/[^/]+/[^/]+$' \
  | grep -v '/issues\|/releases\|/tree/' \
  | sort -u

Pitfall: No GitHub auth = can't clone repos. If git clone from GitHub fails with "could not read Username", the official hub (hermes skills install) still works because it uses the skills.sh registry API — no auth needed. Prefer hub installs when available; fall back to awesome-list only for skills not on the hub.

Step 4: Clone New Repos to Temp Dir

Always clone to /tmp/new-skill-checks/ first — never install directly. Filter out repos already in ~/.hermes/skill-repos/. Skip private/deleted repos gracefully.

mkdir -p /tmp/new-skill-checks && cd /tmp/new-skill-checks
Extract owner/repo from awesome list URLs
Compare against existing skill-repos to find NEW ones only
for repo in ; do
  dirname=$(echo "$repo" | tr '/' '_')
  echo -n "Cloning $repo ... "
  git clone --depth 1 "https://github.com/$repo.git" "$dirname" 2>&1 | tail -1
  # Private/deleted repos will fail with: "fatal: could not read Username" — skip them
done
Check which cloned repos actually contain SKILL.md files
for d in */; do
  count=$(find "$d" -name "SKILL.md" -type f 2>/dev/null | wc -l)
  [ "$count" -gt 0 ] && echo "  $d: $count skills"
done

Step 5: Install New Skills

Priority: Install from official hub first (hermes skills install), then from cloned repos.

From hub (preferred):

hermes skills install 
Installs to /usr/local/lib/hermes-agent/optional-skills///

No git clone needed, no GitHub auth required

From cloned repos (for skills NOT on the hub):
CRITICAL: Only install repos that contain SKILL.md files. Many awesome-list entries are Docker configs, templates, or tools — NOT skill packs. The find SKILL.md check in Step 4 filters these out.

Size-based install strategy:

20-100 skills: Copy repo directory to ~/.hermes/skills/ (gateway scans depth 2, nested skills are on-demand)

100+ skills (large packs): Create index SKILL.md at top level + copy all skills into nested skills/ subdirectory

DEST=~/.hermes/skills
For each validated repo from Step 4:
for repo_dir in /tmp/new-skill-checks//; do
  name=
  
  if [ ! -d "$DEST/$name" ]; then
    cp -r "$repo_dir" "$DEST/$name"
    echo "Installed $name"
  else
    echo "  $name: already exists, skipping"
  fi
done

For large packs (100+ skills), create an index SKILL.md:

mkdir -p "$DEST//skills"
cp -r /tmp/new-skill-checks//skills/* "$DEST//skills/"
cat > "$DEST//SKILL.md" << 'EOF'

name: 
description: >-
  



EOF

Persist new repos to skill-repos/ for future git pulls:

for repo_dir in /tmp/new-skill-checks/*/; do
  name=$(basename "$repo_dir")
  [ -d "$repo_dir/.git" ] && [ ! -d ~/.hermes/skill-repos/"$name" ] && cp -r "$repo_dir" ~/.hermes/skill-repos/"$name"
done

Step 6: Fix Broken Skills

# Add frontmatter if missing
with open("SKILL.md", "r") as f:
    content = f.read()
if not content.startswith("---"):
    fm = '---\nname: skill-name\ndescription: Auto-repaired skill\n---\n\n'
    with open("SKILL.md", "w") as f:
        f.write(fm + content)

Step 7: Measure & Restart

# Token impact — measure BOTH local and hub-installed skills
local_chars=$(find ~/.hermes/skills -maxdepth 2 -name "SKILL.md" -type f -exec grep "^description:" {} \; | wc -c)
hub_chars=$(find /usr/local/lib/hermes-agent/optional-skills -maxdepth 3 -name "SKILL.md" -type f -exec grep "^description:" {} \; | wc -c)
total=$((local_chars + hub_chars))
echo "Local: $local_chars chars | Hub: $hub_chars chars | Total: $total chars"
echo "Estimated tokens: $((total / 4)) (target: < 25K = 20% of 128K)"
Total skill counts
local_count=$(find ~/.hermes/skills -maxdepth 2 -name "SKILL.md" -type f | wc -l)
hub_count=$(find /usr/local/lib/hermes-agent/optional-skills -maxdepth 3 -name "SKILL.md" -type f | wc -l)
nested_count=$(find ~/.hermes/skills -name "SKILL.md" -type f | wc -l)
echo "Discoverable: $local_count local + $hub_count hub = $((local_count + hub_count))"
echo "Total incl nested: $nested_count + $hub_count = $((nested_count + hub_count))"
Restart gateway
systemctl restart hermes-gateway
sleep 5
systemctl is-active hermes-gateway

Skill Sources (Tracked Repos)

Git Repos (pull for updates)

playwright-skill, hermes-dojo, claudeception, reflexion, felo-skills

taste-skill, seo-geo-skills, screenshotone-skills, hermes-next

hermes-plugins, cybersecurity-skills, open-design, wondelai-skills

oh-my-hermes, agentcash, hermes-alpha, hermes-council

hermes-genesis, hermes-skill-factory, hermes-embodied, mercury

youtube-skills, mistral-mcp, chainlink-skills, super-hermes

skillsdotnet, pydanticai-docs, hermes-research-agent, bfl-skills

hermeshub-reviewer, hermes-life-os, hermes-incident-commander

hermes-skill-marketplace, MeiGen-AI-Design-MCP

Large Packs (on-demand, indexed)

cybersecurity-mitre-pack — 753 MITRE ATT&CK skills (nested in skills/)

open-design — 134 design system skills (nested in skills/)

wondelai-skills — 42 business/design skills (nested in skills/)

Skill Quality Validation (LLM Council)

After creating new skills (especially large ones 10K+), validate quality with LLM Council scoring:

Scoring rubric (10 dims × 10pts = 100 total):

Design & Architecture (10)

Flowcharts & Diagrams (10)

Implementation & Idiomatic Code (10)

Topic Coverage (10)

Security & Secure Coding (10)

Testing & QA (10)

Edge Cases & Error Handling (10)

Performance & Scalability (10)

Deployment & Operations (10)

Documentation & Maintainability (10)

Pass threshold: 80/100.

Critical: send FULL skill content (not truncated) to evaluators. Most LLM APIs truncate to ~3K chars, missing security/testing/deployment sections. Use a model with 128K+ context (Groq Llama 3.3 70B works well) and send the complete SKILL.md. Add 2-3 second delays between calls to avoid rate limits. If Groq key expires mid-session, switch to OpenRouter + google/gemini-2.0-flash-001. See references/llm-council-scoring.md for the full evaluation workflow, rubric details, past scoring results (coding + devops), and the OpenRouter fallback procedure.

Pitfalls

Gateway only scans ~/.hermes/skills/*/SKILL.md at depth 2 — nested packs must be indexed

Hub-installed skills go to /usr/local/lib/hermes-agent/optional-skills/ — they are NOT in ~/.hermes/skills/. Always measure token impact from BOTH paths

hermes skills list shows combined counts: "N builtin" = hub/optional skills, "M local" = ~/.hermes/skills/

hermes skills check/update only work for hub-installed skills (hermes skills install), NOT for git-cloned local skills

Large packs (>100 skills) should use index file + skills/ subdirectory, NOT flat install

Repos in /tmp/ are ephemeral — ALWAYS copy validated repos to ~/.hermes/skill-repos/ for persistence

Broken frontmatter causes gateway to skip the skill — always validate

Token budget target: keep under 25K tokens/turn (20% of 128K context)

Always systemctl restart hermes-gateway after changes — it caches skill list

Private/deleted repos fail with "could not read Username" — skip silently, don't retry

Many awesome-list URLs are user profiles or templates, NOT skill repos — always verify SKILL.md exists before installing. Filter with grep -E 'github\.com/[^/]+/[^/]+$' to exclude bare profile links

Clone to temp first — never install repos directly from awesome-list without checking SKILL.md count first

Name collisions — some repos share skill names (e.g. code-review in multiple repos). Use descriptive top-level dir names to avoid overwrites

awesome-hermes-agent is maintained by 0xNyk on GitHub — if that URL changes, check NousResearch org for updated link

Parsing hermes skills browse output — the table has multi-line rows with row numbers in column 1. Use regex │\s+\d+\s+│\s+(\S+)\s+│ to extract skill names. Simple awk -F'│' catches row numbers as skill names

No GitHub auth — git clone from GitHub may fail with "could not read Username". Use hermes skills install for hub-available skills instead (no auth needed). For community-only repos, the user needs gh auth login first

/tmp/ is ephemeral — awesome-hermes-agent clone in /tmp/ disappears on reboot. Always re-clone if missing; don't assume persistence

Delegate task subagents often omit YAML frontmatter — 4/8 skills created by subagents in one session missed --- frontmatter blocks. Always validate frontmatter after delegate_task skill creation

LLM council evaluators need FULL content — truncated 3K previews miss security/testing/deployment sections, causing artificially low scores. Send complete SKILL.md to evaluators with 128K+ context models

GLM models grade harshly on truncated content — when content is cut off, GLM-5.1 and Gemini score 20-40 points lower than when they see the full document. Use Groq Llama 3.3 70B (128K context) as primary evaluator

LLM council scoring provider priority: Groq → OpenRouter → Chutes → Manual expert eval. See references/llm-council-scoring.md for full details including provider-specific parsing pitfalls, score parser code, and historical results

API keys expire mid-session — Groq free tier keys and OpenRouter keys can both expire. Catch 401 errors and fall back down the provider chain

Chutes/Qwen models: (1) output ... blocks in the content field — strip before parsing; (2) return markdown bold format like 1._DESIGN: N/10 — use tolerant parser that strips ** and numbered prefixes; (3) content can be null — fall back to reasoning_content field

Manual expert evaluation is a valid fallback — when all LLM API providers fail, evaluate skills yourself using the 10-dimension rubric. Score conservatively: verified sections get 9-10, missing/thin sections get 6-8. Validated within ±3 points of automated scoring (May 2026)

For 95+ mastery threshold: every dimension must be 9-10/10. Target dimensions scoring ≤8 with dedicated subsections (Security Testing Procedures, Deployment Smoke Tests) inserted before ## Best Practices

Agent mastery skills created (May 2026): hermes-agent-mastery (36.5KB, 95/100), openclaw-mastery (29.6KB, 95/100), ai-agent-mastery (37.8KB, 96/100). All in ~/.hermes/skills/agents/

Non-coding skills (DevOps, infrastructure, security) tend to score low on Flowcharts, Testing, and Performance dimensions — subagents creating these skills often skip Mermaid diagrams, testing strategies, and performance tuning sections. After delegate_task creation, always check for these three sections and patch before scoring

DevOps skills need explicit sections for: (1) architecture flowcharts (Mermaid), (2) testing strategy (unit/integration/chaos), (3) performance optimization (scaling, caching, tuning). If a DevOps skill scores < 80, these are the missing sections to patch first

New DevOps skills (system-design, database, networking-SSL, server-hardening) showed same weakness pattern — Security (6-8/10), Deployment (6-7/10), Flowcharts (7/10). Patch by inserting Security Architecture, Deployment Strategies, and Performance sections before ## Best Practices

database-mastery passed first attempt (82/100) — the only new skill that didn't need patching. Its Security (7/10) was borderline but carried by strong Implementation (9), Coverage (9), and Performance (9)

Skill library overlapping skills: hermes-skills-install, skill-library-management, and hermes-skills-upgrade all cover skill installation. hermes-skills-upgrade is the authoritative workflow; the others are complementary but narrower

Token budget is measured per description lines only — actual skill token cost includes frontmatter + body loaded on skill_view. 8 coding skills (13-24KB each) added ~1.5K tokens over target — acceptable for rich skills, but monitor if adding many large skills

Large skill creation via direct write_file preferred — delegate_task has a 600s timeout that's insufficient for skill creation (only 2 API calls completed before timeout). Use write_file directly for creating SKILL.md files when content is >15KB. delegate_task still works for smaller tasks but not for crafting comprehensive skills

Patch strategy: insert-before-## Best Practices — when boosting weak dimensions (Security, Deployment, Performance), insert new sections just before the Best Practices section. This preserves existing content order and adds the missing material exactly where evaluators expect it

💬 Ask about Hermes Skills Upgrade

📄 Export PDF ← All Skills