Set Up a Self-Improving AI Agent

Run a self-hosted AI agent that learns from its own work using Hermes.

Introduction

30 Second Summary

Every time you figure out a better way to do something, you remember it for next time. What if your AI agent could do the same thing?

In this project, you will set up a self-hosted AI agent on your Mac that connects to Claude, completes multi-step tasks using built-in tools, and automatically creates reusable skill documents from its own experience.

title

git status

What You'll Build

A fully configured Hermes Agent installation that connects to the Anthropic API, triggers autonomous skill creation, and reuses that knowledge on follow-up tasks.

By the end of this project, you'll have:

A running Hermes Agent on your Mac connected to Claude via the Anthropic API.
An auto-generated skill document created by the agent after completing a complex, multi-step task.
A verified understanding of how the learning loop, memory system, and skills architecture work together to make the agent self-improving.
A connected Telegram messaging gateway so you can chat with your agent from your phone (Secret Mission).

Are there any prerequisites?

You need a Mac with Terminal access, Git installed (macOS includes it by default), and an Anthropic API key from console.anthropic.com. For the Secret Mission, you also need a Telegram account.

Install Hermes Agent

Before you can teach an AI agent to learn from its own work, you need the agent itself.

Hermes Agent is an open-source, self-hosted AI agent by Nous Research. In this step, you will install it on your Mac using the official one-line installer, connect it to Claude via the Anthropic API, and verify everything is working.

In This Step, Get Ready To:

Install Hermes Agent and all its dependencies with a single terminal command.
Connect Hermes to the Anthropic API using your API key.
Verify the installation by running a test conversation with the agent.

Run the Installer

The Hermes installer handles everything you need automatically. It installs Python 3.11 (via uv), Node.js v22, ripgrep, ffmpeg, clones the repository, creates a virtual environment, and sets up the global hermes command. The only prerequisite is Git, which macOS includes by default.

Open your terminal and run the one-line install command:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

What does this command do?

This downloads the official install script from the Hermes GitHub repository and pipes it directly to bash for execution. The script detects your operating system and installs all required dependencies without needing sudo for Python version management.

The installation takes a few minutes. Once it finishes, you need to reload your shell so the new hermes command becomes available.

Reload your shell configuration:

source ~/.zshrc

It worked

Your terminal should accept the command without any errors. You are ready to move on to configuring your provider.

I see an error

If you see a "file not found" error, your shell might use .bash_profile instead. Try running source ~/.bashrc instead.

Still seeing an error?

If reloading a different shell config file did not help, help me troubleshoot my Hermes installation.

Configure the Anthropic Provider

Hermes needs to know which AI model to use. The hermes model command launches an interactive setup that walks you through selecting a provider and entering your credentials. Hermes uses the native Anthropic Messages API for direct Anthropic connections, not an OpenAI-compatible wrapper.

Run the model configuration command:

hermes model

Select Anthropic when prompted for your provider.
Select API key when asked for the authentication type.
Paste your Anthropic API key when prompted.

Where does Hermes store my key?

Hermes stores your API key as ANTHROPIC_API_KEY in ~/.hermes/.env. Non-secret settings like your model choice go in ~/.hermes/config.yaml. Everything stays local on your machine.

Verify the Installation

Hermes includes a built-in diagnostic command that checks your entire setup. After confirming everything looks good, you will start the agent and send a test message to make sure the connection to Claude is working.

Run the diagnostic check:

hermes doctor

What should I see?

The hermes doctor command checks that all dependencies are installed, your provider is configured, and your API key is valid. You should see green checkmarks for each component.

Start Hermes in interactive mode:

hermes

You should see a welcome banner showing your chosen model and the tools available to the agent.

Type a simple test prompt to confirm the connection works:

What tools do you have available? List them briefly.

The agent should respond with a list of its built-in tools. This confirms that Hermes is running, connected to Claude, and ready to accept tasks.

Exit the session by pressing Ctrl+C or typing /quit.

Having trouble connecting?

If you see an authentication error, double-check that your Anthropic API key is correct and has available credits. You can re-run hermes model to reconfigure your provider at any time. If you are seeing a different error, help me debug my Hermes connection.

