# Hermes Agent: Skills System Deep Dive

## What It Is

Skills are on-demand knowledge documents (SKILL.md files) that the agent loads when needed. Progressive disclosure minimizes token usage — the agent only loads full content when actually executing a skill.

## Architecture

```
Level 0: skills_list()           → [{name, description, category}]   (~3k tokens)
Level 1: skill_view(name)        → Full content + metadata           (varies)
Level 2: skill_view(name, path)  → Specific reference file           (varies)
```

## Storage

```
~/.hermes/skills/                  # Single source of truth
├── devops/
│   └── deploy-k8s/
│       ├── SKILL.md               # Main instructions (required)
│       ├── references/
│       ├── templates/
│       ├── scripts/
│       └── assets/
├── .hub/                          # Skills Hub state
│   ├── lock.json
│   ├── quarantine/
│   └── audit.log
└── .bundled_manifest              # Tracks seeded bundled skills
```

## How ngn-agent Should Use This

**DON'T BUILD a custom skill system** — Hermes already has it. Instead:

1. **Author custom skills** as SKILL.md files in `~/.hermes/skills/` or via the skill hub tap system
2. **Use skill bundles** to group related infra workflows under one command
3. **Let the agent self-improve** — `skill_manage` tool creates/updates skills after complex tasks
4. **Publish as a tap** if sharing with a team: `hermes skills tap add myorg/ngn-skills`

## SKILL.md Format

```yaml
---
name: my-skill
description: Brief description
version: 1.0.0
platforms: [macos, linux]
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    requires_toolsets: [terminal]
---
# Skill Title
## Procedure
1. Step one
2. Step two
## Pitfalls
## Verification
```

## Key Capabilities for ngn-agent

| Capability | Description | Use for ngn-agent |
|------------|-------------|-------------------|
| Skill Hub install | `hermes skills install openai/skills/k8s` | Install community infra skills |
| Agent-created skills | Agent auto-saves workflows as skills | Self-improving diagnostic skills |
| Skill bundles | `hermes bundles create infra --skill aws-diagnostics --skill jira` | Group related tools |
| External dirs | `skills.external_dirs: [~/.agents/skills]` | Share skills across tools |
| Conditional activation | `fallback_for_toolsets/frequires_toolsets` | Only show skills when needed |
| Write approval gating | `skills.write_approval: true` | Safety gate for agent-created skills |

## Limitations

- Skills are per-profile (each Hermes profile has its own `~/.hermes/skills/`)
- External dirs are not read-only by default (agent can modify shared skills)
- Skills Hub requires GitHub API (60 req/hr unauthenticated, 5000 with GITHUB_TOKEN)