align plugin docs, skills, and validator guidance
Keep plugin terminology, requirements, and cross-references consistent across the canonical docs, agent skills, and in-repo validator tooling. Clarify local-only vs Plugin Index expectations, add missing router/developer-doc references, and update review/validator wording so community plugins require a name while local-only plugins are not treated as hard failures for omitting it.
Alessandro committed
Mar 21, 2026 at 13:53 UTC
6adcefe26e22515a88837a706e51c8fa55976bae
12 files changed
+48
-25
docs/agents/AGENTS.plugins.md
+11
-5
@@ -27,8 +27,8 @@ usr/plugins/<plugin_name>/
27
├── execute.py # Optional: user-triggered plugin script
28
├── hooks.py # Optional: runtime hook functions callable by the framework
29
├── default_config.yaml # Optional: fallback settings defaults
30
-├── README.md # Optional: shown in Plugin List UI
31
-├── LICENSE # Optional: shown in Plugin List UI
30
+├── README.md # Optional locally; strongly recommended for community plugins (Plugin Hub)
31
+├── LICENSE # Optional locally (shown in Plugin List UI when present); required at repo root for Plugin Index submission
32
├── conf/
33
│ └── model_providers.yaml # Optional: add or override model providers
34
├── api/ # API handlers (ApiHandler subclasses)
@@ -263,7 +263,7 @@ screenshots: # optional, up to 5 full image URLs
263
- https://raw.githubusercontent.com/yourname/your-plugin-repo/main/docs/screen.png
264
```
265
266
-The index manifest is named `index.yaml` (not `plugin.yaml`). Required fields: `title`, `description`, `github`. Optional: `tags` (up to 5), `screenshots` (up to 5 URLs). The `github` field must point to the root of a GitHub repository that contains a runtime `plugin.yaml` at the repository root, and that `plugin.yaml` must include a `name` field matching the index folder name exactly.
266
+The index manifest is named `index.yaml` (not `plugin.yaml`). Required fields: `title`, `description`, `github`. Optional: `tags` (up to 5), `screenshots` (up to 5 URLs). The `github` field must point to the root of a GitHub repository that contains a runtime `plugin.yaml` at the repository root, and that `plugin.yaml` must include a `name` field matching the index folder name exactly. That repository must also include a `LICENSE` file at its root so community users have explicit terms of use.
267
268
### Repository Structure for Community Plugins
269
@@ -274,7 +274,7 @@ your-plugin-repo/ ← GitHub repository root
274
├── plugin.yaml ← runtime manifest (title, description, version, ...)
275
├── default_config.yaml
276
├── README.md
277
-├── LICENSE
277
+├── LICENSE ← required for Plugin Index (community) plugins
278
├── api/
279
├── tools/
280
├── extensions/
@@ -297,6 +297,7 @@ Index submission rules:
297
- Folder name must exactly match the `name` field in your remote `plugin.yaml`
298
- Folders starting with `_` are reserved for internal use
299
- `github` must point to a public repo that contains `plugin.yaml` at its root with a matching `name` field
300
+- The same repo must contain `LICENSE` at its root (community contribution requirement)
301
- `title` max 50 characters, `description` max 500 characters
302
- `index.yaml` total max 2000 characters
303
- `tags`: optional, up to 5, use recommended tags from https://github.com/agent0ai/a0-plugins/blob/main/TAGS.md
@@ -313,4 +314,9 @@ Both routes surface Plugin Index entries inside Agent Zero. The Plugin Hub suppo
314
315
---
316
316
-*Refer to AGENTS.md for the main framework guide.*
317
+## 9. See Also
318
+
319
+- `docs/developer/plugins.md` for the developer-facing plugin lifecycle and publishing guide
320
+- `plugins/README.md` for the bundled-vs-user plugin directory overview and quick links
321
+- `skills/a0-plugin-router/SKILL.md` for the agent-facing entry point that routes plugin tasks to the right specialist skill
322
+- `AGENTS.md` for the main framework guide
docs/developer/plugins.md
+7
-5
@@ -54,8 +54,8 @@ usr/plugins/<plugin_name>/
54
├── execute.py # optional user-triggered plugin script
55
├── hooks.py # optional runtime hook functions callable by the framework
56
├── default_config.yaml # optional defaults
57
-├── README.md # optional, shown in Plugin List UI
58
-├── LICENSE # optional, shown in Plugin List UI
57
+├── README.md # optional locally; strongly recommended for community plugins
58
+├── LICENSE # optional locally (shown in Plugin List UI when present); required at repo root for Plugin Index submission
59
├── api/ # ApiHandler implementations
60
├── tools/ # Tool implementations
61
├── helpers/ # shared Python logic
@@ -251,7 +251,7 @@ screenshots: # optional, up to 5 full image URLs
251
- https://raw.githubusercontent.com/yourname/your-plugin-repo/main/docs/screen.png
252
```
253
254
-The index manifest file is named `index.yaml` (not `plugin.yaml`). Required fields: `title`, `description`, `github`. Optional: `tags` (up to 5), `screenshots` (up to 5 URLs). The `github` URL must point to a public GitHub repository that contains a runtime `plugin.yaml` at the **repository root**, and that `plugin.yaml` must include a `name` field matching the index folder name exactly.
254
+The index manifest file is named `index.yaml` (not `plugin.yaml`). Required fields: `title`, `description`, `github`. Optional: `tags` (up to 5), `screenshots` (up to 5 URLs). The `github` URL must point to a public GitHub repository that contains a runtime `plugin.yaml` at the **repository root**, and that `plugin.yaml` must include a `name` field matching the index folder name exactly. That repository must also include a `LICENSE` file at its root (Plugin Index / community contribution requirement).
255
256
### Repository Structure for Community Plugins
257
@@ -262,7 +262,7 @@ your-plugin-repo/ ← GitHub repository root
262
├── plugin.yaml ← runtime manifest (must include name field)
263
├── default_config.yaml
264
├── README.md
265
-├── LICENSE
265
+├── LICENSE ← required for Plugin Index listings
266
├── api/
267
├── tools/
268
├── extensions/
@@ -280,6 +280,7 @@ your-plugin-repo/ ← GitHub repository root
280
Submission rules:
281
- Folder name: unique, stable, `^[a-z0-9_]+$` (lowercase, numbers, underscores — no hyphens)
282
- Folder name must exactly match the `name` field in your remote `plugin.yaml`
283
+- The GitHub repo must include `LICENSE` at its root (community contribution requirement)
284
- Folders starting with `_` are reserved for internal use
285
- `title`: max 50 characters
286
- `description`: max 500 characters
@@ -310,7 +311,8 @@ This keeps toasts and notification history consistent. See [Notifications](notif
311
## See Also
312
313
- `docs/agents/AGENTS.plugins.md` for full architecture details
313
-- `skills/a0-create-plugin/SKILL.md` for plugin authoring workflow (agent-facing)
314
+- `skills/a0-plugin-router/SKILL.md` for the primary agent-facing entry point across plugin create/review/manage/contribute/debug tasks
315
+- `skills/a0-create-plugin/SKILL.md` for direct plugin authoring workflow when the task is specifically to build or extend a plugin
316
- `plugins/README.md` for core plugin directory overview
317
318
## Frontend Extension Notes
plugins/README.md
+3
-1
@@ -14,6 +14,7 @@ For detailed guides on how to create, extend, or configure plugins, refer to:
14
- [`docs/agents/AGENTS.plugins.md`](../docs/agents/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-plugin-router/SKILL.md`](../skills/a0-plugin-router/SKILL.md): Agent-facing entry point that routes plugin tasks to the appropriate specialist skill.
18
- [`skills/a0-create-plugin/SKILL.md`](../skills/a0-create-plugin/SKILL.md): Agent-facing authoring workflow (local and community plugins).
19
20
## What a Plugin Can Provide
@@ -31,6 +32,7 @@ Plugins are automatically discovered based on the presence of a `plugin.yaml` fi
32
Every plugin requires a `plugin.yaml` at its root:
33
34
```yaml
35
+name: my_plugin # required for community plugins
36
title: My Plugin
37
description: What this plugin does.
38
version: 1.0.0
@@ -68,7 +70,7 @@ The **Plugin Index** at https://github.com/agent0ai/a0-plugins is the community-
70
71
To share a plugin with the community:
72
71
-1. Create a standalone GitHub repository with the plugin contents at the repo root. The runtime `plugin.yaml` must include a `name` field matching the intended index folder name.
73
+1. Create a standalone GitHub repository with the plugin contents at the repo root. The runtime `plugin.yaml` must include a `name` field matching the intended index folder name. Add a `LICENSE` file at the repo root (required for Plugin Index listings so users have explicit terms of use).
74
2. Fork `https://github.com/agent0ai/a0-plugins` and add a folder `plugins/<your_plugin_name>/` containing a separate index manifest named `index.yaml` (not `plugin.yaml`):
75
76
```yaml
plugins/_plugin_validator/webui/plugin-validator-checks.json
+4
-4
@@ -7,7 +7,7 @@
7
"checks": {
8
"manifest": {
9
"label": "Manifest Validation",
10
- "detail": "Validate plugin.yaml at the plugin root. Confirm it is parseable YAML, contains the required name/title/description/version fields, uses a valid plugin name matching ^[a-z0-9_]+$, keeps boolean fields typed correctly, restricts settings_sections to the documented values, and avoids unknown schema keys.",
10
+ "detail": "Validate plugin.yaml at the plugin root. Confirm it is parseable YAML, contains the required title/description/version fields (and a valid name when intended for the community index), uses a plugin name matching ^[a-z0-9_]+$ when present, keeps boolean fields typed correctly, restricts settings_sections to the documented values, and avoids unknown schema keys.",
11
"criteria": {
12
"pass": "plugin.yaml exists, parses, and matches the expected schema with no required fixes",
13
"warning": "Manifest is mostly valid but has extra keys, weak metadata, or non-blocking schema issues",
@@ -16,10 +16,10 @@
16
},
17
"structure": {
18
"label": "Structure Validation",
19
- "detail": "Inspect the directory layout and role of each top-level file or folder. Check that api/ contains Python ApiHandler files, tools/ contains Tool subclasses, extensions/ follows python/<point>/ or webui/<point>/ conventions, webui/config.html is backed by settings_sections, hooks.py exposes install when expected, execute.py follows the main()/sys.exit(main()) pattern, and the root contains only expected plugin files.",
19
+ "detail": "Inspect the directory layout and role of each top-level file or folder. Check that api/ contains Python ApiHandler files, tools/ contains Tool subclasses, extensions/ follows python/<point>/ or webui/<point>/ conventions, webui/config.html is backed by settings_sections, hooks.py exposes install when expected, execute.py follows the main()/sys.exit(main()) pattern, and the root contains only expected plugin files. Also verify a file named LICENSE exists at the plugin root (same directory as plugin.yaml). Agent Zero does not require LICENSE for loading a local plugin, but the Plugin Index requires LICENSE at the repository root for community listings; a missing LICENSE must not be rated pass for this phase.",
20
"criteria": {
21
- "pass": "Directory layout cleanly matches Agent Zero plugin conventions",
22
- "warning": "Structure mostly works but contains unusual files or minor convention drift",
21
+ "pass": "Directory layout cleanly matches Agent Zero plugin conventions and LICENSE exists at the plugin root",
22
+ "warning": "Layout mostly works but LICENSE is missing at the plugin root (required for Plugin Index submission; optional for local-only use), or there are unusual files or minor convention drift",
23
"fail": "Layout or required files clearly break plugin loading, installation, or contribution expectations"
24
}
25
},
plugins/_plugin_validator/webui/plugin-validator-guidance.md
+1
@@ -7,3 +7,4 @@
7
- Hooks runtime targeting: use `sys.executable` only for framework runtime work and `/opt/venv/bin/python` for agent-runtime installs.
8
- execute.py pattern: expose `main()` and end with `if __name__ == "__main__": sys.exit(main())`.
9
- Community contribution: plugin name must match `^[a-z0-9_]+$`, match the directory name, and stay unique in the published index.
10
+- LICENSE: a file named `LICENSE` at the plugin root is optional for local-only plugins but required at the repository root before Plugin Index submission; if missing, rate Structure Validation as warning (not pass) and state that clearly in findings.
plugins/_plugin_validator/webui/plugin-validator-prompt.md
+1
-1
@@ -20,7 +20,7 @@ Follow these steps in order:
20
21
1. Resolve the plugin root and list every file below it. Do not sample; inspect the full plugin.
22
2. Read `plugin.yaml` and record the plugin's name, title, description, and version.
23
-3. Map the directory structure and identify every top-level file or folder that affects behavior.
23
+3. Map the directory structure and identify every top-level file or folder that affects behavior. Record whether a `LICENSE` file exists at the plugin root (required for Plugin Index submission per project policy; optional for local-only plugins).
24
4. Run ONLY the selected validation phases listed below.
25
5. If a temporary clone or extracted directory was used, perform the cleanup exactly as instructed.
26
skills/a0-contribute-plugin/SKILL.md
+4
-1
@@ -52,7 +52,7 @@ The plugin must live in its **own standalone GitHub repository** with plugin con
52
your-plugin-repo/ <- GitHub repository root
53
├── plugin.yaml <- runtime manifest (REQUIRED)
54
├── README.md <- strongly recommended (shown in Plugin Hub detail view)
55
-├── LICENSE <- strongly recommended
55
+├── LICENSE <- REQUIRED for Plugin Index submission (place at repo root)
56
├── default_config.yaml <- optional
57
├── api/ <- API handlers
58
├── tools/ <- agent tools
@@ -174,6 +174,7 @@ Run these checks locally before opening the PR (mirrors what CI will verify):
174
| `github` URL | Points to existing public repo |
175
| Remote `plugin.yaml` | Exists at repo root |
176
| Remote `plugin.yaml` `name` field | Matches index folder name exactly |
177
+| Remote `LICENSE` | Exists at repo root (Plugin Index policy) |
178
| Folder name pattern | `^[a-z0-9_]+$`, no leading `_` |
179
| `github` URL uniqueness | Not already in the index for another plugin |
180
@@ -227,6 +228,8 @@ gh pr create \
228
229
## References
230
231
+- Plugin architecture: `/a0/docs/agents/AGENTS.plugins.md`
232
+- Developer lifecycle guide: `/a0/docs/developer/plugins.md`
233
- Plugin Index repo: https://github.com/agent0ai/a0-plugins
234
- Recommended tags: https://github.com/agent0ai/a0-plugins/blob/main/TAGS.md
235
- Review before contributing: read `/a0/skills/a0-review-plugin/SKILL.md`
skills/a0-create-plugin/SKILL.md
+4
-3
@@ -24,6 +24,7 @@ Primary references:
24
- /a0/docs/agents/AGENTS.components.md (Component system deep dive)
25
- /a0/docs/agents/AGENTS.modals.md (Modal system & CSS conventions)
26
- /a0/docs/agents/AGENTS.plugins.md (Extension points, plugin.yaml, settings system, Plugin Index)
27
+- /a0/docs/developer/plugins.md (Developer lifecycle and publishing)
28
29
---
30
@@ -184,8 +185,8 @@ save_plugin_config(
185
execute.py # Optional user-triggered setup, post-install, or maintenance script
186
hooks.py # Optional framework runtime hook functions
187
default_config.yaml # Optional default settings fallback
187
- README.md # Optional, shown in Plugin List UI
188
- LICENSE # Optional, shown in Plugin List UI
188
+ README.md # Optional locally; strongly recommended for community plugins
189
+ LICENSE # Optional locally (shown in Plugin List UI when present); required at repo root for Plugin Index submission
190
agents/
191
<profile>/agent.yaml # Optional plugin-distributed agent profile
192
api/ # API Handlers (ApiHandler base class)
@@ -306,7 +307,7 @@ your-plugin-repo/ ← GitHub repository root
307
├── plugin.yaml ← runtime manifest (must include name field!)
308
├── default_config.yaml
309
├── README.md
309
-├── LICENSE
310
+├── LICENSE ← required at repo root before Plugin Index submission
311
├── api/
312
├── tools/
313
├── extensions/
skills/a0-manage-plugin/SKILL.md
+1
@@ -358,6 +358,7 @@ Plugins with `always_enabled: true` in `plugin.yaml` cannot be toggled (framewor
358
## References
359
360
- Plugin architecture: `/a0/docs/agents/AGENTS.plugins.md`
361
+- Developer lifecycle guide: `/a0/docs/developer/plugins.md`
362
- Debug a broken plugin: read `/a0/skills/a0-debug-plugin/SKILL.md`
363
- Create a new plugin: read `/a0/skills/a0-create-plugin/SKILL.md`
364
- Review a plugin: read `/a0/skills/a0-review-plugin/SKILL.md`
skills/a0-plugin-router/SKILL.md
+2
@@ -79,8 +79,10 @@ always_enabled: false # forces ON, disables toggle (framework use only)
79
| `hooks.py` | Framework runtime hooks (install, cache, registration) |
80
| `execute.py` | User-triggered script (setup, maintenance, repair) |
81
| `default_config.yaml` | Settings defaults |
82
+| `README.md` | Optional locally; strongly recommended for community plugins so Plugin Hub users can inspect the plugin |
83
| `agents/<profile>/agent.yaml` | Plugin-distributed agent profiles |
84
| `conf/model_providers.yaml` | Add/override model providers |
85
+| `LICENSE` | Optional under `usr/plugins/`; required at the root of a plugin GitHub repo before submitting to the Plugin Index |
86
87
### Activation
88
skills/a0-review-plugin/SKILL.md
+6
-4
@@ -27,7 +27,7 @@ Read `usr/plugins/<name>/plugin.yaml`. Check:
27
28
- [ ] File exists at plugin root
29
- [ ] Valid YAML (parseable, mapping at top level)
30
-- [ ] `name` field present, non-empty, matches `^[a-z0-9_]+$` and matches the directory name
30
+- [ ] `name` field handling matches the intended distribution target: for community / Plugin Index plugins it must be present, non-empty, match `^[a-z0-9_]+$`, and match the directory name; for local-only plugins, a missing `name` is a WARN rather than a FAIL
31
- [ ] `title` present and non-empty
32
- [ ] `description` present and non-empty
33
- [ ] `version` present, follows semver or simple `x.y.z` format
@@ -54,10 +54,11 @@ Inspect the plugin directory layout:
54
- [ ] If `webui/config.html` exists: plugin must declare at least one `settings_sections` entry
55
- [ ] If `hooks.py` exists: warn if it does NOT contain an `install` function (common oversight)
56
- [ ] If `execute.py` exists: check it has a `main()` function and `if __name__ == "__main__": sys.exit(main())`
57
+- [ ] `LICENSE` at plugin root: Agent Zero does not require it for local plugins, but it is **required** at the repo root before submitting to the Plugin Index. If missing → **WARN** — `LICENSE absent — required for community contribution (Plugin Index); optional for local-only use`
58
- [ ] `default_config.yaml` (if present): valid YAML
59
- [ ] No unexpected top-level entries (WARN for anything outside the standard layout)
60
60
-Standard top-level layout: `plugin.yaml`, `execute.py`, `hooks.py`, `default_config.yaml`, `README.md`, `LICENSE`, `__init__.py`, `api/`, `tools/`, `extensions/`, `webui/`, `helpers/`, `prompts/`, `agents/`, `conf/`
61
+Standard top-level layout: `plugin.yaml`, `execute.py`, `hooks.py`, `default_config.yaml`, optional `README.md`, `LICENSE`, `__init__.py`, plus `api/`, `tools/`, `extensions/`, `webui/`, `helpers/`, `prompts/`, `agents/`, `conf/`
62
63
---
64
@@ -125,9 +126,9 @@ Check:
126
### Community readiness assessment
127
128
Summarize whether the plugin is ready for contribution:
128
-- READY: all FAIL items resolved, no WARN items blocking
129
+- READY: all FAIL items resolved; for Plugin Index submission, no blocking WARN items (a missing `LICENSE` is a WARN but blocks contribution readiness until fixed)
130
- NEEDS WORK: list specific FAIL items to fix
130
-- OPTIONAL IMPROVEMENTS: list WARN items
131
+- OPTIONAL IMPROVEMENTS: list non-blocking WARN items (if the user is only using the plugin locally, a missing `LICENSE` can be noted as optional)
132
133
---
134
@@ -168,5 +169,6 @@ Fix required: version missing in plugin.yaml, inline error box in webui/settings
169
170
- Detailed pattern checklists: read `checklists.md` in this skill directory
171
- Plugin architecture: `/a0/docs/agents/AGENTS.plugins.md`
172
+- Developer lifecycle guide: `/a0/docs/developer/plugins.md`
173
- Component system: `/a0/docs/agents/AGENTS.components.md`
174
- If review passes and user wants to publish: read `/a0/skills/a0-contribute-plugin/SKILL.md`
skills/a0-review-plugin/checklists.md
+4
-1
@@ -264,7 +264,7 @@ Must: return `0` on success, non-zero on failure. Print progress. Be safe to rer
264
## plugin.yaml Schema Reference
265
266
```yaml
267
-name: my_plugin # required for CI (^[a-z0-9_]+$, must match dir name)
267
+name: my_plugin # required for community index (^[a-z0-9_]+$, must match dir name)
268
title: My Plugin # required, UI display name
269
description: What it does. # required
270
version: 1.0.0 # required
@@ -290,6 +290,9 @@ When submitting to https://github.com/agent0ai/a0-plugins, CI validates:
290
- Must exist at repo root
291
- Must contain `name` field matching the index folder name exactly
292
293
+**`LICENSE`** (your plugin's own repo):
294
+- Must exist at repo root for Plugin Index / community listings (policy; same terms users expect from any open repo)
295
+
296
**Folder name**:
297
- Pattern: `^[a-z0-9_]+$` (underscores, no hyphens)
298
- Must not start with `_`