Are Claude Code Skills Portable to Hermes?
Short answer: yes, format-compatible. Long answer: there are a few differences in frontmatter, triggers, and related-skills resolution. Here is what to change.
Both Claude Code and Hermes follow the agentskills.io open standard. That is the whole reason this question has a clean answer rather than a messy one. A SKILL.md file is a markdown document with YAML frontmatter, a name, a description, and a body that teaches the agent when to invoke the skill. If you wrote it for Claude Code, it will almost always parse and load in Hermes. The word "almost" is doing some work, though, and this post is about what lives inside that word.
I want to be precise here because the easy answer misleads people. Claude Code skills are format-compatible with Hermes, not bit-identical. The differences show up in three places: the frontmatter namespace Hermes uses for its own metadata, the invocation-trigger phrasing conventions, and how related skills get resolved. Port a well-written skill and you are changing a handful of lines, not rewriting the file.
Key Takeaways
- Both runtimes use the agentskills.io standard, so top-level frontmatter (
name,description,version,license) is identical. - Hermes adds a
metadata.hermes.*namespace for tags, related skills, and runtime-specific hints. descriptionfields in Hermes lean toward "Use when..." phrasing to trigger the autonomous loop.- Related skills in Hermes resolve by name across the whole
~/.hermes/skills/tree; Claude Code scopes to.claude/skills/plus~/.claude/skills/. - File structure is the same: one directory per skill, SKILL.md inside.
- Tag conventions differ slightly — Hermes tags are lowercase-hyphenated, Claude Code is looser.
- For a full worked example, see Migrating a Claude Code Skill to Hermes.
What Is The Same
The core contract is identical. A skill is a directory that contains a SKILL.md file. That file has YAML frontmatter with at minimum a name and a description, followed by a markdown body. Both runtimes load skills by walking their skills directory, parsing the frontmatter, and indexing the descriptions so the agent can match a user request to a skill.
Top-level frontmatter fields are all shared:
---
name: test-driven-development
description: Use when implementing any feature or bugfix, before writing implementation code. Enforces RED-GREEN-REFACTOR cycle with test-first approach.
version: 1.1.0
author: Hermes Agent (adapted from obra/superpowers)
license: MIT
---
Both tools read all five of those fields. The name must be unique within the skill set. The description is what the agent matches against. version, author, and license are metadata for humans and package registries.
The markdown body is treated the same way. Both runtimes load it into the model's context when the skill is activated. Headings, code blocks, tables, and inline code render the same because both agents read raw markdown, not rendered HTML.
What Is Different
The metadata.hermes namespace
Hermes introduces a structured namespace for runtime-specific fields:
metadata:
hermes:
tags: [testing, tdd, development, quality, red-green-refactor]
related_skills: [systematic-debugging, writing-plans, subagent-driven-development]
Claude Code does not require or reject this block. If you leave it on a skill you use in Claude Code, it is ignored. If you omit it from a skill you want Hermes to use, everything still works — you just lose the ability to group by tag or surface related skills automatically.
My rule is: if a skill might run in either runtime, include the metadata.hermes block. It is additive.
Trigger phrasing in description
Claude Code pulls skills into context based on relevance scoring between your message and each skill's description. The phrasing can be loose because a human is usually in the loop. Hermes runs autonomously more often, so the idiomatic style for Hermes descriptions is "Use when..." followed by the concrete trigger:
# Claude Code style, loose
description: Enforces test-driven development via red-green-refactor.
# Hermes style, trigger-focused
description: Use when implementing any feature or bugfix, before writing implementation code. Enforces RED-GREEN-REFACTOR cycle with test-first approach.
Both parse in both runtimes. The second style matches better in Hermes because its autonomous loop leans on that trigger phrasing. If your skill will run mostly without human supervision, rewrite the description in the "Use when..." form.
Related skills resolution
Claude Code looks for related skills within the current project's .claude/skills/ folder and the global ~/.claude/skills/ folder. Hermes scans all of ~/.hermes/skills/ regardless of subdirectory, so skills living in ~/.hermes/skills/software-development/ and ~/.hermes/skills/red-teaming/ can cross-reference each other by name.
If your Claude Code skill lists related skills using relative paths, Hermes will not resolve them. Hermes uses bare names:
# Works in Hermes
related_skills: [systematic-debugging, writing-plans]
# Claude Code might accept either form
related_skills: [./systematic-debugging/SKILL.md]
Normalize to bare names when porting. They work in both.
Tag conventions
Hermes expects lowercase-hyphenated tags. Claude Code is more permissive. If you see mixed-case or underscored tags, clean them:
# Before
tags: [Testing, TDD_Workflow]
# After
tags: [testing, tdd, workflow]
File system location
Claude Code project skills live in .claude/skills/<skill-name>/SKILL.md. Global skills live in ~/.claude/skills/<skill-name>/SKILL.md. Hermes puts everything under ~/.hermes/skills/, usually organized into a category subdirectory such as software-development, autonomous-ai-agents, or red-teaming:
~/.hermes/skills/
├── software-development/
│ ├── test-driven-development/
│ │ └── SKILL.md
│ └── systematic-debugging/
│ └── SKILL.md
├── autonomous-ai-agents/
│ └── claude-code/
│ └── SKILL.md
└── red-teaming/
└── prompt-injection-testing/
└── SKILL.md
The category directory is a convention, not a requirement. Hermes walks the whole tree.
What Does NOT Port
A few things do not round-trip cleanly.
Claude Code hooks configured in settings.json — PreToolUse, PostToolUse, Stop — are not skills and not portable. They are harness-level behavior that Hermes has its own equivalent for. See Hermes Hooks vs Claude Code Hooks Compared for how those map.
CLAUDE.md project context files are also not skills. They are a different loading mechanism. Hermes memory fills that role, and moving content between the two is its own exercise — see CLAUDE.md to Hermes Memory Translation.
MCP configuration is mostly portable. Both runtimes speak the same MCP, and Hermes supports the same MCP servers Claude Code uses. You copy the server config to Hermes's MCP settings and you are done. See MCP in Hermes vs MCP in Claude Code Compared.
A Quick Compatibility Check
Before dropping a Claude Code skill into ~/.hermes/skills/, run through this checklist:
- Frontmatter has
nameanddescription. If not, add them. - Description uses "Use when..." phrasing. If not, rewrite.
- Tags are lowercase-hyphenated. If not, clean them.
related_skillsare bare names, not paths. If paths, strip them.metadata.hermesblock is present with at leasttags. If not, add it.- Body markdown is self-contained — no references to Claude Code-specific tools that Hermes does not have.
Item 6 is the subtle one. Claude Code has specific tooling like Edit, Read, and Write with particular argument shapes. Hermes has 47 built-in tools and the names may overlap but the semantics can differ. If your skill's body says "use the Edit tool with old_string and new_string parameters," it will generally work in Hermes, but it's worth testing. See 47 Hermes Tools Claude Code Doesn't Have for the full catalog.
The Practical Answer
For the majority of Claude Code skills I have tested — TDD workflows, debugging playbooks, codebase navigation skills, documentation generators — porting takes under five minutes. You copy the directory, add a metadata.hermes block, reword the description, normalize tags, and it runs. The underlying reason is that both runtimes agreed on the agentskills.io standard before either shipped to wide audiences, so they converged on the same shape by design.
If you are a skill author publishing on the aiskill.market marketplace, design your skills with the Hermes conventions from day one (lowercase tags, "Use when..." descriptions, metadata.hermes block, bare related-skill names). They will still work in Claude Code, and you get Hermes users for free.