Your agent is installed, configured, and talking to Claude. Next up, you will explore the CLI interface and the 40+ built-in tools that make Hermes a capable assistant right out of the box.

Explore the CLI and Built-in Capabilities

Your Hermes Agent is installed and connected to Claude. Before you trigger the learning loop, you need to understand the tools at your disposal. Hermes ships with a rich CLI interface, slash commands for session management, and 40+ built-in skills. Getting comfortable with these now will help you recognize what changes when the agent starts creating its own skills later.

In This Step, Get Ready To:

Navigate the Hermes CLI using slash commands for session and tool management.
Test the agent's ability to execute terminal commands on your behalf.
Browse the bundled skills library to see what the agent already knows.

Start a New Session and Explore Slash Commands

Hermes uses slash commands to control sessions, tools, and agent behavior without leaving the chat interface. These commands are separate from the prompts you send to the agent.

Launch Hermes in your terminal.

hermes

Type /help to see all available slash commands.

/help

Type /tools to see which tools are currently enabled.

/tools

Key Slash Commands to Know

/new starts a fresh conversation.
/model switches models.
/save saves the current conversation.
/personality changes the agent's communication style.

You can also enter multi-line input by pressing Alt+Enter.

Test the Agent's Tool Usage

Hermes is not just a chatbot. It can execute terminal commands, read and write files, and interact with your system. To see this in action, give it a task that requires using its terminal tool. Pay attention to how it handles command execution. The agent shows you the commands it wants to run and asks for your approval on potentially dangerous ones.

Type the following prompt into your Hermes session.

Check my current directory and tell me what the main files are. Then create a directory called hermes-playground in my home folder.

What Should I See?

The agent will make multiple tool calls. It will run commands like ls and mkdir to inspect your directory and create the new folder. You should see the agent display each command before executing it. This is the same tool execution system that powers the learning loop you will trigger in the next step.

Browse the Bundled Skills Library

Hermes ships with 40+ bundled skills out of the box. These are Markdown files stored in ~/.hermes/skills/, organized by category subdirectories. Browsing them now gives you a baseline. After you trigger the learning loop in the next step, you will come back to this directory and find a brand-new skill the agent created on its own.

Use the /skills browse command to see the full list of available skills.

/skills browse

Alternatively, ask the agent naturally to show you some interesting skills.

What skills do you have? Show me a few interesting ones.

Why Are Skills Stored as Markdown Files?

Skills follow the open agentskills.io standard. Each skill is a directory containing a SKILL.md file with YAML frontmatter and structured sections. Because they are plain Markdown, skills are portable across other tools like Claude Code, Cursor, and Codex CLI. You can also read and edit them yourself.

You now have a solid feel for how to interact with Hermes, what tools it has, and what skills it ships with. Next up, you will put the agent to real work with a complex task designed to trigger its autonomous skill creation system.

Trigger the Learning Loop

You have explored the CLI and confirmed that Hermes can execute tools on your behalf. Now it is time to trigger the feature that makes Hermes unique among AI agent frameworks: the autonomous skill creation loop. When Hermes completes a task that involves 5 or more tool calls, it automatically generates a reusable skill document capturing the approach, edge cases, and domain knowledge it discovered along the way.

In this step, you will give Hermes a complex research-and-build task, watch it work through multiple tool calls, and then verify that it produced a structured output file.

In This Step, Get Ready To:

Give Hermes a multi-step research task that triggers 5+ tool calls.
Observe the agent using web search, terminal commands, and file writing tools.
Verify that the agent completed the task and produced a structured output file.

Start a Fresh Session and Give a Complex Task

Hermes needs a task complex enough to involve multiple tool calls. A research-and-build task works well because it naturally requires web searches, terminal commands, and file writes. The magic number is 5 tool calls. That is the threshold that triggers Hermes to create a skill from its experience.

Start Hermes if it is not already running.

hermes

Start a fresh conversation with no prior context.

/new

Give Hermes the following research task. You can copy and paste this prompt directly.

Research the top 5 most popular open-source AI agent frameworks in 2026. For each one, find the GitHub star count, primary language, and key differentiator. Create a markdown comparison table and save it to ~/hermes-playground/agent-frameworks-comparison.md. Include a summary section with your recommendation for different use cases.

Why this specific task?

