molecule-core/docs/plugins/agentskills-compat.md

Molecule AI plugins and the agentskills.io standard

TL;DR — every skill inside a Molecule AI plugin is a spec-compliant agentskills.io skill, which means the same skill directory is installable in Claude Code, Cursor, GitHub Copilot, VS Code, OpenAI Codex, Gemini CLI, Amp, OpenCode, OpenHands, Letta, Goose, Roo Code, Kiro, Factory, Ona, Junie, and ~20 other agent products that ship the standard today. Molecule AI adds a plugin superset on top: a bundle of skills + rules + per-runtime adapters, so the same plugin can orchestrate across a team of agents running on different LLM runtimes.

The two layers

plugins/my-plugin/                        ← Molecule AI bundle (our layer)
├── plugin.yaml                           ← Molecule AI manifest: name, version,
│                                            runtimes, adapters, description
├── rules/*.md                            ← Molecule AI-only: always-on prose
│                                            appended to the runtime memory file
├── skills/                               ← agentskills.io layer starts here
│   ├── <skill-name-1>/
│   │   ├── SKILL.md                      ← agentskills spec: frontmatter + body
│   │   ├── scripts/                      ← optional, executable code
│   │   ├── references/                   ← optional, deep-dive docs
│   │   └── assets/                       ← optional, templates/data
│   └── <skill-name-2>/
│       └── SKILL.md
└── adapters/                             ← Molecule AI-only: per-runtime installers
    ├── claude_code.py
    └── deepagents.py

The boundary is clean:

• Everything under skills/<name>/ follows the spec. A skill-aware tool that doesn't know what Molecule AI is can consume it as-is.
• Everything above skills/ is our superset — bundle metadata, cross-runtime install logic, always-on rules.

What the spec defines (and what we follow exactly)

Per agentskills.io/specification:

Spec requirement	How Molecule AI enforces it
Skill is a directory with SKILL.md at the root	skills/<name>/SKILL.md
Directory name matches frontmatter name	Enforced by molecule_plugin validate
name: 1–64 chars, lowercase + hyphens, no consecutive or edge hyphens	Regex-validated
description: 1–1024 chars, covers what+when	Length-validated
license, compatibility, metadata, allowed-tools optional	Passed through unchanged
scripts/, references/, assets/ optional dirs	Skill loader reads all three
Progressive disclosure (metadata → body → sub-files)	Claude Code reads it natively; other runtimes load via plugin adaptor

Where we extend the spec (bundle layer)

The spec doesn't address bundling, cross-runtime installation, or always-on rules. That's what plugin.yaml adds:

# plugins/my-plugin/plugin.yaml
name: my-plugin
version: 1.0.0
description: Bundle of related skills + rules for <use case>.
author: your-name
tags: [example]

# Declared supported workspace runtimes — each must have a matching
# adapters/<runtime>.py file, or the install falls through to raw-drop.
runtimes:
  - claude_code
  - deepagents

# Optional — these are document hints, not enforced by the spec.
# The skills list is informational; the skill loader discovers everything
# under skills/ regardless.
skills:
  - my-skill-a
  - my-skill-b

# Optional — always-on markdown files appended to the runtime memory file
# (CLAUDE.md on Claude Code and DeepAgents). The spec has no always-on tier.
rules:
  - rules/conventions.md

Rules vs skills

• A skill is activated on demand — the agent reads its name and description at startup, then loads the body when the task matches.
• A rule is always-on — its text is appended to the runtime's memory file (CLAUDE.md) so the agent sees it on every turn.

Rules are a Molecule AI-specific extension. If we ever need to represent a rule as a spec-compliant skill (e.g. for distribution to a non-Molecule AI tool), write it as a skill whose description explicitly says "apply continuously in this codebase" — the tool will decide whether to honor it.

Per-runtime adapters

The spec leaves install semantics to the host tool. Molecule AI's plugin adapters (plugins/<name>/adapters/<runtime>.py) bridge the gap for runtimes that don't read SKILL.md natively. For most plugins the built-in AgentskillsAdaptor covers the common shape (copy skills to /configs/skills/, append rules to CLAUDE.md). See plugins_registry for the resolution order.

Validator

Run before publishing a plugin:

python -m molecule_plugin validate plugins/my-plugin

Checks:

1. plugin.yaml parses and declares known runtimes.
2. Every skills/<name>/SKILL.md:
   • has valid frontmatter
   • name matches the directory name
   • name matches the spec regex (lowercase, hyphens, length)
   • description is 1–1024 chars
   • optional fields (license, compatibility, metadata, allowed-tools) conform to spec types

CI runs this against every first-party plugin on every PR, so spec drift is caught before merge.

Publishing a skill to agentskills-compatible tools

Any skills/<name>/ directory from a Molecule AI plugin is a valid standalone skill. To publish it for Cursor / Codex / Goose / etc. users:

1. Copy plugins/my-plugin/skills/<name>/ into a new repo.
2. Validate: python -m molecule_plugin validate . (or skills-ref validate from the upstream agentskills/agentskills repo).
3. Publish the repo; users install according to their tool's docs.

The skill will use default activation semantics in each tool. Molecule AI's plugin bundle (runtimes, adapters, rules) is not needed — it only matters if the skill is installed inside Molecule AI.

Hermes runtime compatibility (issue #852)

As of 2026-04-18, hermes has been added to the runtimes: field in the five SKILL.md-only first-party plugins. agentskills.io v0.8.0 confirmed that SKILL.md-only plugins are natively hermes-compatible via raw-drop (no adapter file required). Hook-based plugins remain claude_code-only — they rely on harness-level hooks that hermes does not expose.

Plugin	Before	After
ecc	[claude_code, deepagents]	[claude_code, deepagents, hermes]
superpowers	[claude_code, deepagents]	[claude_code, deepagents, hermes]
molecule-dev	[claude_code, deepagents]	[claude_code, deepagents, hermes]
molecule-skill-cron-learnings	[claude_code]	[claude_code, hermes]
molecule-skill-update-docs	[claude_code]	[claude_code, hermes]

Companion PRs:

• molecule-ai-plugin-ecc#2
• molecule-ai-plugin-superpowers#2
• molecule-ai-plugin-molecule-dev#2
• molecule-ai-plugin-molecule-skill-cron-learnings#2
• molecule-ai-plugin-molecule-skill-update-docs#2

Security note: Security Auditor was offline at time of change. Self-assessed as non-security-impacting — adding hermes to a string list in plugin.yaml creates no new tool surface or execution path.

Why this matters strategically

• Zero-cost distribution. Every skill we ship to Molecule AI users is automatically installable in ~35 other agent products, no rewrite.
• We're visible in the spec ecosystem. Our plugin directory becomes discoverable alongside Anthropic's own example skills. If the spec adds new fields, we inherit them for free.
• Our moat stays intact. Multi-agent orchestration, A2A, per-runtime adapters, and the visual canvas — none of this is in scope for the spec and is unlikely to be. That's where Molecule AI differentiates.