| 1 | --- |
| 2 | name: a0-review-plugin |
| 3 | description: Full audit of Agent Zero plugins in usr/plugins/. Reviews manifest validity, directory structure, code patterns (Store Gating, notifications, imports), security, and duplicate detection against the community index. Use when asked to review, audit, validate, or check an existing plugin before using or contributing it. |
| 4 | version: 1.0.0 |
| 5 | tags: ["plugins", "review", "audit", "validate", "security", "checklist"] |
| 6 | trigger_patterns: |
| 7 | - "review plugin" |
| 8 | - "audit plugin" |
| 9 | - "validate plugin" |
| 10 | - "check plugin" |
| 11 | - "plugin review" |
| 12 | - "is my plugin correct" |
| 13 | - "plugin checklist" |
| 14 | --- |
| 15 | |
| 16 | # Agent Zero Plugin Review |
| 17 | |
| 18 | Full-audit workflow for plugins in `/a0/usr/plugins/<name>/`. Run all 4 phases in order and report findings grouped by phase. Mark each item PASS, FAIL, or WARN. |
| 19 | |
| 20 | For detailed checklists and code pattern references, read `checklists.md` in this skill directory when needed. |
| 21 | |
| 22 | --- |
| 23 | |
| 24 | ## Phase 1: Manifest Validation |
| 25 | |
| 26 | 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 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 |
| 34 | - [ ] `settings_sections` is a list; each value is one of: `agent`, `external`, `mcp`, `developer`, `backup` |
| 35 | - [ ] `per_project_config` and `per_agent_config` are booleans (if present) |
| 36 | - [ ] `always_enabled` is `false` or absent (only framework core plugins should use `true`) |
| 37 | - [ ] No unknown fields (warn on extra keys not in the schema) |
| 38 | |
| 39 | --- |
| 40 | |
| 41 | ## Phase 2: Structure Validation |
| 42 | |
| 43 | Inspect the plugin directory layout: |
| 44 | |
| 45 | - [ ] Directory is under `usr/plugins/` (not `plugins/` - that is reserved for core) |
| 46 | - [ ] Directory name matches `^[a-z0-9_]+$` |
| 47 | - [ ] If `api/` exists: contains Python files only; each should subclass `ApiHandler` |
| 48 | - [ ] If `tools/` exists: contains Python files only; each should subclass `Tool` |
| 49 | - [ ] If `extensions/` exists: check subdirs follow `python/<point>/`, `python/_functions/<module>/<qualname>/<start|end>/`, or `webui/<point>/` patterns; flag the retired flattened `python/<module>_<qualname>_<start|end>/` form |
| 50 | - [ ] If `helpers/` exists: shared Python logic (standard directory) |
| 51 | - [ ] If `prompts/` exists: prompt templates (standard directory) |
| 52 | - [ ] If `agents/` exists: agent profiles with `<profile>/agent.yaml` (standard directory) |
| 53 | - [ ] If `conf/` exists: configuration files such as `model_providers.yaml` (standard directory) |
| 54 | - [ ] If `webui/config.html` exists: plugin must declare at least one `settings_sections` entry |
| 55 | - [ ] If `hooks.py` exists: review whether it defines the lifecycle hook functions the plugin appears to rely on, especially `install`, `pre_update`, and `uninstall` when the plugin needs install-time, update-time, or cleanup behavior — if `install()` adds dependencies, flag a missing `uninstall()` as WARN |
| 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 | |
| 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 | |
| 65 | ## Phase 3: Code Pattern Review |
| 66 | |
| 67 | Read source files and check for violations of Agent Zero conventions. |
| 68 | |
| 69 | ### Frontend (HTML/JS) |
| 70 | |
| 71 | - [ ] Every component that accesses a store uses the Store Gate pattern: |
| 72 | ```html |
| 73 | <div x-data> |
| 74 | <template x-if="$store.myStore"> |
| 75 | <div x-init="$store.myStore.onOpen()" x-destroy="$store.myStore.cleanup()"> |
| 76 | ... |
| 77 | </div> |
| 78 | </template> |
| 79 | </div> |
| 80 | ``` |
| 81 | - [ ] No `alpine:init` event listeners inside HTML files (store logic must be in `.js` files) |
| 82 | - [ ] Alpine stores use `createStore` imported from `/js/AlpineStore.js` |
| 83 | - [ ] No inline error/success `<div>` blocks bound to `store.error` or similar - must use notification system: |
| 84 | - `toastFrontendError(msg, "Plugin Name")` / `toastFrontendSuccess(...)` etc. |
| 85 | - Import from `/components/notifications/notification-store.js` |
| 86 | - [ ] Static assets served via `GET /plugins/<name>/...` (not hardcoded absolute paths) |
| 87 | - [ ] Store module imported in HTML `<head>` via `<script type="module" src="/plugins/<name>/webui/store.js">` |
| 88 | |
| 89 | ### Backend (Python) |
| 90 | |
| 91 | - [ ] Correct import paths: |
| 92 | - `from agent import AgentContext, AgentContextType` (not `helpers.context`) |
| 93 | - `from initialize import initialize_agent` (not a local reimport) |
| 94 | - [ ] API handlers subclass `ApiHandler` from `python/helpers/api.py` |
| 95 | - [ ] Tools subclass `Tool` from `helpers.tool` |
| 96 | - [ ] Plugin settings read via `get_plugin_config("plugin-name", agent=agent)` from `helpers.plugins` |
| 97 | - [ ] User messages sent via `context.communicate(UserMessage(...))`, not direct socket writes |
| 98 | - [ ] `hooks.py` environment targeting: if installing packages for the agent runtime (not framework), subprocess must explicitly target the correct interpreter (e.g., `/opt/venv/bin/python`) |
| 99 | - [ ] No `sys.executable -m pip install` for agent-runtime deps (that installs into framework runtime instead) |
| 100 | |
| 101 | --- |
| 102 | |
| 103 | ## Phase 4: Security + Index Review |
| 104 | |
| 105 | ### Security checks |
| 106 | |
| 107 | - [ ] No hardcoded secrets, API keys, tokens, or passwords in any file |
| 108 | - [ ] No `eval()` or `exec()` on user-supplied input |
| 109 | - [ ] File path operations use safe joins (no concatenation with user input that could escape the sandbox) |
| 110 | - [ ] Subprocess calls do not pass unsanitized user input as shell strings |
| 111 | - [ ] ZIP extraction (if any): path traversal protection in place |
| 112 | - [ ] No outbound network calls to third-party endpoints without user awareness (WARN if present, not automatic FAIL) |
| 113 | |
| 114 | ### Duplicate detection against the community index |
| 115 | |
| 116 | Fetch the current index: |
| 117 | ``` |
| 118 | https://github.com/agent0ai/a0-plugins/releases/download/generated-index/index.json |
| 119 | ``` |
| 120 | |
| 121 | Check: |
| 122 | - [ ] Plugin `name` does not already exist as a folder in the index |
| 123 | - [ ] No other index entry points to the same `github` URL |
| 124 | - [ ] Plugin purpose is not already covered by an existing index entry (WARN for semantic overlap, not FAIL) |
| 125 | |
| 126 | ### Community readiness assessment |
| 127 | |
| 128 | Summarize whether the plugin is ready for contribution: |
| 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 |
| 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 | |
| 135 | ## Reporting Format |
| 136 | |
| 137 | ``` |
| 138 | ## Plugin Review: <plugin_name> |
| 139 | |
| 140 | ### Phase 1: Manifest |
| 141 | PASS name: my_plugin |
| 142 | PASS title: My Plugin |
| 143 | FAIL version: missing |
| 144 | ... |
| 145 | |
| 146 | ### Phase 2: Structure |
| 147 | PASS plugin.yaml present |
| 148 | WARN Unexpected file at root: notes.txt |
| 149 | ... |
| 150 | |
| 151 | ### Phase 3: Code Patterns |
| 152 | PASS Store Gating: found in webui/main.html |
| 153 | FAIL Inline error box found in webui/settings.html (use toastFrontendError instead) |
| 154 | ... |
| 155 | |
| 156 | ### Phase 4: Security + Index |
| 157 | PASS No hardcoded secrets found |
| 158 | PASS No duplicate in community index |
| 159 | WARN Outbound HTTP call to external service in api/handler.py:42 |
| 160 | |
| 161 | ### Summary |
| 162 | Status: NEEDS WORK |
| 163 | Fix required: version missing in plugin.yaml, inline error box in webui/settings.html |
| 164 | ``` |
| 165 | |
| 166 | --- |
| 167 | |
| 168 | ## References |
| 169 | |
| 170 | - Detailed pattern checklists: read `checklists.md` in this skill directory |
| 171 | - Plugin architecture: `/a0/plugins/AGENTS.md` |
| 172 | - Developer lifecycle guide: `/a0/docs/developer/plugins.md` |
| 173 | - Component system: `/a0/webui/components/AGENTS.md` |
| 174 | - If review passes and user wants to publish: read `/a0/skills/a0-contribute-plugin/SKILL.md` |