hermes-agent/skills_system_analysis.md

Hermes Agent - Skills System Deep Analysis

Executive Summary

The Hermes skills system is a sophisticated procedural memory architecture that enables the agent to load specialized instructions, templates, and scripts on-demand. The system follows a progressive disclosure pattern inspired by Anthropic's Claude Skills, with three tiers:

1. Tier 0: Category discovery (minimal metadata)
2. Tier 1: Skill listing (name + description only)
3. Tier 2-3: Full content loading with linked files

---

1. Skills Taxonomy & Categorization

1.1 Built-in Skills (Active by Default) - 94 Skills

Category	Count	Description
mlops	41	ML/AI training, inference, evaluation, and deployment
software-development	7	Development workflows, debugging, planning
github	5	GitHub workflows, auth, issues, PRs
productivity	5	Notion, Linear, Google Workspace, OCR, PowerPoint
research	5	Academic paper writing, arXiv, domain intel
creative	4	ASCII art/video, Excalidraw, songwriting
media	4	YouTube, GIF search, SongSee, Heartmula
apple	4	Apple Notes, Reminders, FindMy, iMessage
autonomous-ai-agents	4	Claude Code, Codex, OpenCode, Hermes Agent
mcp	2	MCP server integration skills
email	1	Himalaya email client
smart-home	1	OpenHue lighting control
red-teaming	1	Godmode jailbreak testing
gaming	2	Minecraft, Pokemon
data-science	1	Jupyter live kernel
devops	1	Webhook subscriptions
inference-sh	1	Inference.sh CLI
leisure	1	Find nearby places
note-taking	1	Obsidian integration
social-media	1	Xitter (Twitter/X)
dogfood	2	Hermes self-testing

1.2 Optional Skills (Available but Inactive) - 22 Skills

Category	Count	Skills
research	4	bioinformatics, scrapling, parallel-cli, qmd
security	3	oss-forensics, 1password, sherlock
productivity	4	telephony, memento-flashcards, canvas, siyuan
blockchain	2	base, solana
mcp	1	fastmcp
migration	1	openclaw-migration
communication	1	one-three-one-rule
creative	2	meme-generation, blender-mcp
email	1	agentmail
devops	1	docker-management
health	1	neuroskill-bci
autonomous-ai-agents	1	blackbox

1.3 Category Hierarchy (Nested)

skills/
├── mlops/
│   ├── training/ (12 skills)
│   ├── inference/ (9 skills)
│   ├── evaluation/ (6 skills)
│   ├── vector-databases/ (4 skills)
│   ├── models/ (6 skills)
│   ├── cloud/ (2 skills)
│   ├── research/ (1 skill)
│   └── huggingface-hub/
├── github/
│   ├── github-auth
│   ├── github-issues
│   ├── github-pr-workflow
│   ├── github-code-review
│   └── github-repo-management
└── [other categories]

---

2. Skill Loading Flow Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│                        SKILL LOADING ARCHITECTURE                           │
└─────────────────────────────────────────────────────────────────────────────┘

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  User Input  │────▶│  /command or │────▶│ skills_list  │
│  (Slash cmd) │     │  skills_list │     │  (Tier 1)    │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
                          ┌───────────────────────┘
                          ▼
              ┌───────────────────────┐
              │  Progressive Disclosure │
              │  Tier 1: Metadata Only  │
              │  - name (≤64 chars)     │
              │  - description (≤1024)  │
              │  - category             │
              └───────────┬───────────┘
                          │
                          ▼
              ┌───────────────────────┐
              │    skill_view(name)   │
              │      (Tier 2-3)       │
              └───────────┬───────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
   ┌────────────┐  ┌────────────┐  ┌────────────┐
   │   Parse    │  │  Security  │  │  Platform  │
   │Frontmatter │  │   Guard    │  │   Check    │
   └─────┬──────┘  └─────┬──────┘  └─────┬──────┘
         │               │               │
         ▼               ▼               ▼
   ┌────────────┐  ┌────────────┐  ┌────────────┐
   │ Extract    │  │  Scan for  │  │  platforms:│
   │ - name     │  │  injection │  │  [macos]   │
   │ - desc     │  │  patterns  │  │  [linux]   │
   │ - version  │  │  exfil     │  │  [windows] │
   │ - metadata │  │  malware   │  └─────┬──────┘
   └─────┬──────┘  └─────┬──────┘        │
         │               │               │
         └───────────────┼───────────────┘
                         ▼
              ┌───────────────────────┐
              │   Load Full Content   │
              │   + Linked Files      │
              └───────────┬───────────┘
                          │
              ┌───────────┴───────────┐
              ▼                       ▼
    ┌─────────────────┐    ┌─────────────────┐
    │  linked_files   │    │  Prerequisites  │
    │  - references/  │    │  - env_vars     │
    │  - templates/   │    │  - commands     │
    │  - scripts/     │    │  - credential   │
    │  - assets/      │    │    files        │
    └────────┬────────┘    └────────┬────────┘
             │                      │
             ▼                      ▼
    ┌─────────────────┐    ┌─────────────────┐
    │ skill_view(name │    │ Secret Capture  │
    │  file_path=...) │    │   (if needed)   │
    └─────────────────┘    └─────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                           INSTALLATION SOURCES                              │