This prompt is designed to force multiple types of tool usage. The agent will need to search the web for current data, run terminal commands to create directories and files, and write structured Markdown output. Each of these actions counts as a tool call, and the combination should comfortably exceed the 5-call threshold.

Watch the Agent Work and Observe Tool Calls

As Hermes works through the task, pay close attention to the tool calls it makes. Each time the agent searches the web, runs a terminal command, or writes to a file, that counts toward the 5-call threshold.

Watch the terminal output as Hermes processes the task.
Count the tool calls you see. You should notice web search calls, terminal commands (like mkdir), and file write operations.
If the agent asks for approval before running a command, review the command and approve it.

After completing a task with 5 or more tool calls, Hermes automatically triggers its skill creation system using the skill_manage tool. You may see a message about the agent creating a skill, or it may happen silently in the background.

Pro tip: be patient

This task involves multiple web searches and file operations. It may take a minute or two for the agent to complete everything. Let it work through the full task without interrupting.

Verify the Output

Once the agent finishes, confirm that it actually produced the file you asked for. This is the tangible result of the task, separate from the skill document the agent creates behind the scenes.

Open a new terminal tab or exit Hermes with /quit.
View the output file the agent created.

cat ~/hermes-playground/agent-frameworks-comparison.md

What should I see?

You should see a Markdown file with a comparison table listing AI agent frameworks, their GitHub star counts, primary languages, and key differentiators. There should also be a summary section with use-case recommendations. The exact content will vary based on what the agent found during its research.

✋ File not found?

If the file does not exist, the agent may have saved it to a slightly different path. Run ls ~/hermes-playground/ to check what files are in the directory. If the directory itself does not exist, the agent may not have completed the task successfully. Help me troubleshoot why Hermes did not create the output file.

Your agent just completed a complex, multi-step task and should have triggered the skill creation system behind the scenes. In the next step, you will hunt down the skill document it generated and learn exactly how Hermes captures knowledge for future reuse.

Inspect the Generated Skill

Your agent just completed a complex task and quietly did something remarkable. It reflected on its own work and created a reusable skill document capturing what it learned. In this step, you'll find that document, read through its structure, and understand how Hermes turns one-time experience into permanent knowledge.

In This Step, Get Ready To:

Locate the auto-generated skill document in your skills directory.
Read and understand the SKILL.md format and its sections.
Learn how the progressive disclosure system keeps the agent fast even with thousands of skills.

Find the Auto-Generated Skill

All skills live in ~/.hermes/skills/, organized into category subdirectories. The agent places skills it creates alongside the 40+ bundled skills that ship with Hermes. You need to find the one that was just created.

