The agentskills.io Standard: One Format, Every Platform

One Skill, Many Agents

The agentskills.io open standard defines a minimal, portable format for agent skills. A skill written to the standard works, without modification, on any compliant agent — Claude Code, Hermes, OpenClaw, Cursor, Junie, ZeroClaw, Gemini CLI, OpenHands, GitHub Copilot, VS Code, Amp, Goose, Roo Code, and dozens more. The standard was originally developed by Anthropic and is now open to ecosystem contributions.

Portability comes from a clear boundary: six fields are part of the open standard; everything else is a platform-specific extension. Staying within those six fields means your skill is portable. Using extensions means gaining platform power at the cost of portability — a tradeoff to make consciously.

The Six Portable Fields

• name — display name in skill listings. Defaults to the directory name on most platforms.
• description — what the skill does and when to use it. The primary routing signal at Level 0.
• license — the license covering the skill (e.g., MIT, Apache-2.0). Platforms accept but do not enforce it.
• compatibility — environment requirements or prerequisites in plain text. Maximum 500 characters.
• metadata — a free-form YAML map for custom key-value data. Platforms do not act on the contents.
• allowed-tools — pre-approved tools for the turn. Space or comma-separated, or a YAML list.

If your SKILL.md frontmatter contains only these six fields, it can be packaged and published to the agentskills.io catalog without errors. Including platform-specific fields causes a hard packaging error when uploading to the shared catalog.

Platform Extensions: What Travels and What Stays

Description Limits: Two Different Targets

Both platforms impose description length constraints, but for different reasons and with different numbers:

• Claude Code — the description and when_to_use fields are truncated at a combined 1,536 characters. Put the primary use case first in description; keep when_to_use for supplementary trigger phrases. Do not duplicate information across both fields.
• Hermes — the Level 0 catalog pass treats the description as a routing string. Keep it under ~60 characters: terse, search-result-style phrasing. Narrative explanations belong in the skill body, not in the description field.

Platform Guards

Hermes supports a platforms: list — macos, linux, or windows — that acts as a hard filter. When specified, Hermes silently omits the skill on non-matching operating systems with no error message. This is useful for skills that wrap OS-specific tooling. The silent omission can also mask visibility issues in CI environments if the assumed platform does not match.

Shell Selection: Cross-OS Authoring

The shell field is a Claude Code-only extension — not part of the portable agentskills.io standard — that declares which shell interpreter runs the skill's inline command blocks. Set shell: bash for Unix and macOS environments or shell: powershell for Windows. When omitted, Claude Code defaults to bash. This lets you write a single skill that targets a specific OS shell explicitly, rather than assuming the host platform, which is particularly useful when distributing skills to teams that work across operating systems.

Writing for Portability vs. Platform-Optimized

Write for portability when the skill encodes general knowledge or a workflow that has value across agents — a code review checklist, a documentation style guide, a deployment runbook that does not use shell injection. Restrict frontmatter to the six portable fields.

Write platform-optimized when you need Claude Code features like context: fork, dynamic shell injection, or session hooks — or when you need Hermes features like toolset gating or config injection. Accept the portability tradeoff deliberately. Document the platform requirement in the compatibility field so anyone picking up the skill knows what they need.