└─────────────────────────────────────────────────────────────────────────────┘

┌────────────────┐  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐
│    Built-in    │  │    Optional    │  │  Skills Hub    │  │   External     │
│   (bundled)    │  │   (bundled)    │  │  (remote)      │  │    Dirs        │
├────────────────┤  ├────────────────┤  ├────────────────┤  ├────────────────┤
│ skills/        │  │ optional-skills│  │ GitHub repos:  │  │ Configurable   │
│ Auto-copied to │  │ On-demand copy │  │ - openai/      │  │ external_dirs  │
│ ~/.hermes/     │  │ to ~/.hermes/  │  │   skills       │  │ in config.yaml │
│ on setup       │  │ on install     │  │ - anthropic/   │  │                │
│                │  │                │  │   skills       │  │                │
│ Trust: builtin │  │ Trust: builtin │  │ - VoltAgent/   │  │ Trust: varies  │
└────────────────┘  └────────────────┘  └────────────────┘  └────────────────┘

---

3. SKILL.md Format Specification

---
# Required fields
name: skill-name                  # Max 64 chars, filesystem-safe
description: Brief description    # Max 1024 chars

# Optional fields
version: 1.0.0                    # Semver
author: Author Name
license: MIT                      # SPDX identifier
platforms: [macos, linux]         # OS restrictions (omit for all)

# Legacy prerequisites (deprecated but supported)
prerequisites:
  env_vars: [API_KEY]             # Normalized to required_environment_variables
  commands: [curl, jq]            # Advisory only

# Modern requirements specification
required_environment_variables:
  - name: API_KEY
    prompt: "Enter your API key"
    help: "https://platform.example.com/keys"
    required_for: "API access"

required_credential_files:
  - ~/.config/example/credentials.json

setup:
  help: "How to get credentials"
  collect_secrets:
    - env_var: API_KEY
      prompt: "Enter API key"
      provider_url: "https://platform.example.com/keys"
      secret: true

# agentskills.io compatibility
compatibility: "Requires Python 3.9+"

# Hermes-specific metadata
metadata:
  hermes:
    tags: [tag1, tag2, tag3]
    related_skills: [skill1, skill2]
    fallback_for_toolsets: [toolset1]  # Conditional activation
    requires_toolsets: [toolset2]
---

# Content: Full instructions, procedures, examples...

---

4. Skill Quality Assessment

4.1 High-Quality Skills (Exemplary)

Skill	Strengths
github-auth	Complete detection flow, multiple auth methods, comprehensive troubleshooting table
axolotl	Rich frontmatter, multiple reference files, clear quick reference patterns
plan	Precise behavioral instructions, clear output requirements, specific save location
ml-paper-writing	Extensive templates (AAAI, ACL, ICLR, ICML, NeurIPS, COLM), structured references

4.2 Skills Needing Improvement

Skill	Issues	Priority
gif-search	Minimal content, no references, unclear triggers	High
heartmula	Single-line description, no detailed instructions	High
songsee	No frontmatter, minimal content	High
domain	Empty category placeholder	Medium
feeds	Empty category placeholder	Medium
gifs	Empty category placeholder	Medium
diagramming	Empty category placeholder	Medium
pokemon-player	Minimal procedural guidance	Medium
find-nearby	Limited context and examples	Medium
dogfood	Could benefit from more structured templates	Low

4.3 Missing Reference Files Analysis

Skills lacking supporting files (references, templates, scripts):

• 23% of skills have references/ directory
• 12% have templates/ directory
• 8% have scripts/ directory
• 60% have no supporting files at all

Recommendation: Add at least reference files to skills >500 tokens in content length.

---

5. Skill Dependency Analysis

5.1 Explicit Dependencies (Frontmatter)

# From github-auth skill
metadata:
  hermes:
    related_skills: [github-pr-workflow, github-code-review, github-issues, github-repo-management]

# From plan skill
metadata:
  hermes:
    related_skills: [writing-plans, subagent-driven-development]

5.2 Implicit Dependency Chains

GitHub Workflow Chain:
github-auth (foundation)
    ├── github-pr-workflow
    ├── github-code-review
    ├── github-issues
    └── github-repo-management

ML Training Chain:
axolotl (training framework)
    ├── unsloth (optimization)
    ├── peft (parameter-efficient)
    ├── trl-fine-tuning (RL fine-tuning)
    └── pytorch-fsdp (distributed)

Inference Chain:
vllm (serving)
    ├── gguf (quantization)
    ├── llama-cpp (edge inference)
    └── tensorrt-llm (NVIDIA optimization)

5.3 Toolset Fallback Dependencies

Skills can declare fallback relationships with toolsets:

# From skill_utils.py
extract_skill_conditions(frontmatter) -> {
    "fallback_for_toolsets": [...],  # Activate when toolset unavailable
    "requires_toolsets": [...],      # Only load when toolset present
    "fallback_for_tools": [...],     # Activate when tool unavailable
    "requires_tools": [...]          # Only load when tool present
}

---

6. Security Architecture

6.1 Skills Guard Scanner

┌─────────────────────────────────────────────────────────────┐
│                      SKILLS GUARD                           │
├─────────────────────────────────────────────────────────────┤
│ Threat Categories:                                          │
│ • Exfiltration (env vars, credentials, DNS)                │
│ • Prompt Injection (role hijacking, jailbreaks)            │
│ • Destructive Operations (rm -rf, mkfs, dd)                │
│ • Persistence (cron, shell rc, SSH keys)                   │
│ • Network (reverse shells, tunnels)                        │
│ • Obfuscation (base64, eval, hex encoding)                 │
│ • Privilege Escalation (sudo, setuid, NOPASSWD)            │
│ • Supply Chain (curl | bash, unpinned deps)                │
│ • Crypto Mining (xmrig, stratum)                           │
└─────────────────────────────────────────────────────────────┘

6.2 Trust Levels

Level	Source	Policy
builtin	Hermes bundled	Always allow
trusted	openai/skills, anthropics/skills	Caution allowed
community	Other repos	Block on any finding
agent-created	Runtime creation	Ask on dangerous

---

7. Ten New Skill Recommendations

7.1 High-Priority Gaps

#	Skill	Category	Justification
1	stripe-integration	payments	Payment processing is common need; current skills lack commerce focus
2	postgres-admin	databases	Only vector DBs covered; relational DB ops missing
3	redis-operations	databases	Caching patterns, session management common need
4	kubernetes-deploy	devops	Container orchestration gap; docker-mgmt exists but not k8s
5	aws-cli	cloud	Only Lambda Labs and Modal covered; AWS is dominant

7.2 Medium-Priority Gaps

#	Skill	Category	Justification
6	react-native-build	mobile	Mobile development completely absent
7	terraform-iac	infrastructure	IaC patterns missing; complement to webhook-subscriptions
8	prometheus-monitoring	observability	Monitoring/alerting gap; complement to dogfood
9	elasticsearch-query	search	Search functionality limited; ES common in prod
10	figma-api	design	Design system integration; complement to excalidraw

7.3 Skill Specification Template (stripe-integration)

---
name: stripe-integration
description: Process payments, manage subscriptions, and handle webhooks with Stripe API
version: 1.0.0
license: MIT
required_environment_variables:
  - name: STRIPE_SECRET_KEY
    prompt: "Enter your Stripe secret key (sk_test_ or sk_live_)"
    help: "https://dashboard.stripe.com/apikeys"
  - name: STRIPE_WEBHOOK_SECRET
    prompt: "Enter your webhook endpoint secret (optional)"
    required_for: "webhook verification only"
metadata:
  hermes:
    tags: [payments, stripe, subscriptions, e-commerce, webhooks]
    related_skills: []
---

# Stripe Integration

## Quick Start

1. Set `STRIPE_SECRET_KEY` in environment
2. Use test mode for development: keys start with `sk_test_`
3. Never commit live keys (start with `sk_live_`)

## Common Patterns

### Create a Payment Intent
```python
import stripe
stripe.api_key = os.environ["STRIPE_SECRET_KEY"]

intent = stripe.PaymentIntent.create(
    amount=2000,  # $20.00 in cents
    currency='usd',
    automatic_payment_methods={'enabled': True}
)

References

• references/api-cheat-sheet.md
• references/webhook-events.md
• templates/subscription-flow.py

---

## 8. Key Metrics

| Metric | Value |
|--------|-------|
| Total Skills | 116 |
| Built-in Skills | 94 |
| Optional Skills | 22 |
| Categories | 20+ |
| Average Skill Size | ~2,500 chars |
| Skills with References | 23% |
| Skills with Templates | 12% |
| Skills with Scripts | 8% |
| Security Patterns | 90+ |
| Threat Categories | 12 |

---

## 9. Architecture Strengths

1. **Progressive Disclosure**: Token-efficient discovery
2. **Security-First**: Mandatory scanning for external skills
3. **Flexible Sourcing**: Built-in, optional, hub, external dirs
4. **Platform Awareness**: OS-specific skill loading
5. **Dependency Chains**: Related skills and conditional activation
6. **Agent-Created**: Runtime skill creation capability
7. **Slash Commands**: Intuitive `/skill-name` invocation

## 10. Architecture Weaknesses

1. **Documentation Gaps**: 23% lack references, 60% no supporting files
2. **Category Imbalance**: MLOps heavily weighted (41 skills)
3. **Missing Domains**: No payments, mobile, infrastructure, observability
4. **Skill Updates**: No automatic update mechanism for hub skills
5. **Versioning**: Limited version conflict resolution
6. **Testing**: No skill validation/testing framework

---

*Analysis generated: 2024-03-30*
*Skills scanned: 116 total*
*System version: Hermes Agent skills architecture v1.0*