Claude Code skills are reusable instructions that make an AI coding assistant behave consistently. Hermes Agent skills serve the same practical purpose, but they are portable: the same skill can guide a CLI session, a Telegram bot, a Discord bot, a cron job, or a background automation.
If you already wrote Claude Code skills, do not throw them away. The clean migration path is to keep the workflow, remove Claude Code-specific assumptions, rewrite the skill as a Hermes operating procedure, and test it on a real task before you retire the original file.
If your migration question is really about IDE assistants, compare Hermes Agent vs Cursor: Cursor is still strongest inside the editor, while Hermes turns reusable procedures into skills that can run from CLI, messaging, cron, and GitHub workflows. If you are checking source code or repository automation first, use the official Hermes Agent GitHub repository and integration page before wiring a migrated skill into your repos.
Why migrate at all?#
Claude Code skills are useful inside one coding tool. Hermes skills are more like portable operating procedures: the same workflow can guide a CLI session, a Telegram agent, a Discord bot, or a scheduled cron job. That matters when a workflow graduates from “help me code this once” to “run this process every week.”
The goal is not to mechanically copy prompt text. The goal is to preserve the proven workflow and make it reusable across Hermes surfaces.
Quick answer#
To migrate a Claude Code skill to Hermes Agent, follow this path:
- Open the original skill or command file. Identify what the skill is actually teaching the assistant to do.
- Extract the reusable workflow. Keep the trigger, steps, commands, constraints, examples, and verification checks.
- Create a Hermes skill folder. Use
~/.hermes/skills/<skill-name>/for your default profile, or a profile-specific skill folder for work bots. - Write
SKILL.md. Use clear YAML frontmatter, a “when to use” section, numbered steps, and pitfalls. - Load it in Hermes. Use
hermes -s <skill-name>from the CLI or/skill <skill-name>in a session. - Test it on a real task. Edit the skill until Hermes follows it without you re-explaining the workflow.
Start with one high-value skill. If you are setting up Hermes for the first time, follow the Hermes Agent install guide before moving your old skills over. A small library of verified Hermes skills is better than a large folder of stale Claude Code prompt hacks.
What changes when you move a skill to Hermes?#
Claude Code skills are usually designed for one environment: an interactive coding session inside Claude Code. Hermes skills are broader. They should read like durable operating procedures that can work from the terminal, a messaging gateway, or an autonomous scheduled job.
Primary use#
- Claude Code skill: coding inside Claude Code.
- Hermes Agent skill: any Hermes session, gateway, profile, or cron job.
Storage#
- Claude Code skill: wherever Claude Code stores skills or slash commands.
- Hermes Agent skill:
~/.hermes/skills/<name>/SKILL.md, or a profile-specific skill directory.
Loading#
- Claude Code skill: loaded through Claude Code.
- Hermes Agent skill: loaded with
hermes -s name,/skill name, or automatic skill discovery.
Persistence#
- Claude Code skill: reused by Claude Code.
- Hermes Agent skill: reused across Hermes CLI, Telegram, Discord, cron jobs, profiles, and other gateways.
Best migration target#
- Claude Code skill: repo conventions, code review habits, release checklists, and coding workflows.
- Hermes Agent skill: repeatable workflows with exact commands, safety constraints, and verification steps.
The biggest difference is scope. A migrated Hermes skill should not assume the user is sitting in Claude Code. Write it as a portable procedure that can work from Hermes' CLI, a Telegram agent, or a scheduled Hermes cron job.
Step 1: Audit the source skill#
Before you copy anything, decide whether the skill is worth migrating.
Good migration candidates#
- Repo-specific build, lint, and test procedures
- Code review checklists
- Release and deployment runbooks
- Incident triage steps
- Content publishing workflows
- Security review heuristics
- Tool-specific gotchas that apply outside Claude Code
Poor migration candidates#
- Skills that only describe Claude Code UI behavior
- Prompt hacks tuned to one model's quirks
- Instructions that reference missing tools or unavailable secrets
- Old workflows that no longer match the repo
- Skills that contain tokens, private URLs, or pasted terminal output with secrets
Treat migration as a cleanup pass. Hermes skills compound with persistent memory, so stale or unsafe instructions become more expensive over time.
Step 2: Convert the structure#
A practical Hermes skill usually has seven parts:
- Name: a short command-friendly name.
- Description: when Hermes should load it.
- When to use: the trigger conditions.
- Workflow: the ordered steps.
- Commands: exact commands or tools when they matter.
- Verification: how Hermes proves the work is done.
- Pitfalls: mistakes the agent should avoid next time.
Example folder:
~/.hermes/skills/repo-release-checklist/
└── SKILL.md
Example SKILL.md:
---
name: repo-release-checklist
description: Use before cutting a release for this repository.
---
# Repo Release Checklist
## When to use
Use this when preparing a release branch, changelog, or production deploy.
## Workflow
1. Check `git status --short` and do not overwrite unrelated work.
2. Pull the latest main branch with `git pull --ff-only`.
3. Run the unit tests and the production build.
4. Review the changelog for user-visible changes.
5. Tag only after build and tests pass.
## Verification
- `npm run lint`
- `npm run build`
- `git log --oneline -5`
## Pitfalls
- Never commit `.env`, auth files, browser profiles, or generated secrets.
- If the working tree is dirty, identify the owner of the changes before editing.
That format is intentionally plain. Hermes reads skills as operational context, so clarity beats clever formatting.
Step 3: Remove Claude Code-specific assumptions#
During migration, rewrite instructions that assume Claude Code is the runtime.
Replace UI-specific language#
Use the Claude Code Bash tool to run tests. If Claude suggests a plan, ask it to proceed.
Use portable Hermes language instead:
Run tests with the terminal tool. If a command modifies files, inspect the diff before committing.
Replace editor-specific language#
When Claude Code opens the file, edit the selected block.
Use a tool-agnostic instruction:
Use targeted file edits. Prefer small patches over rewriting unrelated sections.
A good Hermes skill describes the goal, guardrails, and verification. It should work whether Hermes is running in a terminal, as a Discord bot, or from a scheduled job.
Step 4: Put the skill in the right profile#
Hermes profiles are the clean boundary for skill isolation.
Use the default profile for personal skills:
~/.hermes/skills/<skill-name>/SKILL.md
Use a project or work profile when the skill depends on private repos, special credentials, or a bot with different permissions:
~/.hermes/profiles/work/skills/<skill-name>/SKILL.md
~/.hermes/profiles/projectbot/skills/<skill-name>/SKILL.md
Profiles isolate config, sessions, skills, memory, and gateway setup. That is safer than mixing personal, work, and bot-specific instructions into one global skill library.
Step 5: Load and test the migrated skill#
Load the skill directly in a one-shot session:
hermes -s repo-release-checklist chat -q "Review this repository for release readiness"
Or load it inside an interactive session:
/skill repo-release-checklist
Then test against a real task. The test is not “does the markdown parse?” The test is whether Hermes follows the procedure without you having to explain it again.
A good first test prompt:
Use the repo-release-checklist skill. Inspect this repo and tell me whether it is safe to cut a release. Do not change files unless needed.
After the run, update the skill with any missing checks, wrong paths, or commands Hermes had to infer.
Migration checklist#
Use this checklist for each Claude Code skill you convert:
- The skill has one clear purpose.
- The title and description say when to use it.
- Claude Code UI references were removed.
- Commands are explicit and current.
- Secrets and private tokens were removed.
- Verification steps are included.
- The skill was tested in a fresh Hermes session.
- The migrated skill lives in the correct Hermes profile.
Common mistakes#
Migrating everything at once#
Start with the 5–10 skills you actually use. A smaller, verified Hermes skill library beats a large graveyard of stale prompts.
Keeping model-specific prompt hacks#
If a Claude Code skill says “Claude tends to...”, rewrite it as an objective instruction or remove it. Hermes can run many providers via OpenRouter, Kimi, GLM, Ollama, and other models.
Forgetting gateways and cron#
Hermes skills are not just for coding. If a skill might run from Telegram or a scheduled job, avoid assumptions about interactive prompts.
Storing secrets in skills#
Put secrets in .env or the relevant profile environment, never in SKILL.md.
When to keep a skill in Claude Code#
You do not need to abandon Claude Code. Keep Claude Code skills there when they are purely IDE-session instructions or depend on Claude Code-specific behavior.
Move the skills to Hermes when they describe repeatable work you want an always-on agent to perform across tools, models, gateways, profiles, and schedules.
For many teams, the best workflow is complementary: Claude Code for IDE-focused coding, Hermes Agent for persistent memory, automation, multi-platform access, and reusable operational skills. If you are evaluating the broader trade-off, read Hermes Agent vs Claude Code.