docs: add docs/plugins/agentskills-compat.md
This commit is contained in:
molecule-ai[bot]
GitHub
parent
52a36a06f5
commit
6aece0f6de
182
content/docs/plugins/agentskills-compat.md
Normal file
182
content/docs/plugins/agentskills-compat.md
Normal file
@ -0,0 +1,182 @@
|
||||
# Molecule AI plugins and the agentskills.io standard
|
||||
|
||||
> **TL;DR** — every skill inside a Molecule AI plugin is a spec-compliant
|
||||
> [agentskills.io](https://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](https://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:
|
||||
|
||||
```yaml
|
||||
# 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](../../workspace/plugins_registry/__init__.py)
|
||||
for the resolution order.
|
||||
|
||||
## Validator
|
||||
|
||||
Run before publishing a plugin:
|
||||
|
||||
```bash
|
||||
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](https://github.com/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](https://github.com/Molecule-AI/molecule-ai-plugin-ecc/pull/2)
|
||||
- [molecule-ai-plugin-superpowers#2](https://github.com/Molecule-AI/molecule-ai-plugin-superpowers/pull/2)
|
||||
- [molecule-ai-plugin-molecule-dev#2](https://github.com/Molecule-AI/molecule-ai-plugin-molecule-dev/pull/2)
|
||||
- [molecule-ai-plugin-molecule-skill-cron-learnings#2](https://github.com/Molecule-AI/molecule-ai-plugin-molecule-skill-cron-learnings/pull/2)
|
||||
- [molecule-ai-plugin-molecule-skill-update-docs#2](https://github.com/Molecule-AI/molecule-ai-plugin-molecule-skill-update-docs/pull/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.
|
||||
Loading…
Reference in New Issue
Block a user