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.

MCP-server plugins (the plugin declaration is the SSOT)

A plugin can also carry an MCP server rather than (or alongside) skills and rules. This is how privileged capabilities like the management / platform MCP reach an agent — see rfc-platform-mcp-as-plugin.md.

The model is the same two-layer split, applied to MCP:

• The plugin declaration is the single source of truth. An agent's MCP servers come from the plugins it declares (config.yaml: plugins:), not from a separate, hand-maintained mcp_servers: list. There is one place an MCP capability is named: the plugin.

• The plugin ships a runtime-agnostic MCP descriptor — the logical server definition (command/args/env, with secrets referenced, never embedded), independent of any one runtime's config file format.

• A per-runtime shape adapter renders that descriptor into the runtime's native MCP config. Each runtime reads MCP servers from a different place, so the adapter writes the descriptor into the right shape for the active runtime:

  Runtime	Native MCP config the adapter renders into
  claude-code	.claude/settings.json (mcpServers block)
  codex	~/.codex/config.toml
  gemini	~/.gemini/settings.json
  hermes	platforms.* config stanza

  Because the descriptor is runtime-agnostic and the adapter is per-runtime, the same MCP plugin works across runtimes — the agent is runtime-switchable, and the plugin declaration doesn't change when the runtime does.

The exact adapter API (class names, function signatures, the registry resolution order) is owned by the workspace runtime and is being finalized there — see the runtime implementation rather than pinning specifics here.

Privileged MCP plugins (e.g. the org-admin management MCP) are entitlement-gated: installable only on the org-root kind=platform concierge, enforced server-side. See rfc-platform-mcp-as-plugin.md §4.

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.