Skip to content

Agent Zero AI framework

update plugin Skills guidance for uninstall()

Alessandro8240edb400bf
diff --git a/skills/a0-create-plugin/SKILL.md b/skills/a0-create-plugin/SKILL.md
index 2ad649dfc..fc3d51d23 100644
--- a/skills/a0-create-plugin/SKILL.md
+++ b/skills/a0-create-plugin/SKILL.md
@@ -282,6 +282,7 @@ If your plugin needs framework-internal hook points, add a `hooks.py` file at th
- Current built-in usage:
- the plugin installer calls `install()` in `hooks.py` after placing a plugin in `usr/plugins/`
- the plugin updater calls `pre_update()` in `hooks.py` immediately before pulling new plugin code into place
+ - the plugin uninstaller calls `uninstall()` in `hooks.py` before deleting the plugin directory — use this to clean up any dependencies or state created by `install()`
- Hook functions may be sync or async.
- Hooks should be reversible and cleanup-safe. Prefer framework-managed state and plugin-owned paths over permanent system modifications.
diff --git a/skills/a0-debug-plugin/SKILL.md b/skills/a0-debug-plugin/SKILL.md
index 5f0102bfd..a5bd13768 100644
--- a/skills/a0-debug-plugin/SKILL.md
+++ b/skills/a0-debug-plugin/SKILL.md
@@ -138,6 +138,21 @@ print('Done')
"
```
+If the `uninstall()` hook is not running when the plugin is removed:
+- Check the function is named exactly `uninstall` (not `on_uninstall` or similar)
+- Check for exceptions in the function
+- The `uninstall()` hook is called by `uninstall_plugin()` in `helpers/plugins.py` before the plugin directory is deleted. If the user removed the plugin manually (`rm -rf`), the hook was bypassed — always use the API or UI to uninstall.
+- Manually trigger it in the **framework runtime** the same way:
+
+```bash
+cd /a0 && /opt/venv-a0/bin/python -c "
+import asyncio
+from helpers.plugins import call_plugin_hook
+asyncio.run(call_plugin_hook('<plugin_name>', 'uninstall'))
+print('Done')
+"
+```
+
---
## 8. Check Agent Zero logs
diff --git a/skills/a0-plugin-router/SKILL.md b/skills/a0-plugin-router/SKILL.md
index 6de16696d..34020602c 100644
--- a/skills/a0-plugin-router/SKILL.md
+++ b/skills/a0-plugin-router/SKILL.md
@@ -76,7 +76,7 @@ always_enabled: false # forces ON, disables toggle (framework use only)
| `extensions/webui/<point>/` | HTML/JS injected into UI breakpoints |
| `webui/config.html` | Plugin settings UI |
| `webui/*.html`, `webui/*.js` | Full plugin pages and Alpine stores |
-| `hooks.py` | Framework runtime hooks (install, pre_update, cache, registration) |
+| `hooks.py` | Framework runtime hooks (install, uninstall, pre_update, 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 |
diff --git a/skills/a0-review-plugin/SKILL.md b/skills/a0-review-plugin/SKILL.md
index c9d2a6d40..13daf61d3 100644
--- a/skills/a0-review-plugin/SKILL.md
+++ b/skills/a0-review-plugin/SKILL.md
@@ -52,7 +52,7 @@ Inspect the plugin directory layout:
- [ ] If `agents/` exists: agent profiles with `<profile>/agent.yaml` (standard directory)
- [ ] If `conf/` exists: configuration files such as `model_providers.yaml` (standard directory)
- [ ] If `webui/config.html` exists: plugin must declare at least one `settings_sections` entry
-- [ ] If `hooks.py` exists: review whether it defines the lifecycle hook functions the plugin appears to rely on, especially `install` and `pre_update` when the plugin needs install-time or update-time behavior
+- [ ] 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
- [ ] 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
diff --git a/skills/a0-review-plugin/checklists.md b/skills/a0-review-plugin/checklists.md
index 3ba31b3d5..464aa5379 100644
--- a/skills/a0-review-plugin/checklists.md
+++ b/skills/a0-review-plugin/checklists.md
@@ -232,7 +232,7 @@ save_plugin_config(
## hooks.py Environment Targeting
```python
-# hooks.py - install/pre_update hook example
+# hooks.py - install/uninstall/pre_update hook example
import subprocess
import sys
@@ -241,6 +241,10 @@ def install():
# This installs into the Agent Zero FRAMEWORK runtime (/opt/venv-a0)
subprocess.run([sys.executable, "-m", "pip", "install", "some-package==1.0.0"], check=True)
+def uninstall():
+ """Called by framework before deleting plugin directory. Clean up dependencies added by install()."""
+ subprocess.run([sys.executable, "-m", "pip", "uninstall", "-y", "some-package"], check=True)
+
def pre_update():
"""Called by framework immediately before plugin update pulls new code into place."""
# This installs into the Agent Zero FRAMEWORK runtime (/opt/venv-a0)