Merge pull request #99 from Molecule-AI/feat/marketplace-creator-docs
docs(marketplace): tier overview + creator listing guide
This commit is contained in:
Hongming Wang
GitHub
commit
5f0871707e
166
content/docs/marketplace.mdx
Normal file
166
content/docs/marketplace.mdx
Normal file
@ -0,0 +1,166 @@
|
||||
---
|
||||
title: Marketplace
|
||||
description: A tiered library of plugins, agents, and bundles you can mount into any Molecule workspace.
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The Molecule **Marketplace** is the distribution surface for reusable agent
|
||||
infrastructure. It surfaces three tiers of artifacts — from a single MCP
|
||||
plugin to a full team topology — and the same governance, memory, and audit
|
||||
substrate runs underneath each one.
|
||||
|
||||
You browse and install via the Marketplace UI at
|
||||
[`https://moleculesai.app`](https://moleculesai.app), or pin entries from
|
||||
your `workspace.yaml` for reproducible deployments.
|
||||
|
||||
---
|
||||
|
||||
## Three Tiers
|
||||
|
||||
| Tier | Name | Granularity | Mount as |
|
||||
|------|------|-------------|----------|
|
||||
| **L1** | Plugins | A single MCP server / tool pack | Tool capability on an agent or workspace |
|
||||
| **L2** | Agents | A prebuilt single-agent skill (prompts + tools + policy) | Workspace member |
|
||||
| **L3** | Bundles | A full team topology (root + children with their own scopes) | Workspace |
|
||||
|
||||
The tier model is intentionally additive — an L3 Bundle is composed of L2
|
||||
Agents, which in turn use L1 Plugins. Forking a Bundle gives you the lineage
|
||||
to swap any constituent piece without rewiring the operating model.
|
||||
|
||||
### L1 — Plugins
|
||||
|
||||
Plugins are MCP servers or agentskills.io packs. Examples:
|
||||
|
||||
- `postgres` — read/write Postgres with role-scoped credentials
|
||||
- `slack` — post and search Slack with workspace-scoped tokens
|
||||
- `linear` — create / triage / comment on Linear issues
|
||||
- `gh-actions` — query and dispatch GitHub Actions runs
|
||||
- `sentry` — read incident timeline, ack alerts
|
||||
|
||||
Plugins follow the [two-axis source/shape model](/docs/plugins) and install
|
||||
from either a curated `local://` source or a pinned `github://owner/repo#tag`.
|
||||
|
||||
### L2 — Agents
|
||||
|
||||
Agents are single-purpose skills mounted as a workspace member. They ship with:
|
||||
|
||||
- A **system prompt** baked in
|
||||
- A **tool manifest** specifying which L1 plugins they require
|
||||
- A **policy** declaring scope reads/writes and approval requirements
|
||||
|
||||
Examples:
|
||||
|
||||
- `code-reviewer` — five-axis review, posts inline comments via `gh-actions`
|
||||
- `oncall-triager` — reads Sentry, drafts a runbook step, requests approval before paging
|
||||
- `churn-analyst` — periodic Postgres + Stripe rollup, posts a weekly Slack summary
|
||||
|
||||
Mount an agent via the workspace UI or `workspace.yaml`:
|
||||
|
||||
```yaml
|
||||
members:
|
||||
- kind: agent
|
||||
source: marketplace://l2/code-reviewer
|
||||
version: ^1.2.0
|
||||
scopes:
|
||||
- read: pull_requests
|
||||
- write: pull_request_comments
|
||||
```
|
||||
|
||||
### L3 — Bundles
|
||||
|
||||
Bundles are complete team topologies. A bundle ships:
|
||||
|
||||
- A **root agent** that coordinates the team
|
||||
- One or more **child agents**, each with its own scope, memory, and tool
|
||||
list
|
||||
- A **policy graph** declaring which scopes the root can write through and
|
||||
which approvals route to humans
|
||||
|
||||
Examples:
|
||||
|
||||
- `growth-team` — root strategist + content-writer + analytics-rollup +
|
||||
experiment-designer
|
||||
- `platform-ops` — root SRE + on-call triager + change-reviewer +
|
||||
incident-scribe
|
||||
- `revenue-pod` — root commercial lead + churn-analyst + cs-summarizer +
|
||||
expansion-prospector
|
||||
|
||||
Mount a bundle as a workspace:
|
||||
|
||||
```yaml
|
||||
workspace:
|
||||
bundle: marketplace://l3/platform-ops
|
||||
bundle_version: ^0.4.0
|
||||
overrides:
|
||||
members:
|
||||
change-reviewer:
|
||||
scopes:
|
||||
- read: ["github:Molecule-AI/*", "linear:eng"]
|
||||
```
|
||||
|
||||
Forking is encouraged — the bundle author publishes the operating model;
|
||||
your team tunes it for your processes without rebuilding the substrate.
|
||||
|
||||
---
|
||||
|
||||
## Trust Tiers
|
||||
|
||||
Every Marketplace entry carries a **trust tier** that signals review depth
|
||||
and supply-chain provenance:
|
||||
|
||||
| Trust | Vetting | Provenance |
|
||||
|-------|---------|------------|
|
||||
| **Verified** | Reviewed by Molecule for safety, prompt-injection resistance, and policy correctness | Published from a Molecule-controlled identity |
|
||||
| **Partner** | Reviewed by a Marketplace partner; carries the partner's identity badge | Published from a verified partner account |
|
||||
| **Community** | Self-published; static analysis + sandbox runtime; no human review | Pinned to a specific commit SHA |
|
||||
|
||||
The trust tier is shown on every listing card and gated by enterprise
|
||||
policy: organizations on the Enterprise plan can restrict installs to
|
||||
Verified-only via `policy.marketplace.min_trust = verified`.
|
||||
|
||||
---
|
||||
|
||||
## Installing from the Marketplace
|
||||
|
||||
Browse listings at [`https://moleculesai.app`](https://moleculesai.app).
|
||||
Each card shows tier (L1/L2/L3), trust badge, runtime compatibility, and
|
||||
required scopes. The "Install" flow:
|
||||
|
||||
1. Picks a workspace (or creates a new one) to mount into.
|
||||
2. Surfaces required scopes for review and approval.
|
||||
3. Pins to a specific version (semver range, exact tag, or commit SHA).
|
||||
4. Writes the entry into your `workspace.yaml` and triggers a workspace
|
||||
redeploy.
|
||||
|
||||
You can also install non-interactively:
|
||||
|
||||
```bash
|
||||
curl -X POST https://app.moleculesai.app/cp/orgs/$ORG/marketplace/install \
|
||||
-H "Authorization: Bearer $CP_ADMIN_API_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"tier": "l2",
|
||||
"slug": "code-reviewer",
|
||||
"version": "^1.2.0",
|
||||
"workspace_id": "ws_abc123"
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Listing on the Marketplace
|
||||
|
||||
If you have built reusable agent infrastructure — a plugin, agent, or
|
||||
bundle — you can list it on the Marketplace and reach every Molecule
|
||||
organization. See [Listing on the Marketplace](/docs/marketplace/creators)
|
||||
for the full builder workflow.
|
||||
|
||||
---
|
||||
|
||||
## See also
|
||||
|
||||
- [Plugins](/docs/plugins) — L1 source/shape model and install mechanics
|
||||
- [External Agents](/docs/external-agents) — bringing a non-Molecule agent runtime
|
||||
- [Workspace Configuration](/docs/workspace-config) — `workspace.yaml` reference
|
||||
- [Listing on the Marketplace](/docs/marketplace/creators) — builder workflow
|
||||
164
content/docs/marketplace/creators.mdx
Normal file
164
content/docs/marketplace/creators.mdx
Normal file
@ -0,0 +1,164 @@
|
||||
---
|
||||
title: Listing on the Marketplace
|
||||
description: How builders ship plugins, agents, and bundles to every Molecule organization.
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The Marketplace is open to external builders. If you have authored reusable
|
||||
agent infrastructure — an MCP plugin, a single-agent skill, or a full team
|
||||
bundle — you can list it and reach every Molecule organization. We handle
|
||||
distribution, billing, and policy; you keep the IP and the upgrade cadence.
|
||||
|
||||
This page walks through the three-step workflow: **Build · List · Earn**.
|
||||
|
||||
---
|
||||
|
||||
## 1. Build
|
||||
|
||||
You author your artifact against the open Molecule SDK. The same primitives
|
||||
we use internally are available to you:
|
||||
|
||||
- **Workspace** — the durable boundary for memory, members, and policy
|
||||
- **A2A** — agent-to-agent messaging, used to talk to runtimes you don't
|
||||
own (LangGraph, CrewAI, etc.)
|
||||
- **Memory scopes** — hierarchical, governance-aware persistence
|
||||
- **Audit** — every action is captured at the orchestration layer
|
||||
|
||||
Pick the tier that matches your artifact's granularity:
|
||||
|
||||
### L1 — Plugins
|
||||
|
||||
A plugin is an MCP server (or an agentskills.io pack). The
|
||||
[two-axis source/shape model](/docs/plugins) describes how the workspace
|
||||
runtime loads it. Authoring requirements:
|
||||
|
||||
- A `plugin.yaml` manifest declaring tools, required scopes, and runtime
|
||||
compatibility.
|
||||
- A README documenting the tool surface and side effects.
|
||||
- For MCP plugins: an HTTP or stdio MCP server pinned to a tagged commit.
|
||||
|
||||
A reference plugin lives at
|
||||
[`Molecule-AI/molecule-ai-plugin-template`](https://github.com/Molecule-AI/molecule-ai-plugin-template).
|
||||
|
||||
### L2 — Agents
|
||||
|
||||
An agent is a single workspace member with a baked-in prompt + tools +
|
||||
policy. Authoring requirements:
|
||||
|
||||
- An `agent.yaml` manifest declaring system prompt, required L1 plugins,
|
||||
scope reads/writes, and approval triggers.
|
||||
- A `prompts/` directory with the system prompt and any reusable templates.
|
||||
- A `tests/` directory exercising the prompt against canned scenarios.
|
||||
|
||||
Reference: [`Molecule-AI/molecule-ai-agent-template`](https://github.com/Molecule-AI/molecule-ai-agent-template).
|
||||
|
||||
### L3 — Bundles
|
||||
|
||||
A bundle ships a complete team topology — a root agent plus children, each
|
||||
with its own scope and memory. Authoring requirements:
|
||||
|
||||
- A `bundle.yaml` declaring members, their scopes, and the policy graph
|
||||
(which scopes the root can write through, which approvals route to
|
||||
humans).
|
||||
- A `members/` directory containing member-specific overrides if any
|
||||
member is a fork of an L2 agent.
|
||||
- A `topology.svg` diagram (auto-rendered from `bundle.yaml`, but you can
|
||||
override).
|
||||
|
||||
Reference: [`Molecule-AI/molecule-ai-bundle-template`](https://github.com/Molecule-AI/molecule-ai-bundle-template).
|
||||
|
||||
---
|
||||
|
||||
## 2. List
|
||||
|
||||
Submit through the **Creator Portal** at
|
||||
[`https://moleculesai.app/creators`](https://moleculesai.app/creators).
|
||||
The submission flow:
|
||||
|
||||
1. **Connect** — link the GitHub repository hosting your artifact. We pull
|
||||
from tagged releases; we never re-tag or modify your code.
|
||||
2. **Manifest check** — we validate `plugin.yaml` / `agent.yaml` /
|
||||
`bundle.yaml` against the schema for your tier and surface any gaps.
|
||||
3. **Static analysis** — credential-shape scan, prompt-injection-pattern
|
||||
scan, and dependency vulnerability check on every tagged release.
|
||||
4. **Sandbox boot** — your artifact is mounted into a throwaway workspace
|
||||
to verify it boots, declares its scopes correctly, and surfaces a
|
||||
reasonable error path.
|
||||
5. **Trust tier** — every artifact starts at **Community**. Apply for
|
||||
**Partner** or **Verified** review once you have a couple of releases
|
||||
under your belt.
|
||||
|
||||
Pricing is configured at submission:
|
||||
|
||||
- **Free** — no charge to install.
|
||||
- **Per-seat** — a flat monthly amount per workspace member that mounts
|
||||
the artifact.
|
||||
- **Per-use** — metered against a unit you define (token calls, runs,
|
||||
alerts handled).
|
||||
- **Hybrid** — base seat fee plus metered overages.
|
||||
|
||||
You can change pricing on subsequent releases; existing installs are
|
||||
grandfathered to the version they pinned.
|
||||
|
||||
---
|
||||
|
||||
## 3. Earn
|
||||
|
||||
Once your listing is live, you receive:
|
||||
|
||||
- **Distribution** — every Molecule organization sees your listing in the
|
||||
Marketplace UI, gated only by their policy (`min_trust`, region, etc.).
|
||||
- **Billing** — Molecule handles the charge to the installing
|
||||
organization, deducts the platform fee (15% as of writing; check the
|
||||
current rate in the Creator Portal), and pays out monthly.
|
||||
- **Audit visibility** — you see install counts, version distribution,
|
||||
and aggregated usage metrics in the Creator Portal. You do **not** see
|
||||
per-organization data.
|
||||
- **Upgrade cadence** — semver: bump tags, organizations on a `^range`
|
||||
pin pull updates on their next workspace redeploy. Major bumps require
|
||||
re-approval of any new scopes.
|
||||
|
||||
---
|
||||
|
||||
## Policy & Safety
|
||||
|
||||
By listing, you agree to:
|
||||
|
||||
- **No exfiltration** — your code does not transmit organization data
|
||||
outside the scopes it declares.
|
||||
- **Pinned releases** — every version is pinned to an immutable commit;
|
||||
retagging is not permitted.
|
||||
- **Disclose model usage** — if your agent calls an LLM API, declare the
|
||||
provider and model so enterprise plans can route through their own
|
||||
keys.
|
||||
- **Respect approval triggers** — if your `agent.yaml` declares a scope
|
||||
that requires human approval (e.g. `write: pull_request_merge`), you
|
||||
must call the approval API before acting.
|
||||
|
||||
Listings that violate these terms are de-listed; refunds for affected
|
||||
installs are paid from your account.
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
Once a listing is live, you can:
|
||||
|
||||
- Push new tagged releases — they enter the static-analysis + sandbox
|
||||
flow automatically.
|
||||
- Mark older versions as **deprecated** to nudge installs to upgrade.
|
||||
- File **security advisories** that surface to every organization on a
|
||||
vulnerable pinned version.
|
||||
- Yank a release in the rare case of a critical bug; organizations
|
||||
pinned to the yanked tag are notified and offered the next safe version.
|
||||
|
||||
---
|
||||
|
||||
## See also
|
||||
|
||||
- [Marketplace](/docs/marketplace) — tier model and installation overview
|
||||
- [Plugins](/docs/plugins) — L1 plugin source/shape mechanics
|
||||
- [Workspace Configuration](/docs/workspace-config) — pinning marketplace
|
||||
entries in `workspace.yaml`
|
||||
- [Security » OWASP Agentic Top 10](/docs/security/owasp-agentic-top-10) — supply-chain considerations relevant to bundle authors
|
||||
@ -20,6 +20,9 @@
|
||||
"self-hosting/admin-token",
|
||||
"observability",
|
||||
"troubleshooting",
|
||||
"---Marketplace---",
|
||||
"marketplace",
|
||||
"marketplace/creators",
|
||||
"---Security---",
|
||||
"security/index",
|
||||
"security/safe-mcp-advisory",
|
||||
|
||||
Loading…
Reference in New Issue
Block a user