**Duration:** ~45 minutes
**Prerequisites:** Module 4 (Tools & Capabilities)
**Skill Level:** Intermediate
5.1 Introduction
Most AI assistants are amnesiacs. You teach them something one day, and the next day they've forgotten it entirely. You show them exactly how to deploy your app, and tomorrow you have to explain it all over again. This is the fundamental limitation of the "chatbot" paradigm — every conversation starts from zero.
Hermes Agent breaks this cycle with **Skills**.
Skills are the single most important feature of Hermes Agent. They transform the agent from a transactional assistant (ask → answer → forget) into a **compound-learning system** that gets provably better over time. Every time you teach Hermes something, that knowledge persists, compounds, and makes future interactions faster, more accurate, and more autonomous.
By the end of this module, you'll understand:
- What skills are and why they're revolutionary
- The anatomy of a skill file (frontmatter + body)
- How to create, load, and manage skills
- The skill lifecycle (creation → curation → archival)
- The Skills Hub ecosystem (browse, install, publish)
- Best practices and anti-patterns
- How 50+ skills make you a super-agent user
5.2 What Are Skills?
A **skill** is a reusable, versioned procedure stored as a Markdown file with YAML frontmatter. Think of it as a "recipe" the agent can follow to accomplish a specific task.
---
name: deploy-to-nginx
description: Deploy a static site to an Nginx server on this machine
version: 1.2.0
tags: [deployment, nginx, devops, web]
author: ops-team
---
# Deploy to Nginx
1. Verify the site source directory exists at `/var/www/{site_name}`
2. Check that Nginx is running: `systemctl status nginx`
3. Copy the site configuration:
```
cp /etc/nginx/sites-available/{site_name} /etc/nginx/sites-enabled/
```
4. Test the configuration: `nginx -t`
5. Reload Nginx: `systemctl reload nginx`
6. Verify the site responds: `curl -s -o /dev/null -w "%{http_code}" http://localhost/{site_name}`
## Pitfalls
- If `nginx -t` fails, check for syntax errors in the config file
- Don't use `restart` — use `reload` to avoid downtime
- Ensure the document root directory exists before reloading
## Verification
- Site returns HTTP 200
- Nginx status shows "active (running)"
- New config appears in `nginx -T` output
That's it. A skill is just a Markdown file — simple enough to edit by hand, structured enough for the agent to parse and execute reliably.
What Makes Skills Different from Prompts?
| Aspect | Regular Prompt | Skill |
|---|---|---|
| **Persistence** | Ephemeral (one conversation) | Permanent (saved to disk) |
| **Versioning** | None | Explicit version field |
| **Structure** | Freeform text | Numbered steps + frontmatter |
| **Reusability** | Must re-explain | Load by name |
| **Curation** | None | Auto-archived when stale |
| **Sharing** | Not possible | Skills Hub registry |
5.3 Why Skills Matter
Skills solve three fundamental problems in AI-human interaction:
Problem 1: The Repetition Tax
Every time you ask the agent to do something non-trivial, you pay a "repetition tax" — explaining context, specifying commands, correcting mistakes. With skills, you pay that tax once. The next time, the agent already knows.
**Without skills:** "No, use `systemctl reload` not `restart`... remember Nginx has a test flag... check the config syntax first..."
**With skills:** "Deploy the site." The agent loads the skill and executes it perfectly.
Problem 2: Tribal Knowledge Loss
When you have workflows that only you know — deployment procedures, database backup commands, CI/CD conventions — that knowledge lives in your head (or scattered across docs). Skills make it explicit, versioned, and transferable. New team members get instant access to your operational knowledge.
Problem 3: Inconsistent Execution
Humans and AI alike make mistakes on complex multi-step procedures. A skill ensures the same steps execute in the same order every time, with the same verification checks.
The Compound Effect
Here's the key insight: **skills compound.** Each skill you create makes the agent more capable. After 10 skills, you have a capable assistant. After 50 skills, you have an agent that knows your entire stack — deployment, testing, debugging, monitoring, database management, code review, everything. You stop explaining and start **delegating**.
5.4 Skill Anatomy
Every skill file has two parts: **frontmatter** and **body**.
Frontmatter (YAML)
The frontmatter is a YAML block between `---` delimiters at the very top of the file. It contains metadata that helps the agent find, load, and manage the skill.
---
name: deploy-to-nginx # Unique identifier, lowercase with hyphens
description: > # Description used for matching queries to skills
Deploy a static site to an Nginx server on this machine.
Handles config validation, reload, and verification.
version: 1.2.0 # Semantic versioning: major.minor.patch
tags: # Tags for discoverability and grouping
- deployment
- nginx
- devops
- web
author: ops-team # Optional: who created/maintains this
depends_on: [] # Optional: other skills this one requires
os: [linux] # Optional: OS constraints
---
**Required fields:** `name`, `description`, `version`
**Strongly recommended:** `tags`
**Key rules:**
- `name` must be unique across all your skills
- `version` follows semver — bump `patch` for fixes, `minor` for new features, `major` for breaking changes
- `description` should be detailed; the agent uses semantic matching to find the right skill
Body (Markdown Instructions)
The body is a Markdown document with numbered steps, commands, pitfalls, and verification steps.
**Structure conventions:**
# {Skill Name}
{Context paragraph — what this skill does and when to use it}
1. {Step 1 — what to do}
```
{exact command or code}
```
2. {Step 2 — what to do next}
3. ...
## Pitfalls
- {Common mistake and how to avoid it}
- {Another pitfall}
- {Edge case to watch for}
## Verification
- {How to confirm the skill executed successfully}
- {Another verification check}
Numbered Steps
Steps should be:
- **Actionable:** "Copy the configuration file" not "Understand the configuration"
- **Deterministic:** The same inputs should produce the same outputs
- **Verifiable:** Each step should produce output you can check
- **Exact:** Include exact commands in code blocks
Pitfalls Section
This is where you capture **experience** — the mistakes you've made and the edge cases you've encountered. A skill without pitfalls is a recipe that only works in the happy path.
Good pitfalls:
- Warnings about common errors
- Environment-specific gotchas
- Ordering dependencies ("do X before Y")
- Failure modes and recovery steps
Verification Section
Every skill should end with verification steps that answer "how do I know this worked?" These are explicit checks the agent can run to confirm success.
Good verification steps:
- HTTP status checks (`curl -s -o /dev/null -w "%{http_code}"`)
- Service status checks (`systemctl is-active`)
- File existence checks (`test -f /path/to/file`)
- Output consistency checks (`diff expected.txt actual.txt`)
5.5 Creating a Skill
Skills are created using the `skill_manage` tool.
The `skill_manage` Tool
skill_manage(action="create", name="skill-name", path="/path/to/skill.md")
You can also create skills by asking the agent directly:
"Save this as a skill called 'deploy-to-nginx': first, check the source directory exists..."
The agent will:
1. Generate the skill file with proper frontmatter
2. Save it to the skills directory
3. Register it in the skill index
4. Confirm creation
Updating Skills
skill_manage(action="update", name="skill-name", path="/path/to/updated-skill.md")
Or just ask:
"Update the deploy-to-nginx skill — add a step to check disk space first."
Deleting Skills
skill_manage(action="remove", name="skill-name")
5.6 Loading a Skill
Skills are loaded on demand, either explicitly or implicitly.
Explicit Loading
**In Hermes Chat (Telegram):**
/skill deploy-to-nginx
/skill deploy-to-nginx site_name=myapp
The `/skill` command loads the skill and executes it. You can pass variables as `key=value` pairs.
**From the CLI:**
hermes -s deploy-to-nginx
Implicit Loading (Auto-Matching)
The agent automatically matches your query to relevant skills. If you say "deploy the site," the agent finds the `deploy-to-nginx` skill and asks if you'd like to use it.
**User:** "Deploy the new landing page to production."
>
**Agent:** "I have a skill for that: `deploy-to-nginx`. Shall I use it? (I'll deploy from `/var/www/landing-page`)"
Skill Variables
Skills can have variable placeholders using `{variable_name}` syntax. The agent fills these in from context or prompts you for missing values.
1. Check that the database {db_name} is running
2. Run migration: `migrate -d {db_name}`
When loading: `/skill run-db-migration db_name=production`
5.7 Complete Example Skill
Here's a complete, real-world skill you can create and use immediately:
---
name: diagnose-disk-space
description: >
Diagnose disk space issues on a Linux server.
Checks overall usage, largest directories, and
identifies old log files that can be rotated.
version: 1.0.0
tags:
- system
- disk
- diagnostics
- linux
author: hermes-agent
os: [linux]
---
# Diagnose Disk Space
Use this when the system reports low disk space or when
deployments fail due to insufficient storage.
## Prerequisites
- Root or sudo access
## Steps
1. Check overall disk usage:
```
df -h
```
Look for partitions above 80% usage.
2. Find the largest directories in `/`:
```
du -sh /* | sort -hr | head -20
```
3. For the most-used partition (from step 1), drill into
specific directories:
```
du -sh /var/log/* | sort -hr | head -10
du -sh /var/lib/* | sort -hr | head -10
```
4. Check for old log files (>30 days):
```
find /var/log -name "*.log" -type f -mtime +30 -exec ls -lh {} \; | head -20
```
5. Suggest cleanup actions:
- Rotate logs: `logrotate -f /etc/logrotate.conf`
- Clear apt cache: `apt-get clean`
- Remove old kernels: `apt-get autoremove --purge`
- Truncate specific large files (if safe)
- Add disk usage alerting if this is recurring
## Pitfalls
- Don't delete files without confirming with the user first
- `/tmp` may be mounted as `tmpfs` (RAM) — freeing space there
won't help with disk usage
- Be careful with `find -delete` — always preview first
- Some systems use LVM — check with `lvdisplay` if `df` is confusing
- Docker containers can consume `overlay2` storage in `/var/lib/docker`
## Verification
- At least 10% free space on critical partitions
- No partitions above 90% after cleanup
- System reports OK for `systemctl status`
- `df -h` shows improvement from initial state
5.8 The Skill Lifecycle
Skills aren't static — they evolve through a lifecycle managed by the Hermes Agent curation system.
Phase 1: Creation
You create a skill (or the agent creates one on your behalf). The skill is saved to the active skills directory and indexed.
Phase 2: Active Use
The skill is available for immediate loading. The agent tracks:
- **Usage frequency:** How often each skill is loaded
- **Success rate:** Whether verification steps pass
- **Error rate:** How often the skill produces errors
- **Last used:** When the skill was last invoked
Phase 3: Staleness Detection
The **Curator** (a built-in agent subsystem) periodically reviews all skills. A skill is flagged as "stale" if:
- It hasn't been used in 30+ days
- Its verification steps consistently fail
- Its commands reference tools or paths that no longer exist
- A newer version of the same workflow exists
Phase 4: Archival
Stale skills are auto-archived — moved to an archive directory and removed from the active index. They're not deleted; you can restore them if needed.
skills/
├── active/
│ ├── deploy-to-nginx.md
│ └── diagnose-disk-space.md
└── archived/
├── 2025-11-01_deploy-to-apache.md
└── 2025-10-15_old-backup-script.md
Phase 5: Restoration
If you need an archived skill:
skill_manage(action="restore", name="deploy-to-apache")
Or ask the agent: "Restore the old Apache deploy skill."
5.9 The Skills Hub
The **Skills Hub** is a central registry where you can browse, install, and publish skills.
Browsing
Check what's available:
/skillhub browse
/skillhub search "database backup"
/skillhub search --tag devops
Installing from the Registry
hermes skill install deploy-to-nginx
hermes skill install --from https://skills.example.com/my-skills.json
Publishing Your Skills
Share your skills with the community:
hermes skill publish diagnose-disk-space
Published skills are:
- Reviewed for quality and safety
- Indexed by tags for discoverability
- Version-tracked so users get updates
- Rated by the community
Private Registries
Organizations can run their own Skills Hub registries for internal workflows:
hermes skill registry add internal https://skills.internal.company.com
hermes skill install db-backup --registry internal
5.10 Best Practices
DO: Write Good Triggers
The `description` field is your skill's "trigger" — it's what the agent uses to match queries. Write descriptions that capture the words someone would naturally use.
❌ Bad: "Handles deployment procedures"
✅ Good: "Deploy a static site or web application to an Nginx server on Ubuntu/Debian"
DO: Use Numbered Steps
Numbered steps are deterministic. The agent executes them in order. Bullet lists are for context, not execution.
DO: Include Exact Commands
Don't describe what to do — show the exact command:
❌ Bad: "Check the Nginx configuration"
✅ Good: "Run `nginx -t`"
DO: Write a Useful Pitfalls Section
This is where the skill earns its keep. Every mistake you've made while running this procedure should be a pitfall.
DO: Always Verify
Every skill should end with verification steps that prove success. "It worked because I checked" is the skill's warranty.
DO: Version Your Skills
Bump versions when you make changes. This lets you (and the curator) track evolution.
DO: Tag Thoughtfully
Tags make skills discoverable. Use a consistent tagging convention.
DON'T: Make a Skill for One-Off Tasks
If you'll never do this again, don't make a skill. Skills are for procedures you repeat.
DON'T: Make Skills for Trivial Things
"Open the browser" is not a skill. Use your judgment — if it takes longer to create the skill than to do the task once, skip it (unless you'll do it many times).
DON'T: Hardcode Secrets
Never put passwords, API keys, or tokens in a skill file. Use environment variables or the agent's secret store instead.
# DO THIS
1. Connect: `psql -h {db_host} -U {db_user} -d {db_name}`
The agent will prompt for connection details.
# NOT THIS
1. Connect: `psql -h localhost -U admin -d myapp`
Password: s3cret!
5.11 When NOT to Make a Skill
Skills are powerful, but they're not the answer to everything. Here's when you should **not** create a skill:
| Scenario | Why Not | What Instead |
|---|---|---|
| One-time migration | You'll never do it again | Just ask the agent |
| "Hello World" example | Trivial, no repetition | Skip it |
| Dangerous operation | No safe verification | Document as a runbook, not a skill |
| Deeply contextual | Depends on too many variables | Break into smaller skills |
| Rapidly changing | Outdated in a week | Wait for stability |
| Personal preference | "I like tabs not spaces" | Save as a user profile preference |
**The litmus test:** Ask yourself "Will I need to do this again in the next 30 days?" If no, probably don't skill it. If yes, invest the 5 minutes.
5.12 Skills as Your Competitive Advantage
Here's the truth: **Hermes Agent is only as good as your library of skills.**
A new user with zero skills has a chatbot. A user with 10 skills has a capable assistant. A user with 50+ skills has a super-agent.
The 50-Skill Milestone
At 50 skills, something changes. The agent starts to:
- **Predict what you need** — before you ask
- **Chain skills together** — one task triggers a sequence of related skills
- **Offer proactive improvements** — "I notice you deploy frequently; I could set up automatic verification"
- **Become autonomous** — you say "handle the deployment" and it manages everything
What 50 Skills Looks Like
| Category | Skills |
|---|---|
| **DevOps (10)** | Deploy to Nginx, deploy to Docker, deploy to K8s, rollback, DB backup, log analysis, monitor health, scale services, SSL renewal, CI/CD setup |
| **Development (10)** | Code review checklist, run tests, lint code, create PR, review PR, debug crash, profile performance, optimize query, generate types, stub API |
| **System Admin (8)** | Diagnose disk, check memory, find process, configure firewall, set up user, audit security, update system, manage cron |
| **Data (6)** | ETL pipeline, backup DB, restore DB, analyze logs, generate report, data validation |
| **Writing (5)** | Draft changelog, write release notes, create RFC, review docs, format markdown |
| **Research (4)** | Search docs, find packages, compare solutions, summarize findings |
| **Quality (4)** | Run linter, check coverage, validate schema, audit dependencies |
| **Automation (3)** | Schedule task, watch directory, auto-cleanup |
The Winning Strategy
1. **Start small** — skill your most painful repeated task today
2. **Skill by correction** — whenever you correct the agent, ask: "Should this be a skill?"
3. **Review monthly** — look at archived skills, update stale ones, delete useless ones
4. **Publish and consume** — share skills internally, install from the hub
5. **Aim for 50** — it's the tipping point where the agent becomes truly autonomous
5.13 Summary
Skills are Hermes Agent's killer feature. They transform the agent from a stateless chat interface into a persistent, learning system that gets better every time you use it.
**Key takeaways:**
- Skills are Markdown files with YAML frontmatter (name, description, version, tags)
- They contain numbered steps, exact commands, pitfalls, and verification checks
- Create with `skill_manage(action="create")`, load with `/skill` or `hermes -s`
- The Curator auto-archives stale skills; the Skills Hub lets you share them
- Best skills are repeatable, verifiable, and versioned
- 50+ skills = a super-agent that knows your entire stack
**In the next module,** we'll cover how to train your agent — memory management, corrections, user profiles, and the powerful correction-to-skills pipeline.
5.14 Exercises
1. **Create your first skill:** Pick a task you do weekly and write a skill for it. Create it with the `skill_manage` tool.
2. **Load a skill:** Use `/skill` to execute your new skill.
3. **Review a skill:** Open an existing skill file, check its frontmatter is complete, ensure it has a pitfalls and verification section.
4. **Publish (optional):** If your skill is general-purpose, publish it to the Skills Hub.
5.15 Further Reading
- [Hermes Agent Skills Documentation](https://hermes-agent.nousresearch.com/docs/skills)
- [Skill Creation Best Practices Guide](https://hermes-agent.nousresearch.com/docs/skills/best-practices)
- [Skills Hub API Reference](https://hermes-agent.nousresearch.com/docs/skills/hub)
- [Curator Configuration](https://hermes-agent.nousresearch.com/docs/skills/curator)