Hermes Skills Upgrade

Hermes Skill Library Upgrade

Prerequisites

Key Files & Paths

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

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

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:

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)

Large Packs (on-demand, indexed)

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):

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