Agent Zero AI framework
align plugin docs, skills, and validator guidance
Alessandro6adcefe26e22
diff --git a/docs/agents/AGENTS.plugins.md b/docs/agents/AGENTS.plugins.mdindex ab5a64732..a5a1851a4 100644--- a/docs/agents/AGENTS.plugins.md+++ b/docs/agents/AGENTS.plugins.md@@ -27,8 +27,8 @@ usr/plugins/<plugin_name>/├── execute.py # Optional: user-triggered plugin script├── hooks.py # Optional: runtime hook functions callable by the framework├── default_config.yaml # Optional: fallback settings defaults-├── README.md # Optional: shown in Plugin List UI-├── LICENSE # Optional: shown in Plugin List UI+├── README.md # Optional locally; strongly recommended for community plugins (Plugin Hub)+├── LICENSE # Optional locally (shown in Plugin List UI when present); required at repo root for Plugin Index submission├── conf/│ └── model_providers.yaml # Optional: add or override model providers├── api/ # API handlers (ApiHandler subclasses)@@ -263,7 +263,7 @@ screenshots: # optional, up to 5 full image URLs- https://raw.githubusercontent.com/yourname/your-plugin-repo/main/docs/screen.png```-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.+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.### Repository Structure for Community Plugins@@ -274,7 +274,7 @@ your-plugin-repo/ ← GitHub repository root├── plugin.yaml ← runtime manifest (title, description, version, ...)├── default_config.yaml├── README.md-├── LICENSE+├── LICENSE ← required for Plugin Index (community) plugins├── api/├── tools/├── extensions/@@ -297,6 +297,7 @@ Index submission rules:- Folder name must exactly match the `name` field in your remote `plugin.yaml`- Folders starting with `_` are reserved for internal use- `github` must point to a public repo that contains `plugin.yaml` at its root with a matching `name` field+- The same repo must contain `LICENSE` at its root (community contribution requirement)- `title` max 50 characters, `description` max 500 characters- `index.yaml` total max 2000 characters- `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----*Refer to AGENTS.md for the main framework guide.*+## 9. See Also++- `docs/developer/plugins.md` for the developer-facing plugin lifecycle and publishing guide+- `plugins/README.md` for the bundled-vs-user plugin directory overview and quick links+- `skills/a0-plugin-router/SKILL.md` for the agent-facing entry point that routes plugin tasks to the right specialist skill+- `AGENTS.md` for the main framework guidediff --git a/docs/developer/plugins.md b/docs/developer/plugins.mdindex 1b0ead1dc..b16cb5428 100644--- a/docs/developer/plugins.md+++ b/docs/developer/plugins.md@@ -54,8 +54,8 @@ usr/plugins/<plugin_name>/├── execute.py # optional user-triggered plugin script├── hooks.py # optional runtime hook functions callable by the framework├── default_config.yaml # optional defaults-├── README.md # optional, shown in Plugin List UI-├── LICENSE # optional, shown in Plugin List UI+├── README.md # optional locally; strongly recommended for community plugins+├── LICENSE # optional locally (shown in Plugin List UI when present); required at repo root for Plugin Index submission├── api/ # ApiHandler implementations├── tools/ # Tool implementations├── helpers/ # shared Python logic@@ -251,7 +251,7 @@ screenshots: # optional, up to 5 full image URLs- https://raw.githubusercontent.com/yourname/your-plugin-repo/main/docs/screen.png```-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.+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).### Repository Structure for Community Plugins@@ -262,7 +262,7 @@ your-plugin-repo/ ← GitHub repository root├── plugin.yaml ← runtime manifest (must include name field)├── default_config.yaml├── README.md-├── LICENSE+├── LICENSE ← required for Plugin Index listings├── api/├── tools/├── extensions/@@ -280,6 +280,7 @@ your-plugin-repo/ ← GitHub repository rootSubmission rules:- Folder name: unique, stable, `^[a-z0-9_]+$` (lowercase, numbers, underscores — no hyphens)- Folder name must exactly match the `name` field in your remote `plugin.yaml`+- The GitHub repo must include `LICENSE` at its root (community contribution requirement)- Folders starting with `_` are reserved for internal use- `title`: max 50 characters- `description`: max 500 characters@@ -310,7 +311,8 @@ This keeps toasts and notification history consistent. See [Notifications](notif## See Also- `docs/agents/AGENTS.plugins.md` for full architecture details-- `skills/a0-create-plugin/SKILL.md` for plugin authoring workflow (agent-facing)+- `skills/a0-plugin-router/SKILL.md` for the primary agent-facing entry point across plugin create/review/manage/contribute/debug tasks+- `skills/a0-create-plugin/SKILL.md` for direct plugin authoring workflow when the task is specifically to build or extend a plugin- `plugins/README.md` for core plugin directory overview## Frontend Extension Notesdiff --git a/plugins/README.md b/plugins/README.mdindex 90cb164b0..cd2668f22 100644--- a/plugins/README.md+++ b/plugins/README.md@@ -14,6 +14,7 @@ For detailed guides on how to create, extend, or configure plugins, refer to:- [`docs/agents/AGENTS.plugins.md`](../docs/agents/AGENTS.plugins.md): Full-stack plugin architecture, manifest format, extension points, and Plugin Index submission.- [`docs/developer/plugins.md`](../docs/developer/plugins.md): Human-facing developer guide covering the full plugin lifecycle.- [`AGENTS.md`](../AGENTS.md): Main framework guide and backend context.+- [`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.- [`skills/a0-create-plugin/SKILL.md`](../skills/a0-create-plugin/SKILL.md): Agent-facing authoring workflow (local and community plugins).## What a Plugin Can Provide@@ -31,6 +32,7 @@ Plugins are automatically discovered based on the presence of a `plugin.yaml` fiEvery plugin requires a `plugin.yaml` at its root:```yaml+name: my_plugin # required for community pluginstitle: My Plugindescription: What this plugin does.version: 1.0.0@@ -68,7 +70,7 @@ The **Plugin Index** at https://github.com/agent0ai/a0-plugins is the community-To share a plugin with the community:-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.+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).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`):```yamldiff --git a/plugins/_plugin_validator/webui/plugin-validator-checks.json b/plugins/_plugin_validator/webui/plugin-validator-checks.jsonindex def4e828a..3d019620e 100644--- a/plugins/_plugin_validator/webui/plugin-validator-checks.json+++ b/plugins/_plugin_validator/webui/plugin-validator-checks.json@@ -7,7 +7,7 @@"checks": {"manifest": {"label": "Manifest Validation",- "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.",+ "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.","criteria": {"pass": "plugin.yaml exists, parses, and matches the expected schema with no required fixes","warning": "Manifest is mostly valid but has extra keys, weak metadata, or non-blocking schema issues",@@ -16,10 +16,10 @@},"structure": {"label": "Structure Validation",- "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.",+ "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.","criteria": {- "pass": "Directory layout cleanly matches Agent Zero plugin conventions",- "warning": "Structure mostly works but contains unusual files or minor convention drift",+ "pass": "Directory layout cleanly matches Agent Zero plugin conventions and LICENSE exists at the plugin root",+ "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","fail": "Layout or required files clearly break plugin loading, installation, or contribution expectations"}},diff --git a/plugins/_plugin_validator/webui/plugin-validator-guidance.md b/plugins/_plugin_validator/webui/plugin-validator-guidance.mdindex 0e67f9625..861192ece 100644--- a/plugins/_plugin_validator/webui/plugin-validator-guidance.md+++ b/plugins/_plugin_validator/webui/plugin-validator-guidance.md@@ -7,3 +7,4 @@- Hooks runtime targeting: use `sys.executable` only for framework runtime work and `/opt/venv/bin/python` for agent-runtime installs.- execute.py pattern: expose `main()` and end with `if __name__ == "__main__": sys.exit(main())`.- Community contribution: plugin name must match `^[a-z0-9_]+$`, match the directory name, and stay unique in the published index.+- 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.diff --git a/plugins/_plugin_validator/webui/plugin-validator-prompt.md b/plugins/_plugin_validator/webui/plugin-validator-prompt.mdindex 8f69bb51b..0c19f812d 100644--- a/plugins/_plugin_validator/webui/plugin-validator-prompt.md+++ b/plugins/_plugin_validator/webui/plugin-validator-prompt.md@@ -20,7 +20,7 @@ Follow these steps in order:1. Resolve the plugin root and list every file below it. Do not sample; inspect the full plugin.2. Read `plugin.yaml` and record the plugin's name, title, description, and version.-3. Map the directory structure and identify every top-level file or folder that affects behavior.+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).4. Run ONLY the selected validation phases listed below.5. If a temporary clone or extracted directory was used, perform the cleanup exactly as instructed.diff --git a/skills/a0-contribute-plugin/SKILL.md b/skills/a0-contribute-plugin/SKILL.mdindex d8b2589ad..f729483c3 100644--- a/skills/a0-contribute-plugin/SKILL.md+++ b/skills/a0-contribute-plugin/SKILL.md@@ -52,7 +52,7 @@ The plugin must live in its **own standalone GitHub repository** with plugin conyour-plugin-repo/ <- GitHub repository root├── plugin.yaml <- runtime manifest (REQUIRED)├── README.md <- strongly recommended (shown in Plugin Hub detail view)-├── LICENSE <- strongly recommended+├── LICENSE <- REQUIRED for Plugin Index submission (place at repo root)├── default_config.yaml <- optional├── api/ <- API handlers├── tools/ <- agent tools@@ -174,6 +174,7 @@ Run these checks locally before opening the PR (mirrors what CI will verify):| `github` URL | Points to existing public repo || Remote `plugin.yaml` | Exists at repo root || Remote `plugin.yaml` `name` field | Matches index folder name exactly |+| Remote `LICENSE` | Exists at repo root (Plugin Index policy) || Folder name pattern | `^[a-z0-9_]+$`, no leading `_` || `github` URL uniqueness | Not already in the index for another plugin |@@ -227,6 +228,8 @@ gh pr create \## References+- Plugin architecture: `/a0/docs/agents/AGENTS.plugins.md`+- Developer lifecycle guide: `/a0/docs/developer/plugins.md`- Plugin Index repo: https://github.com/agent0ai/a0-plugins- Recommended tags: https://github.com/agent0ai/a0-plugins/blob/main/TAGS.md- Review before contributing: read `/a0/skills/a0-review-plugin/SKILL.md`diff --git a/skills/a0-create-plugin/SKILL.md b/skills/a0-create-plugin/SKILL.mdindex 6ea78849c..97c91542b 100644--- a/skills/a0-create-plugin/SKILL.md+++ b/skills/a0-create-plugin/SKILL.md@@ -24,6 +24,7 @@ Primary references:- /a0/docs/agents/AGENTS.components.md (Component system deep dive)- /a0/docs/agents/AGENTS.modals.md (Modal system & CSS conventions)- /a0/docs/agents/AGENTS.plugins.md (Extension points, plugin.yaml, settings system, Plugin Index)+- /a0/docs/developer/plugins.md (Developer lifecycle and publishing)---@@ -184,8 +185,8 @@ save_plugin_config(execute.py # Optional user-triggered setup, post-install, or maintenance scripthooks.py # Optional framework runtime hook functionsdefault_config.yaml # Optional default settings fallback- README.md # Optional, shown in Plugin List UI- LICENSE # Optional, shown in Plugin List UI+ README.md # Optional locally; strongly recommended for community plugins+ LICENSE # Optional locally (shown in Plugin List UI when present); required at repo root for Plugin Index submissionagents/<profile>/agent.yaml # Optional plugin-distributed agent profileapi/ # API Handlers (ApiHandler base class)@@ -306,7 +307,7 @@ your-plugin-repo/ ← GitHub repository root├── plugin.yaml ← runtime manifest (must include name field!)├── default_config.yaml├── README.md-├── LICENSE+├── LICENSE ← required at repo root before Plugin Index submission├── api/├── tools/├── extensions/diff --git a/skills/a0-manage-plugin/SKILL.md b/skills/a0-manage-plugin/SKILL.mdindex f322e7915..b4f89b8be 100644--- a/skills/a0-manage-plugin/SKILL.md+++ b/skills/a0-manage-plugin/SKILL.md@@ -358,6 +358,7 @@ Plugins with `always_enabled: true` in `plugin.yaml` cannot be toggled (framewor## References- Plugin architecture: `/a0/docs/agents/AGENTS.plugins.md`+- Developer lifecycle guide: `/a0/docs/developer/plugins.md`- Debug a broken plugin: read `/a0/skills/a0-debug-plugin/SKILL.md`- Create a new plugin: read `/a0/skills/a0-create-plugin/SKILL.md`- Review a plugin: read `/a0/skills/a0-review-plugin/SKILL.md`diff --git a/skills/a0-plugin-router/SKILL.md b/skills/a0-plugin-router/SKILL.mdindex 943256956..8e559ddf9 100644--- a/skills/a0-plugin-router/SKILL.md+++ b/skills/a0-plugin-router/SKILL.md@@ -79,8 +79,10 @@ always_enabled: false # forces ON, disables toggle (framework use only)| `hooks.py` | Framework runtime hooks (install, cache, registration) || `execute.py` | User-triggered script (setup, maintenance, repair) || `default_config.yaml` | Settings defaults |+| `README.md` | Optional locally; strongly recommended for community plugins so Plugin Hub users can inspect the plugin || `agents/<profile>/agent.yaml` | Plugin-distributed agent profiles || `conf/model_providers.yaml` | Add/override model providers |+| `LICENSE` | Optional under `usr/plugins/`; required at the root of a plugin GitHub repo before submitting to the Plugin Index |### Activationdiff --git a/skills/a0-review-plugin/SKILL.md b/skills/a0-review-plugin/SKILL.mdindex f2c14aff1..92f0d8933 100644--- a/skills/a0-review-plugin/SKILL.md+++ b/skills/a0-review-plugin/SKILL.md@@ -27,7 +27,7 @@ Read `usr/plugins/<name>/plugin.yaml`. Check:- [ ] File exists at plugin root- [ ] Valid YAML (parseable, mapping at top level)-- [ ] `name` field present, non-empty, matches `^[a-z0-9_]+$` and matches the directory name+- [ ] `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- [ ] `title` present and non-empty- [ ] `description` present and non-empty- [ ] `version` present, follows semver or simple `x.y.z` format@@ -54,10 +54,11 @@ Inspect the plugin directory layout:- [ ] If `webui/config.html` exists: plugin must declare at least one `settings_sections` entry- [ ] If `hooks.py` exists: warn if it does NOT contain an `install` function (common oversight)- [ ] If `execute.py` exists: check it has a `main()` function and `if __name__ == "__main__": sys.exit(main())`+- [ ] `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`- [ ] `default_config.yaml` (if present): valid YAML- [ ] No unexpected top-level entries (WARN for anything outside the standard layout)-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/`+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/`---@@ -125,9 +126,9 @@ Check:### Community readiness assessmentSummarize whether the plugin is ready for contribution:-- READY: all FAIL items resolved, no WARN items blocking+- 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)- NEEDS WORK: list specific FAIL items to fix-- OPTIONAL IMPROVEMENTS: list WARN items+- OPTIONAL IMPROVEMENTS: list non-blocking WARN items (if the user is only using the plugin locally, a missing `LICENSE` can be noted as optional)---@@ -168,5 +169,6 @@ Fix required: version missing in plugin.yaml, inline error box in webui/settings- Detailed pattern checklists: read `checklists.md` in this skill directory- Plugin architecture: `/a0/docs/agents/AGENTS.plugins.md`+- Developer lifecycle guide: `/a0/docs/developer/plugins.md`- Component system: `/a0/docs/agents/AGENTS.components.md`- If review passes and user wants to publish: read `/a0/skills/a0-contribute-plugin/SKILL.md`diff --git a/skills/a0-review-plugin/checklists.md b/skills/a0-review-plugin/checklists.mdindex ba6418d02..76cea262d 100644--- a/skills/a0-review-plugin/checklists.md+++ b/skills/a0-review-plugin/checklists.md@@ -264,7 +264,7 @@ Must: return `0` on success, non-zero on failure. Print progress. Be safe to rer## plugin.yaml Schema Reference```yaml-name: my_plugin # required for CI (^[a-z0-9_]+$, must match dir name)+name: my_plugin # required for community index (^[a-z0-9_]+$, must match dir name)title: My Plugin # required, UI display namedescription: What it does. # requiredversion: 1.0.0 # required@@ -290,6 +290,9 @@ When submitting to https://github.com/agent0ai/a0-plugins, CI validates:- Must exist at repo root- Must contain `name` field matching the index folder name exactly+**`LICENSE`** (your plugin's own repo):+- Must exist at repo root for Plugin Index / community listings (policy; same terms users expect from any open repo)+**Folder name**:- Pattern: `^[a-z0-9_]+$` (underscores, no hyphens)- Must not start with `_`