# 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

```yaml
---
# 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)

```yaml
# 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:

```python
# 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)

```yaml
---
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*