One SKILL.md, Many Agents: Writing Agent Skills That Work in Claude Code, Codex, Cursor and Hermes

Most AI agent tools now read the same skill format. A folder with a SKILL.md file in it works in Claude Code, Codex, Cursor, GitHub Copilot, VS Code, Gemini CLI, goose, Amp, OpenCode and Hermes Agent, among others. That means you can write a workflow once and carry it between agents instead of rewriting a system prompt for each one.

This guide covers what the format actually requires, where each tool looks for skills, and the habits that make a skill get picked up reliably.

What a skill is

The Agent Skills specification defines a skill as a directory containing, at minimum, a SKILL.md file. The format was originally developed by Anthropic and released as an open standard (overview).

A typical layout looks like this:

release-notes/
├── SKILL.md          # required: metadata + instructions
├── scripts/          # optional: code the agent can run
├── references/       # optional: extra docs loaded on demand
└── assets/           # optional: templates, schemas, data

SKILL.md is YAML frontmatter followed by Markdown. Only two fields are required:

---
name: release-notes
description: "Drafts release notes from merged pull requests and the git log. Use when the user asks for release notes, a changelog entry, or a summary of what shipped since the last tag."
---

# Release notes

1. Find the previous tag with `git describe --tags --abbrev=0`.
2. List commits since that tag with `git log <tag>..HEAD --oneline`.
3. Group changes into Added, Changed and Fixed.
4. Use the template in `assets/template.md`.

## Edge cases
- If there are no tags, ask which commit to start from.

The rules people trip over

The spec is short, but a few constraints catch people out.

The name is strict. It has to be 1 to 64 characters, lowercase letters, numbers and hyphens only. It can't start or end with a hyphen, can't contain --, and it must match the parent folder name. PDF-Processing fails, and so does a folder called pdf_processing holding a skill named pdf-processing.

The description does the heavy lifting. It can be up to 1024 characters and should say both what the skill does and when to use it. The spec's own example of a poor description is "Helps with PDFs." Agents decide whether to load a skill mostly from this one field, so include the words a user would actually type.

Optional fields exist but are optional. license, compatibility (up to 500 characters, for things like "Requires git, docker and jq"), metadata (a string to string map) and allowed-tools are all in the spec. allowed-tools is marked experimental, and support varies between agents.

You can check your frontmatter with the reference validator:

skills-ref validate ./release-notes

Why skills are cheap on context

The format is built around progressive disclosure. According to the spec, agents load skills in three stages:

1. Metadata, roughly 100 tokens per skill. The name and description of every installed skill are loaded at startup.
2. Instructions. The full SKILL.md body loads only when the agent decides the skill is relevant. The spec recommends keeping it under 5000 tokens and under 500 lines.
3. Resources. Files in scripts/, references/ and assets/ load only when the task needs them.

So you can install dozens of skills without stuffing your context window. The practical consequence is that a long reference document belongs in references/, not pasted into SKILL.md. The spec also suggests keeping file references one level deep, so link references/api.md directly rather than chaining files that point to other files.

Where each agent looks

This is the part that differs between tools. The paths below come from each vendor's documentation, as collected in skillsboard's support table and the Hermes Agent docs.

A few things stand out. .agents/skills/ is the closest thing to a shared location, and Codex, Cursor and Copilot all read it. Claude Code uses .claude/skills/ instead, and Cursor and Copilot also read that folder for compatibility. Hermes keeps everything in ~/.hermes/skills/, which its docs describe as the single source of truth.

One more catch from the Anthropic docs, via the same skillsboard page: skills uploaded to claude.ai and skills on your filesystem for Claude Code don't sync with each other.

A setup that works across tools

If you use more than one agent, the simplest approach is to keep one canonical copy of each skill and point the other locations at it.

# keep the real skills here
mkdir -p ~/.agents/skills

# let Claude Code and Hermes see the same folders
ln -s ~/.agents/skills/release-notes ~/.claude/skills/release-notes
ln -s ~/.agents/skills/release-notes ~/.hermes/skills/release-notes

For a team repo, commit skills to .agents/skills/ and add a .claude/skills/ symlink if anyone on the team uses Claude Code. Check that your tools follow symlinks before relying on this. If one doesn't, a small sync script that copies the folder is the fallback.

Vendor extensions are fine

Several agents add their own frontmatter on top of the standard. Claude Code documents extra features beyond the spec. Hermes Agent adds a top-level platforms field and optional fields under metadata.hermes, such as requires_toolsets, fallback_for_toolsets and config (Hermes skill docs). The requires_toolsets option, for example, hides a skill unless the tools it depends on are active.

These are additive. A skill that only uses name and description works everywhere, and other clients generally ignore fields they don't recognise. So write the portable core first and add vendor fields only when you need the behaviour.

Habits that make skills actually trigger

A skill that never activates is just a file. These come straight from the spec's guidance plus common sense about how agents choose:

• Write the description for matching, not marketing. List the tasks and the words users say. "Use when the user mentions PDFs, forms, or document extraction" beats a one line summary.
• Make the body a procedure. Numbered steps, example inputs and outputs, and a short edge cases section, which is what the spec recommends.
• Move bulk out of SKILL.md. API references, long examples and lookup tables go in references/ or assets/.
• Put fragile steps in scripts. If a step must run the same way every time, a script in scripts/ with clear error messages is more reliable than prose instructions.
• Keep one job per skill. Two narrow skills with sharp descriptions get picked more accurately than one broad skill that tries to cover both.

Where to find existing skills

Before writing your own, check what's already out there. The Agent Skills client showcase lists products that support the format and links to each one's docs. Hermes Agent can also install skills from a hub with hermes skills install, and its docs note the agent can create and edit skills itself in ~/.hermes/skills/.

Running skills in Hermes Agent

If you want an agent that writes and refines its own skills over time, Hermes Agent from Nous Research is worth a look, and it's compatible with the same SKILL.md format covered above.

Disclosure: the link below is my referral link. Nous Portal Plus is $20 a month and includes Hermes Agent usage and a cloud agent. Eligible new subscribers get $15 off their first paid month through this referral link, and I get a $10 credit if you sign up.

Sources

• Agent Skills specification
• Agent Skills overview
• Agent Skills client showcase
• Agent Skills support by client, skillsboard
• Hermes Agent skills system
• Creating skills for Hermes Agent