Open a new terminal window (or exit Hermes if you're still in a session).
List the skills directory sorted by modification time to spot the newest entry.

ls -lt ~/.hermes/skills/

The directory at the top of the list is the most recently modified. That is where your new skill lives.

Use find to locate SKILL.md files that are newer than the bundled manifest. This filters out all the pre-installed skills and shows only agent-created ones.

find ~/.hermes/skills -name "SKILL.md" -newer ~/.hermes/skills/.bundled_manifest

What does this command do?

The -newer flag tells find to only return files modified more recently than the reference file. The .bundled_manifest file was created during installation, so anything newer than it was created by the agent after setup.

You can also ask the agent directly. Start Hermes and type: "What skills have you created?"

Not seeing any new SKILL.md files?

Skill creation triggers after tasks with 5 or more tool calls that the agent considers sufficiently complex. If your research task did not generate enough tool calls, go back to Step 3 and try the task again with a more detailed prompt. Make sure the agent performs web searches, writes files, and runs terminal commands.

If you're still stuck, help me figure out why Hermes didn't create a skill after my task.

Read and Understand the Skill Document

Each skill is a directory containing a SKILL.md file (required) plus optional subdirectories for references, templates, scripts, and assets. The SKILL.md file is where all the captured knowledge lives.

Open the generated SKILL.md file using cat. Replace the path below with the one you found in the previous substep.

cat ~/.hermes/skills/[[SKILL_PATH="category/skill-name"]]/SKILL.md

The document follows a standard format. Here is what each section means:

YAML frontmatter at the top contains the skill's name, description, version, supported platforms, and other metadata.
When to Use defines the trigger conditions. These tell the agent when this skill is relevant to a future task.
Procedure lays out the step-by-step approach the agent discovered while completing the task.
Pitfalls captures known failure modes and edge cases the agent encountered or anticipated.
Verification describes how to confirm the task was completed successfully.

What is the agentskills.io standard?

Hermes skills follow the open agentskills.io standard. This means the skill documents you create in Hermes are portable. You can use them with other tools like Claude Code, Cursor, Codex CLI, and Gemini CLI. The format is not locked to a single agent framework.

Understand the Progressive Disclosure System

You might wonder what happens when the agent accumulates hundreds or thousands of skills. Loading all of them into every conversation would consume a massive number of tokens and slow everything down. Hermes solves this with progressive disclosure, a three-level loading system.

Level 0 loads just the skill index. This is a list of skill names and descriptions, costing about 3,000 tokens total. The agent always has this loaded.
Level 1 loads the full content of a specific skill. The agent only does this when it identifies a relevant skill for the current task.
Level 2 loads specific reference files attached to a skill. This is for skills that include templates, scripts, or detailed documentation.

This design means the agent can have 10,000+ skills without any performance penalty. The underlying SQLite database with FTS5 full-text search indexing retrieves matching skills in under 10 milliseconds.

How does this fit into the memory architecture?

Skills are one layer of a three-layer memory system. Session context is fast, ephemeral working memory for the current conversation. The persistent store is the SQLite database holding skills, task summaries, and preferences. The user model is a drift-adjusting profile of your communication style, domains, and decision patterns that updates over time.

Together, these three layers give the agent both short-term recall and long-term learning.

You now understand exactly how Hermes captures knowledge and organizes it for efficient retrieval. Next up, you'll put the learning loop to the test by giving the agent a similar task and watching it reuse the skill it just created.

Test Skill Reuse

You have a skill document sitting in your agent's memory. The real question is whether Hermes actually uses it. In this step, you will give the agent a similar task in a clean session and observe whether the learning loop closes. A fresh session means no conversation history from the previous task. The only way the agent can follow the same structured approach is by retrieving the skill it created.

In This Step, Get Ready To:

Give the agent a similar research task in a clean session with no prior context.
Observe whether the agent retrieves and applies its previously created skill.
Compare the output quality and efficiency between the first and second tasks.

Start a Fresh Session and Give a Similar Task

Starting a new conversation with /new wipes the session context completely. The agent will have no memory of your previous research task. The only knowledge it can draw on comes from its persistent store, which includes the skill it auto-generated.

Launch Hermes if it is not already running.
Type /new to start a clean session.

/new

Now give the agent a task that is structurally similar to your first one but covers a different topic. The key is that the task shape is the same: research items, gather specific data points, and produce a comparison table.

Enter the following prompt:

Research the top 5 most popular open-source LLM inference frameworks in 2026. For each, find the GitHub star count, primary language, and key differentiator. Create a markdown comparison table and save it to ~/hermes-playground/inference-frameworks-comparison.md with a recommendation section.

Why a similar but different topic?

If you gave the exact same task, the agent might just repeat cached results. A different topic with the same structure forces the agent to recognize the pattern and retrieve its skill, not just replay a conversation.

Observe Skill Retrieval

As the agent works, watch closely for signs that it is drawing on its learned skill. The agent's three-layer memory architecture is working behind the scenes: session context handles the current conversation, the persistent store (SQLite with FTS5) retrieves matching skills and summaries, and the user model applies your preferences.

Here is what to look for:

The agent may explicitly mention loading or referencing a skill.
It may follow a more structured, confident approach from the very first tool call, instead of exploring and figuring things out.
The output format may closely match the structure from your first task.

How Does Skill Retrieval Work?

Hermes uses progressive disclosure to keep token usage low. At Level 0, it loads just the skill index (name and description, about 3k tokens total). When it finds a relevant match, it escalates to Level 1 and loads the full SKILL.md content. This means having thousands of skills does not slow the agent down.

Compare the Results

Once the agent finishes, check the output file and compare it to your first task's result.

Run the following command to view the new output file:

cat ~/hermes-playground/inference-frameworks-comparison.md

A well-functioning learning loop means the agent should complete this similar task more efficiently, following the procedure it documented in its skill. In Nous Research's benchmarks, agents with 20+ self-created skills complete tasks about 40% faster than fresh instances.

Compare the structure of inference-frameworks-comparison.md with agent-frameworks-comparison.md from Step 3.
Notice whether the formatting, section headings, and overall approach are consistent.

Pro tip: side-by-side comparison

You can quickly compare both files side by side using the diff command. Run diff ~/hermes-playground/agent-frameworks-comparison.md ~/hermes-playground/inference-frameworks-comparison.md to see structural similarities and differences.

✋ The agent didn't seem to use the skill?

Skill retrieval depends on the agent finding a semantic match between your new task and the stored skill. If the output looks unstructured or the agent seems to be starting from scratch, try asking it directly: "Do you have any skills related to research comparisons?" This nudges the agent to check its skill index. You can also run /skills browse to confirm the skill still exists.

If you are still having trouble, help me troubleshoot why my Hermes agent is not retrieving its auto-created skill.

You have now seen the full learning loop in action. Your agent completed a task, captured what it learned as a reusable skill, and applied that knowledge to a new problem. This is the core concept behind self-improving AI agents. Every complex task makes the agent a little smarter for next time.

Secret mission

Connect the Telegram Gateway

Your Hermes Agent is powerful, but it's trapped in your terminal. What if you could message it from your phone while you're on the go? In this secret mission, you'll connect the Telegram messaging gateway so your agent becomes a personal assistant you can reach from anywhere.

Before you go

Decide whether to keep your Hermes Agent installation running, pause it to come back later, or delete it entirely. This project runs entirely locally with all data stored in ~/.hermes/, so there are no ongoing infrastructure costs. The only variable cost is Anthropic API usage, which is pay-per-token and only incurred when you actively use the agent.

Resources you used:

Hermes Agent installation (cloned repo, virtual environment, global hermes command).
Hermes data directory at ~/.hermes/ (config, skills, memory, secrets).
The ~/hermes-playground/ directory with output files from your tasks.
Anthropic API key stored in ~/.hermes/.env.
Telegram bot (Secret Mission only).

Keep everything running

No action needed. Choose this if you plan to keep using Hermes Agent as a daily tool. Your skills, memory, and configuration will persist between sessions.

Hermes only uses Anthropic API tokens when you actively run it. There are no background processes or idle costs.
Your auto-generated skills in ~/.hermes/skills/ will continue to grow as you use the agent for more tasks.
Run hermes update periodically to stay on the latest version.

Pause - I'll come back to this later

Since Hermes runs entirely locally and has no background processes, there is nothing to pause. Your installation stays dormant until you run hermes again.

If you started the Telegram gateway, stop it with Ctrl+C. It only runs while the process is active.
Your skills, memory, and configuration in ~/.hermes/ will be preserved when you return.
Resume your last session anytime with hermes -c.

Delete - I don't want to use this again

Remove all Hermes Agent files and configuration from your machine.

Delete the Hermes data directory, which contains your config, skills, memory, and API keys:

rm -rf ~/.hermes

Delete the playground directory you created during the project:

rm -rf ~/hermes-playground

Remove the Hermes shell alias from your ~/.zshrc file. Open the file in a text editor and delete any lines related to Hermes.
If you created a Telegram bot for the Secret Mission, you can delete it by messaging @BotFather on Telegram and sending /deletebot.
Your Anthropic API key remains active on your Anthropic account. If you want to revoke it, visit console.anthropic.com and delete the key from your API settings.

Mission accomplished

Nice work! You just set up a self-improving AI agent that learns from its own experience and gets better over time.

Here's what you accomplished:

Installed and configured Hermes Agent on macOS with the Anthropic provider, connecting it to Claude via the native Anthropic Messages API.
Triggered the autonomous skill creation system by completing a complex multi-step task, then inspected the auto-generated SKILL.md document to understand how the agent captures knowledge for reuse.
Verified the closed learning loop by giving the agent a similar task in a fresh session and observing it retrieve and apply its self-created skill.
Connected the Telegram messaging gateway so you can chat with your agent from your phone, turning it into a personal assistant you can reach from anywhere.

Ready to quiz yourself?