Skill Library Management

| Source | Stars | What It Has |
|--------|-------|-------------|
| awesome-hermes-agent | 3K+ | Curated community list — skills, plugins, tools, deployment guides |
| hermeshub | 185 | 22 production skills with security scanning |
| felo-skills | — | 14 skills: search, web-fetch, x-search, slides, etc. |
| composio | — | 1,000+ SaaS integrations via CLI |
| Official Docs | — | Built-in and optional skills list |
| Blog roundups (Felo, Composio) | — | Sometimes surface hidden gems |

Full Upgrade Sweep (Repeatable Workflow)

When the user says "upgrade skills", "repeat", or "add more skills for X", run this end-to-end sweep:

1. AUDIT current state (count, categories, token impact)
REFRESH awesome-hermes-agent: cd /tmp/awesome-hermes-agent && git pull
GIT PULL all tracked repos (skill-repos + git-tracked skills)
MINE EXISTING PACKS — grep cloned repos for uninstalled skills matching user needs
DISCOVER new repos: parse awesome list, compare against installed
CLONE new repos in batches (use terminal() NOT execute_code background)
INSTALL new skills (handle large packs vs standalone)
VALIDATE all SKILL.md frontmatter + fix broken symlinks
MEASURE final token impact
RESTART gateway: systemctl restart hermes-gateway
UPDATE memory with final counts

Step 4 Detail: Mining Existing Packs (Fast Path)

Before cloning new repos, check what's already in /tmp/ from previous sessions. This is faster and avoids GitHub rate limits:

# 1. List all cloned repos with skill counts
for dir in /tmp/*/; do
    count=$(find "$dir" -name "SKILL.md" -type f 2>/dev/null | wc -l)
    [ "$count" -gt 0 ] && echo "$(basename $dir): $count skills"
done
2. For a user request like "document/proposal/tender/mindmap/design/graphics",
   grep all existing packs for matching skills
find /tmp/open-design -name "SKILL.md" -type f | xargs grep -l -iE "document|proposal|tender|mindmap|design|graphic|chart|diagram|presentation|pdf|excel" 2>/dev/null
3. Install matching skills that aren't already in ~/.hermes/skills/
for skill_dir in $(find /tmp/open-design -name "SKILL.md" -type f -exec dirname {} \;); do
    skill=$(basename "$skill_dir")
    if [ ! -d "$HOME/.hermes/skills/$skill" ]; then
        cp -r "$skill_dir" "$HOME/.hermes/skills/$skill"
        echo "INSTALLED $skill"
    fi
done

Key repos to mine for document/design/research skills:
| Repo | Best For |
|------|----------|
| open-design (134) | Documents, decks, reports, dashboards, design |
| orahermes-agent (168) | Finance models, data viz, blockchain |
| wondelai-skills (42) | Business strategy, marketing, UX |
| felo-skills (14) | Mindmaps, slides, search, web extraction |
| hermes-research-agent (92) | Research, literature review |
| MeiGen-AI-Design-MCP | Image/video generation, product photoshoots |

Key implementation notes:

Use terminal() for git clone — execute_code background processes are unreliable

Clone in sequential batches of 10 (not parallel background — they silently fail)

After cloning, scan each repo: find $repo -name "SKILL.md" -type f | wc -l

Install standalone skills (1-5 per repo) directly as top-level dirs

Large packs (50+ skills) get the indexed-pack pattern (see below)

Check for broken frontmatter: find ~/.hermes/skills -maxdepth 2 -name "SKILL.md" -exec grep -L "^name:" {} \;

Fix broken frontmatter by prepending ---\nname: \ndescription: "..."\n---\n

Always move repos to ~/.hermes/skill-repos/ before symlinking (never symlink to /tmp)

Update memory with final counts after restart

Installation Procedure

Step 1: Evaluate Before Installing

Never install blind. For each candidate skill:

Read the SKILL.md frontmatter (name, description)

Check if you already have overlapping functionality

Categorize by impact: 🔥 High / ⚡ Medium / 📦 Low

Skip skills that overlap with existing built-in or already-installed skills

Step 2: Parallel Clone Independent Repos

When installing from multiple sources, clone in parallel since they're independent:

# Example: install 4 packs in parallel
cd ~/.hermes/skills && git clone https://github.com/org/repo1.git repo1 &
cd ~/.hermes/skills && git clone https://github.com/org/repo2.git repo2 &
wait

Use execute_code with multiple terminal calls for true parallelism.

Step 3: Handle Nested Repo Structures

Many repos (felo-skills, seo-geo-skills, taste-skill, reflexion/context-engineering-kit) nest skills inside subdirectories. The gateway scans ~/.hermes/skills/*/SKILL.md — it does NOT recurse into subdirectories by default.

Solution: Symlink sub-skills to top level for discoverability:

# Example: Felo skills are nested at felo-skills///
for skill in felo-search felo-web-fetch felo-x-search; do
    src="$HOME/.hermes/skills/felo-skills/$skill"
    dest="$HOME/.hermes/skills/$skill"
    if [ -d "$src" ] && [ ! -d "$dest" ]; then
        ln -s "$src" "$dest"
    fi
