The agentskills.io Standard: Why Hermes, Claude Code, and Cursor All Speak It
How agentskills.io became the markdown-native skill format shared across Hermes, Claude Code, Cursor, and Codex — and what it means for portability.
A year ago, every agent runtime invented its own way to describe a reusable procedure. Today, four of the most-used AI coding environments — Hermes, Claude Code, Cursor, and Codex — read the same markdown file format and call it a "skill." That convergence has a name: agentskills.io.
This is a short tour of why the format exists, what it actually specifies, and how it differs from MCP (with which it is frequently confused). If you write skills once and want them to survive the next runtime migration, the standard matters more than the runtime.
Key Takeaways
- agentskills.io is a markdown-plus-YAML-frontmatter format for describing a reusable agent procedure — the SKILL.md file.
- Hermes, Claude Code, Cursor, and Codex all parse this format. Tag namespaces and runtime-specific metadata differ, so skills are format-compatible rather than drop-in portable.
- The standard covers procedural memory (how to do a task). MCP covers tool I/O (what capabilities exist). They complement; they do not compete.
- A skill is a prompt fragment plus metadata, not executable code. That is deliberate — skills are inspectable by humans and auditable in version control.
- Hermes ships 100+ bundled skills across 24+ top-level categories following this standard.
- Minor tag tweaks between runtimes are normal; the body of a SKILL.md usually transfers unchanged.
What a SKILL.md Actually Is
A skill is a single markdown file with YAML frontmatter. The frontmatter declares when the skill should activate, what it is about, and which other skills relate to it. The body is plain markdown — instructions, examples, counter-examples, and references.
Here is an unmodified Hermes skill header:
---
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
metadata:
hermes:
tags: [testing, tdd, development, quality, red-green-refactor]
related_skills: [systematic-debugging, writing-plans, subagent-driven-development]
---
The name, description, and version fields are part of the agentskills.io core. The metadata.hermes block is a runtime extension — Claude Code uses a slightly different shape under its own key, and Cursor's annotation sits elsewhere in the tree. The body of the skill is identical across all four runtimes.
Why Four Runtimes Converged
Procedural memory for agents is not a new idea. What is new is the recognition that prompt fragments are the right unit of reuse — not fine-tuned weights, not plugin binaries. Once you accept that, the format question reduces to: "what do humans and LLMs both read comfortably?" Markdown won that argument a decade ago.
The practical pressure was also significant. Skill authors were tired of rewriting the same test-driven-development prompt for every runtime. Runtime builders were tired of fragmenting the author community. agentskills.io emerged from that shared fatigue — a minimal spec everyone could implement without surrendering runtime-specific features.
If you have written Claude Code skills before, see Are Claude Code Skills Portable to Hermes? for a practical migration walkthrough.
agentskills.io vs MCP
The two are often confused because both involve "extending an agent." They solve different problems.
| Concern | agentskills.io | MCP |
|---|---|---|
| Unit of extension | A procedure (how to do X) | A tool (a callable capability) |
| Format | Markdown + YAML | JSON-RPC over stdio or HTTP |
| Executed by | The LLM, as a prompt | The host runtime, as a function call |
| Versioning | Git, semver in frontmatter | Server version string |
| Inspection | cat skill.md | list_tools RPC |
Put plainly: MCP lets an agent do things it otherwise couldn't. agentskills.io lets an agent know how to do things well. A single task often uses both — an MCP tool to query a database, and a skill describing when and how that query belongs in the workflow.
For more on the MCP side of the story, see MCP in Hermes vs MCP in Claude Code Compared.
The Portability Caveat
"Format-compatible" is not "drop-in compatible." Three things commonly need tweaking when moving a skill between runtimes:
- Metadata namespace. Each runtime reads its own key (
metadata.hermes,metadata.claude-code, etc.). Your skill file needs the right key for the active runtime, or the tags are ignored. - Tool references. If a skill body says "use the
Greptool," that works in Claude Code but not in a runtime that calls the equivalent toolsearch_files. Skills that reference tools generically ("search the codebase") port more cleanly. - Activation hints. Hermes treats the
descriptionfield as activation guidance for the model's skill selector. Cursor has similar behavior but with a slightly different matcher. The language of the description matters.
Once you know these three patterns, porting is mostly mechanical. Most community skills on the Hermes Skills Hub that originated in other runtimes required no body changes at all.
A Minimal Valid Skill
If you are writing from scratch, this is enough:
---
name: conventional-commits
description: Use when creating a git commit to enforce Conventional Commits 1.0.0 style.
version: 1.0.0
author: your-handle
license: MIT
---
When asked to commit, use the format `type(scope): subject`.
Types: feat, fix, docs, refactor, test, chore, perf, build, ci.
Subject is imperative ("add login" not "added login"), no trailing period, under 72 chars.
If the change spans multiple types, split into separate commits.
Drop that file into ~/.hermes/skills/conventional-commits/SKILL.md, run hermes chat, ask for a commit message, and the skill activates on the description match. The same file, renamed and placed under .claude/skills/conventional-commits/SKILL.md, works in Claude Code.
Why This Matters for Skill Authors
Three practical consequences follow from the format convergence.
- Your skills survive runtime migrations. Choosing Hermes today does not lock you out of Claude Code tomorrow.
- Community skills are larger than any one runtime's library. A Hermes user can install a skill originally written for Cursor, and vice versa, with minor edits.
- Version control treats skills like code. A SKILL.md is a text file. It diffs cleanly, reviews cleanly in a PR, and ships with the rest of your repo.
For the self-improvement angle — where the agent itself writes new skills — see Self-Improving Agents: How Hermes Writes Its Own Skills from Experience.
Sources
- Hermes Agent repository — https://github.com/NousResearch/hermes-agent
- Hermes documentation — https://hermes-agent.nousresearch.com/docs/
- Anthropic Claude Code documentation — https://docs.anthropic.com/claude/docs/claude-code
- Model Context Protocol — https://modelcontextprotocol.io
- Series: Are Claude Code Skills Portable to Hermes?
- Series: MCP in Hermes vs MCP in Claude Code Compared
- Series: Writing Your First Hermes SKILL.md