docs: update plugin docs and skill
update plugin skill and docs
Alessandro committed
Mar 2, 2026 at 10:46 UTC
c51f313d94c8942046c0954e9bedad69d6c53e6c
5 files changed
+68
-5
AGENTS.md
+2
-2
@@ -7,7 +7,7 @@ Tech Stack: Python 3.12+ | Flask | Alpine.js | LiteLLM | WebSocket (Socket.io)
7
Dev Server: python run_ui.py (runs on http://localhost:50001 by default)
8
Run Tests: pytest (standard) or pytest tests/test_name.py (file-scoped)
9
Documentation: README.md | docs/
10
-Frontend Deep Dives: [Component System](docs/agents/AGENTS.components.md) | [Modal System](docs/agents/AGENTS.modals.md) | [Plugin Architecture](AGENTS.plugins.md)
10
+Frontend Deep Dives: [Component System](docs/agents/AGENTS.components.md) | [Modal System](docs/agents/AGENTS.modals.md) | [Plugin Architecture](docs/agents/AGENTS.plugins.md)
11
12
---
13
@@ -98,7 +98,7 @@ Key Files:
98
- python/helpers/api.py: Base class for all API endpoints.
99
- docs/agents/AGENTS.components.md: Deep dive into the frontend component architecture.
100
- docs/agents/AGENTS.modals.md: Guide to the stacked modal system.
101
-- AGENTS.plugins.md: Comprehensive guide to the full-stack plugin system.
101
+- docs/agents/AGENTS.plugins.md: Comprehensive guide to the full-stack plugin system.
102
103
---
104
docs/agents/AGENTS.plugins.md
renamed
+1
@@ -24,6 +24,7 @@ Each plugin lives in usr/plugins/<plugin_name>/.
24
```text
25
usr/plugins/<plugin_name>/
26
├── plugin.yaml # Required: Title, version, settings + activation metadata
27
+├── initialize.py # Optional: one-time setup script (dependencies, models, etc.)
28
├── default_config.yaml # Optional: fallback settings defaults
29
├── README.md # Optional: shown in Plugin List UI
30
├── LICENSE # Optional: shown in Plugin List UI
docs/developer/plugins.md
+32
-1
@@ -49,6 +49,7 @@ Field reference:
49
```text
50
usr/plugins/<plugin_name>/
51
├── plugin.yaml
52
+├── initialize.py # optional one-time setup script
53
├── default_config.yaml # optional defaults
54
├── README.md # optional, shown in Plugin List UI
55
├── LICENSE # optional, shown in Plugin List UI
@@ -66,6 +67,36 @@ usr/plugins/<plugin_name>/
67
└── ...
68
```
69
70
+## Plugin Initialization (`initialize.py`)
71
+
72
+Plugins can include an optional `initialize.py` at the plugin root for one-time setup such as installing dependencies, downloading models, or preparing databases.
73
+
74
+- Triggered manually via the **Init** button in the Plugin List UI — never runs automatically
75
+- Execution is tracked in `usr/plugins/<plugin_name>/init_exec.json` (timestamp + exit code)
76
+- The modal streams output in real time and shows success/failure on completion
77
+
78
+```python
79
+import subprocess
80
+import sys
81
+
82
+def main():
83
+ print("Installing dependencies...")
84
+ result = subprocess.run(
85
+ [sys.executable, "-m", "pip", "install", "requests==2.31.0"],
86
+ text=True,
87
+ )
88
+ if result.returncode != 0:
89
+ print("ERROR: Installation failed")
90
+ return result.returncode
91
+ print("Done.")
92
+ return 0
93
+
94
+if __name__ == "__main__":
95
+ sys.exit(main())
96
+```
97
+
98
+Return `0` on success, non-zero on failure. Print progress for user feedback. Use `sys.executable` for pip commands.
99
+
100
## Settings Resolution
101
102
Plugin settings are resolved by scope. Higher priority overrides lower priority:
@@ -191,6 +222,6 @@ A built-in **Plugin Marketplace** (always-active plugin) will allow users to bro
222
223
## See Also
224
194
-- `AGENTS.plugins.md` for full architecture details
225
+- `docs/agents/AGENTS.plugins.md` for full architecture details
226
- `skills/a0-create-plugin/SKILL.md` for plugin authoring workflow (agent-facing)
227
- `plugins/README.md` for core plugin directory overview
plugins/README.md
+5
-1
@@ -11,7 +11,7 @@ This directory contains the system-level plugins bundled with Agent Zero.
11
12
For detailed guides on how to create, extend, or configure plugins, refer to:
13
14
-- [`AGENTS.plugins.md`](../AGENTS.plugins.md): Full-stack plugin architecture, manifest format, extension points, and Plugin Index submission.
14
+- [`docs/agents/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).
@@ -41,6 +41,10 @@ per_agent_config: false
41
always_enabled: false
42
```
43
44
+## Plugin Initialization (`initialize.py`)
45
+
46
+Plugins can include an optional `initialize.py` at the plugin root for one-time setup such as installing dependencies or downloading models. Users trigger it via the **Init** button in the Plugin List UI. The script should return `0` on success and print progress messages for user feedback.
47
+
48
## Plugin Index & Community Sharing
49
50
The **Plugin Index** at https://github.com/agent0ai/a0-plugins is the community-maintained registry of plugins available to all Agent Zero users.
skills/a0-create-plugin/SKILL.md
+28
-1
@@ -12,7 +12,7 @@ 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, Plugin Index)
15
+- /a0/docs/agents/AGENTS.plugins.md (Extension points, plugin.yaml, settings system, Plugin Index)
16
17
---
18
@@ -168,6 +168,7 @@ save_plugin_config(
168
```
169
/a0/usr/plugins/<name>/
170
plugin.yaml # Required manifest
171
+ initialize.py # Optional one-time setup script
172
default_config.yaml # Optional default settings fallback
173
README.md # Optional, shown in Plugin List UI
174
LICENSE # Optional, shown in Plugin List UI
@@ -184,6 +185,32 @@ save_plugin_config(
185
my-store.js # Alpine stores
186
```
187
188
+## Plugin Initialization Script (`initialize.py`)
189
+
190
+If your plugin requires one-time setup (e.g., installing dependencies, downloading models), add an `initialize.py` at the plugin root:
191
+
192
+```python
193
+import subprocess
194
+import sys
195
+
196
+def main():
197
+ print("Installing plugin dependencies...")
198
+ result = subprocess.run(
199
+ [sys.executable, "-m", "pip", "install", "requests==2.31.0"],
200
+ text=True,
201
+ )
202
+ if result.returncode != 0:
203
+ print("ERROR: Installation failed")
204
+ return result.returncode
205
+ print("Done.")
206
+ return 0
207
+
208
+if __name__ == "__main__":
209
+ sys.exit(main())
210
+```
211
+
212
+Users trigger it via the **Init** button in the Plugin List UI. Return `0` on success, non-zero on failure.
213
+
214
---
215
216
## Community Plugin: GitHub Repo + Plugin Index Submission