done

For reflexion/context-engineering-kit (different structure):
The repo uses plugins/reflexion/skills/{reflect,critique,memorize}/ layout. Create top-level SKILL.md manually AND symlink sub-skills:

# Create top-level SKILL.md
cat > ~/.hermes/skills/reflexion/SKILL.md << 'EOF'

name: reflexion
description: "Self-refinement loop..."

Reflexion
Sub-skills
reflexion-reflect — Reflect on previous response
reflexion-critique — Multi-perspective review
reflexion-memorize — Curate insights into CLAUDE.md
EOF
Symlink sub-skills
for skill in reflect critique memorize; do
    ln -s "$HOME/.hermes/skills/reflexion/plugins/reflexion/skills/$skill" \
          "$HOME/.hermes/skills/reflexion-$skill"
done

Step 4: Validate All SKILL.md Files

After installation, verify frontmatter is valid:

for skill_dir in ~/.hermes/skills//*/; do
    f="$skill_dir/SKILL.md"
    if [ -f "$f" ]; then
        name=$(grep -m1 "^name:" "$f" | sed 's/name: *//' | tr -d '"')
        desc_len=$(grep -m1 "^description:" "$f" | wc -c)
        echo "✅ $(basename $skill_dir) → $name (${desc_len}c desc)"
    else
        echo "❌ $(basename $skill_dir) → SKILL.md missing!"
    fi
done

Step 5: Measure Token Impact

Before restarting, measure the cost:

# Total description text (what enters context per turn)
CRITICAL: use -maxdepth 2 — the gateway only scans top-level SKILL.md files
Recursive find massively overestimates (e.g., 219K chars vs actual 67K)
find ~/.hermes/skills -maxdepth 2 -name "SKILL.md" -type f -exec grep "^description:" {} \; | wc -c
Rule of thumb: 1 token ≈ 4 chars (English)
So 56,000 chars of descriptions ≈ 14,000 tokens per turn
On 128K context model: 14K/128K = 11% — acceptable

Token budget thresholds (measured at maxdepth 2):

< 8K tokens: Green zone — no concern

8-15K tokens: Yellow zone — monitor, trim if model is budget-constrained

> 15K tokens: Red zone — consider pruning low-value skills or moving to subdirectories

Massive skill packs (>50 sub-skills): Do NOT install individually at the top level. Use the indexed-pack pattern — create a single top-level SKILL.md and place sub-skills in a skills/ subdirectory. The gateway's maxdepth-2 scan means nested files are invisible to the description catalog but available for on-demand skill_view loading. Examples: cybersecurity-mitre-pack (753 skills), open-design (134 skills).

Step 6: Restart Gateway

# Check for active sessions first (other users chatting)
ps aux | grep "slash_worker" | grep -v grep | wc -l
Restart
systemctl restart hermes-gateway
Verify
sleep 8
systemctl is-active hermes-gateway
Check memory freed (restart often releases stale worker memory)
free -h | head -2

Impact of restart:

Kills active chat sessions (users need to resend)

WhatsApp bridge reconnects automatically (~10-15 sec)

WebUI stays running (separate systemd service)

Memory/Hindsight persists (disk-backed)

Cron jobs unaffected

Skills rescanned from ~/.hermes/skills/ on startup

Pitfalls

Gateway only scans top-level directories — Nested SKILL.md files (e.g., felo-skills/search/felo-search/SKILL.md) won't be discovered without symlinks to ~/.hermes/skills//SKILL.md

Some repos aren't standard skill repos — reflexion/context-engineering-kit is a Claude Code plugin, not a Hermes skill repo. You need to manually create the top-level SKILL.md and symlink sub-skills.

Composio install needs HOME set — The install script fails with HOME: unbound variable in some environments. Fix: export HOME=/root && curl -fsSL https://composio.dev/install | bash

Gateway restart kills active sessions — Always check ps aux | grep slash_worker before restarting. If other users are chatting, warn them first.

Skills are NOT all loaded into RAM — Only the description: field is indexed at startup (~200-500 chars each). Full SKILL.md content loads on-demand when triggered. RAM impact is negligible; token budget is the real concern.

Duplicate skills from different sources — HermesHub, built-in skills, and community repos may have the same skill (e.g., docker-manager exists in all three). Check with find ~/.hermes/skills -name "SKILL.md" | xargs grep "name: docker" before installing.

hindsight_retain captures stable facts, not install events — Don't save "installed X skill" to memory. Save "user has 289 skills, ~14K tokens/turn from descriptions" as it's durable state.

Symlinks to /tmp break on reboot — If you symlink skills from a cloned repo, copy the repo to ~/.hermes/skill-repos/ first, then symlink from the permanent location. /tmp is cleared on reboot.

Pip editable installs from /tmp break on reboot — Copy the repo to ~/.hermes/skill-repos/ before pip install -e. Better: install as a regular (non-editable) package with pip install so it bakes into site-packages.

Massive packs need the indexed-pack pattern — Repos with 50+ sub-skills should be installed as a single top-level directory with a SKILL.md index and skills/ subdirectory, NOT as individual top-level skills. This keeps the description catalog small while making skills available via skill_view.

