update docs for index repo
Alessandro committed
Feb 25, 2026 at 13:37 UTC
777901744cfd6d61dda4d7fa13f8f8b4c4a11824
4 files changed
+320
-37
AGENTS.plugins.md
+90
-4
@@ -23,7 +23,10 @@ Each plugin lives in usr/plugins/<plugin_name>/.
23
24
```text
25
usr/plugins/<plugin_name>/
26
-├── plugin.yaml # Required: Name, version, settings + activation metadata
26
+├── plugin.yaml # Required: Title, version, settings + activation metadata
27
+├── default_config.yaml # Optional: fallback settings defaults
28
+├── README.md # Optional: shown in Plugin List UI
29
+├── LICENSE # Optional: shown in Plugin List UI
30
├── api/ # API handlers (ApiHandler subclasses)
31
├── tools/ # Agent tools (Tool subclasses)
32
├── helpers/ # Shared Python logic
@@ -37,7 +40,10 @@ usr/plugins/<plugin_name>/
40
└── ... # Full plugin pages/components
41
```
42
40
-### plugin.yaml format
43
+### plugin.yaml (runtime manifest)
44
+
45
+This is the manifest file that lives inside your plugin directory and drives runtime behavior. It is distinct from the index manifest used when publishing to the Plugin Index (see Section 7).
46
+
47
```yaml
48
title: My Plugin
49
description: What this plugin does.
@@ -49,7 +55,15 @@ per_agent_config: false
55
# Optional: lock plugin permanently ON in UI/back-end
56
always_enabled: false
57
```
52
-settings_sections values: agent, external, mcp, developer, backup.
58
+
59
+Field reference:
60
+- `title`: UI display name
61
+- `description`: Short plugin summary
62
+- `version`: Plugin version string
63
+- `settings_sections`: Which Settings tabs show a subsection for this plugin. Valid values: `agent`, `external`, `mcp`, `developer`, `backup`. Use `[]` for no subsection.
64
+- `per_project_config`: Enables project-scoped settings and toggle rules
65
+- `per_agent_config`: Enables agent-profile-scoped settings and toggle rules
66
+- `always_enabled`: Forces ON and disables toggle controls in the UI (reserved for framework use)
67
68
---
69
@@ -96,7 +110,79 @@ Place *.js files in extensions/webui/<extension_point>/ and export a default asy
110
|---|---|
111
| GET /plugins/<name>/<path> | Serve static assets |
112
| POST /api/plugins/<name>/<handler> | Call plugin API |
99
-| POST /api/plugins | Management (actions: get_config, save_config, list_configs, delete_config, toggle_plugin) |
113
+| POST /api/plugins | Management (actions: get_config, save_config, list_configs, delete_config, toggle_plugin, get_doc) |
114
+
115
+---
116
+
117
+## 7. Plugin Index & Community Sharing
118
+
119
+The **Plugin Index** is a community-maintained repository at https://github.com/agent0ai/a0-plugins that lists plugins available to the Agent Zero community. Plugins listed there can be discovered and installed by other users.
120
+
121
+### Two Distinct plugin.yaml Files
122
+
123
+There are two completely different `plugin.yaml` schemas used at different stages. They must not be confused:
124
+
125
+**Runtime manifest** (inside your plugin repo/directory, drives Agent Zero behavior):
126
+```yaml
127
+title: My Plugin
128
+description: What this plugin does.
129
+version: 1.0.0
130
+settings_sections:
131
+ - agent
132
+per_project_config: false
133
+per_agent_config: false
134
+always_enabled: false
135
+```
136
+
137
+**Index manifest** (submitted to the `a0-plugins` repo under `plugins/<your-plugin-name>/`, drives discoverability only):
138
+```yaml
139
+title: My Plugin
140
+description: What this plugin does.
141
+github: https://github.com/yourname/your-plugin-repo
142
+tags:
143
+ - tools
144
+ - example
145
+```
146
+
147
+The index manifest contains only four fields (`title`, `description`, `github`, `tags`) and must not include runtime fields. The `github` field must point to the root of a GitHub repository that itself contains a runtime `plugin.yaml` at the repository root.
148
+
149
+### Repository Structure for Community Plugins
150
+
151
+When creating a plugin intended for the community, the plugin should be a standalone GitHub repository where the plugin directory contents live at the repo root:
152
+
153
+```text
154
+your-plugin-repo/ ← GitHub repository root
155
+├── plugin.yaml ← runtime manifest (title, description, version, ...)
156
+├── default_config.yaml
157
+├── README.md
158
+├── LICENSE
159
+├── api/
160
+├── tools/
161
+├── extensions/
162
+└── webui/
163
+```
164
+
165
+Users install it locally by cloning (or downloading) the repo contents into `/a0/usr/plugins/<plugin_name>/`.
166
+
167
+### Submitting to the Plugin Index
168
+
169
+1. Create a GitHub repository for your plugin with the runtime `plugin.yaml` at the repo root.
170
+2. Fork `https://github.com/agent0ai/a0-plugins`.
171
+3. Create a folder `plugins/<your-plugin-name>/` containing only an index `plugin.yaml` (and optionally a square thumbnail image ≤ 20 KB).
172
+4. Open a Pull Request with exactly one new plugin folder.
173
+5. CI validates the submission automatically. A maintainer reviews and merges.
174
+
175
+Index submission rules:
176
+- One plugin per PR
177
+- Folder name must be unique, stable, lowercase, kebab-case
178
+- Folders starting with `_` are reserved for internal use
179
+- `github` must point to a public repo that contains `plugin.yaml` at its root
180
+- `title` max 50 characters, `description` max 500 characters
181
+- `tags`: optional, up to 5, use recommended tags from https://github.com/agent0ai/a0-plugins/blob/main/TAGS.md
182
+
183
+### Plugin Marketplace (Coming Soon)
184
+
185
+A built-in **Plugin Marketplace** plugin (always active) will allow users to browse the Plugin Index and install or update community plugins directly from the Agent Zero UI. This section will be updated once the marketplace plugin is released.
186
187
---
188
docs/developer/plugins.md
+73
-6
@@ -1,6 +1,6 @@
1
# Plugins
2
3
-This page documents the current Agent Zero plugin system, including manifest format, discovery rules, scoped configuration, and activation behavior.
3
+This page documents the current Agent Zero plugin system, including manifest format, discovery rules, scoped configuration, activation behavior, and how to share a plugin with the community.
4
5
## Overview
6
@@ -21,7 +21,7 @@ On name collisions, user plugins take precedence.
21
22
## Manifest (`plugin.yaml`)
23
24
-Every plugin must contain `plugin.yaml`:
24
+Every plugin must contain `plugin.yaml`. This is the **runtime manifest** — it drives Agent Zero behavior. It is distinct from the index manifest used when publishing to the Plugin Index (see [Publishing to the Plugin Index](#publishing-to-the-plugin-index) below).
25
26
```yaml
27
title: My Plugin
@@ -36,7 +36,7 @@ always_enabled: false
36
37
Field reference:
38
39
-- `name`: UI display name
39
+- `title`: UI display name
40
- `description`: short plugin summary
41
- `version`: plugin version string
42
- `settings_sections`: where plugin settings appear (`agent`, `external`, `mcp`, `developer`, `backup`)
@@ -50,6 +50,8 @@ Field reference:
50
usr/plugins/<plugin_name>/
51
├── plugin.yaml
52
├── default_config.yaml # optional defaults
53
+├── README.md # optional, shown in Plugin List UI
54
+├── LICENSE # optional, shown in Plugin List UI
55
├── api/ # ApiHandler implementations
56
├── tools/ # Tool implementations
57
├── helpers/ # shared Python logic
@@ -118,12 +120,77 @@ Supported actions:
120
- `list_configs`
121
- `delete_config`
122
- `toggle_plugin`
123
+- `get_doc` (fetches README.md or LICENSE for display in the UI)
124
122
-## Migration Notes
125
+## Publishing to the Plugin Index
126
124
-Current plugin format is YAML-based (`plugin.yaml`, `default_config.yaml`, `agent.yaml` for agent profiles). Legacy JSON manifests should be migrated.
127
+The **Plugin Index** is a community-maintained repository at https://github.com/agent0ai/a0-plugins. Plugins listed there are discoverable by all Agent Zero users.
128
+
129
+### Two Distinct plugin.yaml Files
130
+
131
+There are two completely different `plugin.yaml` schemas — they must not be confused:
132
+
133
+**Runtime manifest** (inside your plugin's own repo, drives Agent Zero behavior):
134
+```yaml
135
+title: My Plugin
136
+description: What this plugin does.
137
+version: 1.0.0
138
+settings_sections:
139
+ - agent
140
+per_project_config: false
141
+per_agent_config: false
142
+always_enabled: false
143
+```
144
+
145
+**Index manifest** (submitted to `a0-plugins` under `plugins/<your-plugin-name>/`, drives discoverability only):
146
+```yaml
147
+title: My Plugin
148
+description: What this plugin does.
149
+github: https://github.com/yourname/your-plugin-repo
150
+tags:
151
+ - tools
152
+ - example
153
+```
154
+
155
+The index manifest has only four fields (`title`, `description`, `github`, `tags`). The `github` URL must point to a public GitHub repository that contains a runtime `plugin.yaml` at the **repository root**.
156
+
157
+### Repository Structure for Community Plugins
158
+
159
+Plugin repos should expose the plugin contents at the repo root, so they can be cloned directly into `usr/plugins/<name>/`:
160
+
161
+```text
162
+your-plugin-repo/ ← GitHub repository root
163
+├── plugin.yaml ← runtime manifest
164
+├── default_config.yaml
165
+├── README.md
166
+├── LICENSE
167
+├── api/
168
+├── tools/
169
+├── extensions/
170
+└── webui/
171
+```
172
+
173
+### Submission Process
174
+
175
+1. Create a GitHub repository with the runtime `plugin.yaml` at the repo root.
176
+2. Fork `https://github.com/agent0ai/a0-plugins`.
177
+3. Add `plugins/<your-plugin-name>/plugin.yaml` (index manifest) to your fork, and optionally a square thumbnail image (≤ 20 KB, named `thumbnail.png|jpg|webp`).
178
+4. Open a Pull Request. One PR must add exactly one new plugin folder.
179
+5. CI validates automatically. A maintainer reviews and merges.
180
+
181
+Submission rules:
182
+- Folder name: unique, stable, lowercase, kebab-case
183
+- Folders starting with `_` are reserved for internal use
184
+- `title`: max 50 characters
185
+- `description`: max 500 characters
186
+- `tags`: optional, up to 5, see https://github.com/agent0ai/a0-plugins/blob/main/TAGS.md
187
+
188
+### Plugin Marketplace (Coming Soon)
189
+
190
+A built-in **Plugin Marketplace** (always-active plugin) will allow users to browse the Plugin Index and install or update community plugins directly from the Agent Zero UI without leaving the application. This section will be updated once the marketplace plugin is released.
191
192
## See Also
193
194
- `AGENTS.plugins.md` for full architecture details
129
-- `skills/a0-create-plugin/SKILL.md` for plugin authoring workflow
195
+- `skills/a0-create-plugin/SKILL.md` for plugin authoring workflow (agent-facing)
196
+- `plugins/README.md` for core plugin directory overview
plugins/README.md
+56
-12
@@ -1,23 +1,67 @@
1
# Agent Zero - Core Plugins
2
3
-This directory contains the system-level plugins for Agent Zero.
3
+This directory contains the system-level plugins bundled with Agent Zero.
4
5
## Directory Structure
6
7
-- plugins/: Core system plugins (reserved for framework updates).
8
-- usr/plugins/: Recommended location for user-developed plugins.
7
+- `plugins/`: Core system plugins. Reserved for framework updates — do not place custom plugins here.
8
+- `usr/plugins/`: The correct location for all user-developed and custom plugins. This directory is gitignored.
9
10
## Documentation
11
12
-For detailed guides on how to create, extend, or configure plugins, please refer to:
12
+For detailed guides on how to create, extend, or configure plugins, refer to:
13
14
-- AGENTS.plugins.md: Full-stack plugin architecture, manifest format, and extension points.
15
-- AGENTS.md: Main framework guide and backend context overview.
14
+- [`AGENTS.plugins.md`](../AGENTS.plugins.md): Full-stack plugin architecture, manifest format, extension points, and Plugin Index submission.
15
+- [`docs/developer/plugins.md`](../docs/developer/plugins.md): Human-facing developer guide covering the full plugin lifecycle.
16
+- [`AGENTS.md`](../AGENTS.md): Main framework guide and backend context.
17
+- [`skills/a0-create-plugin/SKILL.md`](../skills/a0-create-plugin/SKILL.md): Agent-facing authoring workflow (local and community plugins).
18
17
-## Usage
19
+## What a Plugin Can Provide
20
19
-Plugins are automatically discovered based on the presence of a plugin.yaml file. Each plugin can contribute:
20
-- Backend: APIs, Tools, Helpers, and Lifecycle Extensions.
21
-- Frontend: HTML/JS UI contributions via core breakpoints.
22
-- Config: Isolated settings scoped per-project and per-agent profile.
23
-- Activation: Global/scoped ON-OFF rules via `.toggle-1` and `.toggle-0` files, including advanced per-scope switching in WebUI.
21
+Plugins are automatically discovered based on the presence of a `plugin.yaml` file. Each plugin can contribute:
22
+
23
+- **Backend**: API handlers, tools, helpers, and lifecycle extensions
24
+- **Frontend**: HTML/JS UI contributions via core extension breakpoints
25
+- **Settings**: Isolated configuration scoped per-project and per-agent profile
26
+- **Activation**: Global and scoped ON/OFF rules via `.toggle-1` and `.toggle-0` files, including advanced per-scope switching in the WebUI
27
+- **Agent profiles**: Plugin-distributed subagent definitions under `agents/<profile>/agent.yaml`
28
+
29
+## Plugin Manifest
30
+
31
+Every plugin requires a `plugin.yaml` at its root:
32
+
33
+```yaml
34
+title: My Plugin
35
+description: What this plugin does.
36
+version: 1.0.0
37
+settings_sections:
38
+ - agent
39
+per_project_config: false
40
+per_agent_config: false
41
+always_enabled: false
42
+```
43
+
44
+## Plugin Index & Community Sharing
45
+
46
+The **Plugin Index** at https://github.com/agent0ai/a0-plugins is the community-maintained registry of plugins available to all Agent Zero users.
47
+
48
+To share a plugin with the community:
49
+
50
+1. Create a standalone GitHub repository with the plugin contents at the repo root and the runtime `plugin.yaml` there.
51
+2. Fork `https://github.com/agent0ai/a0-plugins` and add a folder `plugins/<your-plugin-name>/` containing a separate index `plugin.yaml`:
52
+
53
+```yaml
54
+title: My Plugin
55
+description: What this plugin does.
56
+github: https://github.com/yourname/your-plugin-repo
57
+tags:
58
+ - tools
59
+```
60
+
61
+3. Open a Pull Request. CI validates the submission; a maintainer reviews and merges.
62
+
63
+Note: The index `plugin.yaml` is a **different schema** from the runtime manifest — it contains only `title`, `description`, `github`, and optional `tags`. Do not mix them up.
64
+
65
+## Plugin Marketplace (Coming Soon)
66
+
67
+A built-in **Plugin Marketplace** (always-active plugin) is planned and will allow users to browse the Plugin Index and install community plugins directly from the Agent Zero UI.
skills/a0-create-plugin/SKILL.md
+101
-15
@@ -6,17 +6,30 @@ description: Create, extend, or modify Agent Zero plugins. Follows strict full-s
6
# Agent Zero Plugin Development
7
8
> [!IMPORTANT]
9
-> Always create new plugins in usr/plugins/<plugin_name>/. The root /plugins directory is reserved for core system plugins.
9
+> Always create new plugins in `/a0/usr/plugins/<plugin_name>/`. The `/a0/plugins/` directory is reserved for core system plugins.
10
11
Primary references:
12
- /a0/AGENTS.md (Full-stack architecture & AgentContext)
13
- /a0/docs/agents/AGENTS.components.md (Component system deep dive)
14
- /a0/docs/agents/AGENTS.modals.md (Modal system & CSS conventions)
15
-- /a0/AGENTS.plugins.md (Extension points, plugin.yaml, settings system)
15
+- /a0/AGENTS.plugins.md (Extension points, plugin.yaml, settings system, Plugin Index)
16
+
17
+---
18
+
19
+## Step 0: Ask First — Local or Community Plugin?
20
+
21
+Before starting, ask the user one question:
22
+
23
+> "Should this plugin be **local only** (stays in your Agent Zero installation) or a **community plugin** (published to the Plugin Index so others can install it)?"
24
+
25
+- **Local plugin**: Create it in `/a0/usr/plugins/<plugin_name>/`. No repository needed. Skip to the manifest section below.
26
+- **Community plugin**: The plugin must live in its own GitHub repository (runtime manifest at the repo root), and then a separate index submission PR is made to https://github.com/agent0ai/a0-plugins. Guide the user through both steps.
27
+
28
+---
29
30
## Plugin Manifest (plugin.yaml)
31
19
-Every plugin must have a plugin.yaml or it will not be discovered:
32
+Every plugin must have a `plugin.yaml` or it will not be discovered.
33
34
```yaml
35
title: My Plugin
@@ -28,9 +41,12 @@ per_project_config: false
41
per_agent_config: false
42
```
43
31
-settings_sections controls which Settings tabs show a subsection for this plugin. Valid values: agent, external, mcp, developer, backup. Use [] for no subsection.
44
+`settings_sections` controls which Settings tabs show a subsection for this plugin. Valid values: `agent`, `external`, `mcp`, `developer`, `backup`. Use `[]` for no subsection.
45
+
46
Activation defaults to ON when no toggle rule exists. Set `per_project_config` and/or `per_agent_config` to enable advanced per-scope switching. Core system plugins may also use `always_enabled: true` to lock the plugin permanently ON (reserved for framework use).
47
48
+---
49
+
50
## Mandatory Frontend Patterns
51
52
### 1. The "Store Gate" Template
@@ -64,13 +80,15 @@ Import it in the HTML <head>:
80
</head>
81
```
82
83
+---
84
+
85
## Plugin Settings
86
69
-If your plugin needs user-configurable settings, add webui/config.html. The system detects it automatically and shows a Settings button in the relevant tabs (per settings_sections in plugin.yaml).
87
+If your plugin needs user-configurable settings, add `webui/config.html`. The system detects it automatically and shows a Settings button in the relevant tabs (per `settings_sections` in `plugin.yaml`).
88
89
### Settings modal contract
90
73
-The modal provides Project + Agent profile context selectors. Your config.html binds to $store.pluginSettings.settings:
91
+The modal provides Project + Agent profile context selectors. Your config.html binds to `$store.pluginSettings.settings`:
92
93
```html
94
<html>
@@ -89,11 +107,11 @@ The modal provides Project + Agent profile context selectors. Your config.html b
107
</html>
108
```
109
92
-The modal's Save button persists $store.pluginSettings.settings to config.json in the correct scope (project/agent/global).
110
+The modal's Save button persists `$store.pluginSettings.settings` to `config.json` in the correct scope (project/agent/global).
111
112
### Surfacing core settings (e.g. memory pattern)
113
96
-If your plugin exposes existing core settings rather than plugin-specific ones, set saveMode = 'core' so Save delegates to the core settings API:
114
+If your plugin exposes existing core settings rather than plugin-specific ones, set `saveMode = 'core'` so Save delegates to the core settings API:
115
116
```html
117
<div x-data x-init="
@@ -105,16 +123,18 @@ If your plugin exposes existing core settings rather than plugin-specific ones,
123
```
124
125
### Sidebar Button (sidebar entry point)
108
-- Extension point: sidebar-quick-actions-main-start
109
-- Class: class="config-button"
110
-- Placement: x-move-after=".config-button#dashboard"
111
-- Action: @click="openModal('/plugins/<plugin_name>/webui/my-modal.html')"
126
+- Extension point: `sidebar-quick-actions-main-start`
127
+- Class: `class="config-button"`
128
+- Placement: `x-move-after=".config-button#dashboard"`
129
+- Action: `@click="openModal('/plugins/<plugin_name>/webui/my-modal.html')"`
130
+
131
+---
132
133
## Backend API & Context
134
135
### Import Paths
116
-- Correct: from agent import AgentContext, AgentContextType
117
-- Correct: from initialize import initialize_agent
136
+- Correct: `from agent import AgentContext, AgentContextType`
137
+- Correct: `from initialize import initialize_agent`
138
139
### Sending Messages Proactively
140
```python
@@ -142,11 +162,15 @@ save_plugin_config(
162
)
163
```
164
165
+---
166
+
167
## Directory Layout
168
```
147
-usr/plugins/<name>/
169
+/a0/usr/plugins/<name>/
170
plugin.yaml # Required manifest
171
default_config.yaml # Optional default settings fallback
172
+ README.md # Optional, shown in Plugin List UI
173
+ LICENSE # Optional, shown in Plugin List UI
174
agents/
175
<profile>/agent.yaml # Optional plugin-distributed agent profile
176
api/ # API Handlers (ApiHandler base class)
@@ -159,3 +183,65 @@ usr/plugins/<name>/
183
my-modal.html # Full plugin pages
184
my-store.js # Alpine stores
185
```
186
+
187
+---
188
+
189
+## Community Plugin: GitHub Repo + Plugin Index Submission
190
+
191
+If the user chose a **community plugin**, follow these additional steps after building and testing the plugin locally.
192
+
193
+### 1. Repository Structure
194
+
195
+The plugin must live in its own GitHub repository with the plugin contents at the **repository root** (not inside a subfolder):
196
+
197
+```text
198
+your-plugin-repo/ ← GitHub repository root
199
+├── plugin.yaml ← runtime manifest (title, description, version, ...)
200
+├── default_config.yaml
201
+├── README.md
202
+├── LICENSE
203
+├── api/
204
+├── tools/
205
+├── extensions/
206
+└── webui/
207
+```
208
+
209
+Help the user create this repository and push the plugin files to it.
210
+
211
+### 2. Index manifest (different from runtime manifest)
212
+
213
+The Plugin Index (`https://github.com/agent0ai/a0-plugins`) uses a **separate, simpler `plugin.yaml`** that only describes discoverability — it is NOT the same as the runtime manifest:
214
+
215
+```yaml
216
+title: My Plugin
217
+description: What this plugin does.
218
+github: https://github.com/yourname/your-plugin-repo
219
+tags:
220
+ - tools
221
+ - example
222
+```
223
+
224
+Only four fields: `title`, `description`, `github` (required), and `tags` (optional, up to 5). See the recommended tag list at https://github.com/agent0ai/a0-plugins/blob/main/TAGS.md.
225
+
226
+### 3. Submission steps
227
+
228
+1. Fork `https://github.com/agent0ai/a0-plugins`.
229
+2. Create the folder `plugins/<your-plugin-name>/` in the fork.
230
+3. Add the index `plugin.yaml` inside it (and optionally a square thumbnail ≤ 20 KB named `thumbnail.png`, `thumbnail.jpg`, or `thumbnail.webp`).
231
+4. Open a Pull Request. The PR must add exactly one new plugin folder.
232
+5. CI will validate automatically. A maintainer reviews and merges.
233
+
234
+Submission constraints:
235
+- Folder name: unique, stable, lowercase, kebab-case
236
+- Folders starting with `_` are reserved for internal use
237
+- `title` max 50 characters, `description` max 500 characters
238
+
239
+Help the user prepare the fork, the index manifest, and draft the PR.
240
+
241
+---
242
+
243
+## Plugin Index & Marketplace
244
+
245
+The **Plugin Index** is the community hub at https://github.com/agent0ai/a0-plugins.
246
+
247
+A **Plugin Marketplace** (a built-in always-active plugin) is planned and will allow users to browse, install, and update indexed plugins directly from the Agent Zero UI. When available, this skill will be updated to guide users through marketplace-based installation as well.