Frontmatter validation is required — Some community SKILL.md files lack the name: field. After install, run: find ~/.hermes/skills -maxdepth 2 -name "SKILL.md" -type f -exec grep -L "^name:" {} \;

Background & in execute_code terminal() is unreliable — Use sequential terminal() calls within execute_code instead. Each blocks until complete.

Large pack installation (50+ skills) — Repos like cybersecurity-mitre-pack (754), open-design (134), orahermes-agent (168), hermes-research-agent (92) need special handling:

    # 1. Create the indexed pack directory
    mkdir -p ~/.hermes/skills/cybersecurity-mitre-pack
    
    # 2. Write a top-level SKILL.md index (this is what the gateway scans)
    #    Include: name, description, usage instructions, category listing
    #    Keep description under 500 chars to control token budget
    
    # 3. Copy the skills/ subdirectory for on-demand access
    cp -r /tmp/repo/skills ~/.hermes/skills/cybersecurity-mitre-pack/skills
    
    # 4. The nested skills are NOT scanned (maxdepth 2) but ARE accessible
    #    via skill_view(name='cybersecurity-mitre-pack', file_path='skills/...')

This pattern prevents token budget explosion (754 skills × ~200 chars = 150K tokens!) while keeping all skills accessible on-demand.

Awesome list discovery workflow — To find NEW repos not yet installed:

    # 1. Parse awesome list for GitHub URLs
    grep -oP 'https://github\.com/[^)\s"]+' /tmp/awesome-hermes-agent/README.md | sort -u
    
    # 2. For each repo, check if already installed
    for repo_url in $urls; do
        name=$(echo "$repo_url" | sed 's|.*/||')
        if [ ! -d ~/.hermes/skills/$name ] && [ ! -d ~/.hermes/skill-repos/$name ]; then
            echo "NEW: $name"
        fi
    done
    
    # 3. Clone new repos in batches of 10
    # 4. Scan for SKILL.md files
    # 5. Install unique skills (skip duplicates)

Frontmatter fix patterns — Some community SKILL.md files lack proper frontmatter:

    # Fix missing name: field
    with open(path, 'r') as f:
        content = f.read()
    if not content.startswith('---'):
        fm = '---\nname: \ndescription: "..."\n---\n\n'
        with open(path, 'w') as f:
            f.write(fm + content)

Duplicate detection across large packs — When installing from multiple large repos, check for overlaps:

    # Find skills that exist in multiple repos
    for skill in $(ls /tmp/new-repo/skills/); do
        if [ -d ~/.hermes/skills/$skill ]; then
            echo "DUP: $skill (already installed)"
        else
            echo "NEW: $skill"
        fi
    done

Common duplicates: docker-manager, solana, agentmail, qmd appear in multiple repos.

GitHub rate limiting during bulk clones — Cloning 10+ repos in rapid succession triggers "could not read Username for 'https://github.com': No such device or address" errors. This is NOT an auth issue — it's rate limiting. Workarounds:

- Clone in batches of 5-8 with a 2-second pause between batches - Always check if a repo was already cloned before re-attempting: [ -d /tmp/repo-name ] && echo "EXISTS" - If rate-limited, mine existing clones instead of fetching new ones (see "Mining Existing Packs" in the upgrade sweep) - Some repos are genuinely private (mnemo-hermes, master-skill, cognify-skills) — these will always fail

Duplicate clone detection — fatal: destination path already exists means you already have it. Check before cloning:

    [ -d /tmp/repo-name ] || git clone --depth 1  /tmp/repo-name

Mining existing packs for user-requested categories — When the user asks for skills in a domain (e.g., "document, proposal, mindmap, design, graphics"), grep all existing cloned repos in /tmp/ for matching skills before cloning new repos. This is faster and avoids rate limits. Use case-insensitive regex: grep -l -iE "document|proposal|tender|mindmap|design|graphic" across all SKILL.md files in /tmp/*/.

hermes-skills-install — Significant overlap with this skill. Both cover discovery, evaluation, installation, and impact analysis. This skill focuses on organization, symlinks, and token impact; hermes-skills-install focuses on source evaluation, type-specific install commands, and the Quick Reference table. Both were patched in May 2026 with identical pitfalls (symlinks to /tmp, pip from /tmp, indexed-pack pattern for massive repos, maxdepth-2 token measurement). Consider consolidation — the combined skill would be the authoritative reference for all skill library operations.

# Clone repo
cd /tmp && git clone --depth 1 https://github.com/org/repo.git
Install all skills except unwanted ones
for skill in $(ls /tmp/repo/skills/); do
    if [ "$skill" != "skip-this" ]; then
        cp -r /tmp/repo/skills/$skill ~/.hermes/skills/$skill
    fi
done
Validate
find ~/.hermes/skills -name "SKILL.md" -newer /tmp/repo -exec grep -l "^name:" {} \;
Cleanup
rm -rf /tmp/repo
Restart
systemctl restart hermes-gateway

💬 Ask about Skill Library Management

📄 Export PDF ← All Skills