refactor: align skills and tool guidance
Rename high-impact skills to task-oriented names and move plugin-owned skills into their owning plugin folders.\n\nAlign renamed skill frontmatter with the official SKILL.md standard by keeping trigger language in name/description metadata, replacing the old create-skill wizard with build-skill, and updating browser, A0 connector, computer-use, CLI setup, and scheduler skill references.\n\nTighten the recurring cross-provider guidance gaps surfaced by the evidence sweeps: memory requests now avoid promptinclude-file routing, scheduler prompts distinguish cron schedules from planned ISO dates, document questions prefer document_query, skills_tool search/read_file usage is clearer, normal notifications set info/priority 10, and local/host text editors preserve patch intent.\n\nUpdate regression tests for the renamed skills, plugin ownership, prompt budget reality, and standard frontmatter shape.
Alessandro committed
May 10, 2026 at 07:13 UTC
6d29268cbd8f7fc7920d5bc877ee6f76ed4a66e5
29 files changed
+243
-424
docs/guides/a0-cli-connector.md
+1
-1
@@ -229,7 +229,7 @@ from your own browser:
229
If another agent is helping with setup, do not paste a whole checklist. Paste one line:
230
231
```text
232
-Set up the A0 CLI connector for Agent Zero on this machine using the a0-setup-cli Skill.
232
+Set up the A0 CLI connector for Agent Zero on this machine using the setup-a0-cli Skill.
233
```
234
235
## Troubleshooting
plugins/_a0_connector/prompts/agent.system.tool.code_execution_remote.md
+1
-1
@@ -4,7 +4,7 @@ Runs shell-backed execution on the machine where a connected A0 CLI is running.
4
Use this tool, not `code_execution_tool`, when the user asks for the connected
5
local terminal, the A0 CLI host, their local machine, or explicitly says not to
6
use Docker/server/container execution.
7
-For complex local project work, optionally load skill `code-execution-remote`.
7
+For complex local project work, optionally load skill `host-code-execution`.
8
9
Availability and permissions are checked when the tool runs. If no CLI is
10
connected, remote execution is disabled, or local access is not Read&Write for a
plugins/_a0_connector/prompts/agent.system.tool.text_editor_remote.md
+2
-1
@@ -3,7 +3,7 @@
3
Reads, writes, and patches files on the machine where a connected A0 CLI is
4
running. Use this tool, not server-side file tools, when the user asks for files
5
on the connected local machine, A0 CLI host, or explicitly says not to use
6
-Docker/server files. For complex remote edits, optionally load skill `text-editor-remote`.
6
+Docker/server files. For complex remote edits, optionally load skill `host-file-editing`.
7
8
Availability and permissions are checked when the tool runs. If no CLI is
9
connected, remote file access is disabled, or a write/patch needs Read&Write,
@@ -18,6 +18,7 @@ report that to the user instead of falling back to server-side file tools.
18
19
## Notes
20
- Prefer `read` before line-number edits.
21
+- If the user says patch, change without rewriting, or don't rewrite, use `action: "patch"` instead of `write`.
22
- Prefer `patch_text` for context-anchored changes and `edits` only for fresh, surgical line ranges.
23
- If freshness checks reject a line patch, reread the file and retry with updated ranges.
24
- Relative paths are relative to the CLI host filesystem. Do not rewrite them to
plugins/_a0_connector/skills/host-code-execution/SKILL.md
renamed
+3
-22
@@ -1,28 +1,9 @@
1
---
2
-name: code-execution-remote
3
-description: Guide safe use of code_execution_remote for shell-backed execution on the connected A0 CLI host machine.
4
-version: 1.0.0
5
-author: Agent Zero Team
6
-tags: ["agent-zero", "a0", "cli", "connector", "remote-execution", "shell"]
7
-trigger_patterns:
8
- - "code_execution_remote"
9
- - "remote shell execution"
10
- - "run commands on the cli host"
11
- - "run python on the cli host"
12
- - "run node on the cli host"
13
- - "connected local terminal"
14
- - "connected terminal"
15
- - "local terminal"
16
- - "my terminal"
17
- - "a0 cli"
18
- - "cli host"
19
- - "not docker"
20
- - "not the docker terminal"
21
-allowed_tools:
22
- - code_execution_remote
2
+name: host-code-execution
3
+description: Guide safe use of code_execution_remote for shell-backed execution on the connected A0 CLI host. Use when the user asks for their computer, local terminal, CLI host, remote shell, not Docker, or host-side Python/Node/terminal commands.
4
---
5
25
-# Code Execution Remote
6
+# Host Code Execution
7
8
## Boundary
9
plugins/_a0_connector/skills/host-computer-use/SKILL.md
renamed
+4
-17
@@ -1,22 +1,9 @@
1
---
2
-name: computer-use-remote
3
-description: Beta local desktop control through a connected A0 CLI host; use for screenshots, menus, browser chrome, and native UI tasks.
4
-version: 1.1.0
5
-author: Agent Zero Team
6
-tags: ["computer-use", "desktop", "local-ui", "screenshots", "native-ui"]
7
-trigger_patterns:
8
- - "computer use"
9
- - "computer-use"
10
- - "computer_use_remote"
11
- - "local desktop control"
12
- - "control local browser"
13
- - "click on screen"
14
- - "native ui"
15
-allowed_tools:
16
- - computer_use_remote
2
+name: host-computer-use
3
+description: Beta desktop control through the connected A0 CLI host. Use when the user asks for computer use, screenshots, screen inspection, menus, browser chrome, native UI tasks, clicking, scrolling, typing, or checking computer_use_remote status.
4
---
5
19
-# Computer Use Remote
6
+# Host Computer Use
7
8
This skill unlocks the beta `computer_use_remote` tool for connected local desktop control through A0 CLI.
9
@@ -26,7 +13,7 @@ Load this skill before using `computer_use_remote` for local desktop and native
13
14
If the task is browser-only and the user is flexible, prefer direct browser tooling because it is usually more reliable and token-efficient than screenshot-driven desktop control.
15
29
-If the task needs shell execution on the CLI host, load `code-execution-remote` separately rather than treating desktop control and shell execution as one affordance.
16
+If the task needs shell execution on the CLI host, load `host-code-execution` separately rather than treating desktop control and shell execution as one affordance.
17
18
## Tool Contract
19
plugins/_a0_connector/skills/host-file-editing/SKILL.md
renamed
+3
-19
@@ -1,25 +1,9 @@
1
---
2
-name: text-editor-remote
3
-description: Guide safe use of text_editor_remote for reading, writing, and patching files on the connected A0 CLI host machine.
4
-version: 1.0.0
5
-author: Agent Zero Team
6
-tags: ["agent-zero", "a0", "cli", "connector", "remote-files", "file-editing"]
7
-trigger_patterns:
8
- - "text_editor_remote"
9
- - "remote file editing"
10
- - "edit my local files through a0 cli"
11
- - "read files on the cli host"
12
- - "patch files on the cli host"
13
- - "connected local files"
14
- - "connected local machine files"
15
- - "local files not docker"
16
- - "a0 cli files"
17
- - "cli host files"
18
-allowed_tools:
19
- - text_editor_remote
2
+name: host-file-editing
3
+description: Guide safe use of text_editor_remote for reading, writing, and patching files on the connected A0 CLI host. Use when the user asks to inspect or edit files on their computer, local files, CLI host files, or files that are explicitly not Docker/server files.
4
---
5
22
-# Text Editor Remote
6
+# Host File Editing
7
8
## Boundary
9
plugins/_a0_connector/skills/setup-a0-cli/SKILL.md
renamed
+2
-16
@@ -1,20 +1,6 @@
1
---
2
-name: a0-setup-cli
3
-description: Guide the user through installing and connecting the A0 CLI on the host machine so Dockerized Agent Zero can work on real local files. Use when asked to install A0, set up the CLI connector, connect Agent Zero to local files, or troubleshoot host-vs-container setup confusion.
4
-version: 1.1.0
5
-author: Agent Zero Team
6
-tags: ["agent-zero", "a0", "cli", "connector", "docker", "setup", "local-files"]
7
-trigger_patterns:
8
- - "install a0"
9
- - "install a0 cli"
10
- - "set up a0 cli"
11
- - "set up a0 cli connector"
12
- - "connect a0 to agent zero"
13
- - "connect agent zero to local files"
14
- - "let agent zero work on my local files"
15
- - "install the terminal connector"
16
- - "help me set up the a0 cli connector"
17
- - "install a0 connector"
2
+name: setup-a0-cli
3
+description: Guide installing, connecting, or troubleshooting the A0 CLI connector on the user's host machine so Dockerized Agent Zero can work on real local files. Use for install A0, set up A0 CLI, connect local files, remote tools, host-vs-container confusion, or CLI connector setup problems.
4
---
5
6
# A0 CLI Host Setup
plugins/_browser/helpers/extension_manager.py
+1
-1
@@ -84,7 +84,7 @@ def install_chrome_web_store_extension(source: str) -> dict[str, Any]:
84
extension_id = parse_chrome_web_store_extension_id(source)
85
target = get_extensions_root() / "chrome-web-store" / extension_id
86
87
- with tempfile.TemporaryDirectory(prefix="a0-browser-ext-") as tmp:
87
+ with tempfile.TemporaryDirectory(prefix="browser-extension-control-") as tmp:
88
archive_path = Path(tmp) / f"{extension_id}.crx"
89
_download_crx(extension_id, archive_path)
90
payload_path = Path(tmp) / f"{extension_id}.zip"
plugins/_browser/prompts/agent.system.tool.browser.md
+3
-3
@@ -1,11 +1,11 @@
1
### browser
2
Rendered browser automation for pages that need interaction, JavaScript, forms, downloads, screenshots, or visual inspection.
3
4
-Prefer `search_engine` or `document_query` for plain text research. Use the browser headlessly unless the user opens the Browser surface or asks for a visible browser.
4
+Prefer `search_engine` or `document_query` for plain text research. The tool must not open a Browser surface automatically. Use the tool headlessly unless the user opens the Browser surface or asks for the optional visible WebUI viewer.
5
6
The browser may run in Docker container mode or A0 CLI host-browser mode depending on settings. Container-mode paths resolve inside Agent Zero; host-mode paths resolve on the connected A0 CLI host.
7
8
-For complex browser workflows, load skill `browser-tool`. For fragile forms, load skill `browser-forms`.
8
+For complex browser workflows, load skill `browser-automation`. For fragile forms, load skill `browser-form-workflows`.
9
10
Actions: `open`, `list`, `state`, `set_active`, `navigate`, `back`, `forward`, `reload`, `content`, `detail`, `screenshot`, `click`, `hover`, `double_click`, `right_click`, `drag`, `type`, `submit`, `type_submit`, `scroll`, `evaluate`, `key_chord`, `mouse`, `wheel`, `keyboard`, `clipboard`, `set_viewport`, `select_option`, `set_checked`, `upload_file`, `multi`, `close`, `close_all`.
11
@@ -16,7 +16,7 @@ Workflow:
16
- `content` returns markdown with refs like `[link 3]`, `[button 6]`, `[input text 8]`.
17
- Interactions use refs from the latest `content` capture.
18
- `navigate` reuses an existing `browser_id` and is preferred for serial browsing.
19
-- Screenshots are explicit only; call `vision_load` with the returned path before reasoning visually.
19
+- Screenshots are explicit only; the browser does not automatically load screenshots. Call `vision_load` with the returned path before reasoning visually.
20
- Keep the tab set small; close pages after extracting what you need.
21
22
`multi` is only a browser action: use `tool_name: "browser"` with `tool_args.action: "multi"`. Never use `tool_name: "multi"`.
plugins/_browser/skills/browser-automation/SKILL.md
renamed
+2
-2
@@ -1,5 +1,5 @@
1
---
2
-name: browser-tool
2
+name: browser-automation
3
description: Use for complex Agent Zero browser automation, including multi-tab browsing, screenshots, forms, uploads, raw pointer/keyboard actions, host-vs-container browser mode, and visual verification workflows.
4
---
5
@@ -39,7 +39,7 @@ Screenshot args include `quality`, `full_page`, and optional `path`. PNG is used
39
- `select_option` works for native selects and detectable ARIA listbox/combobox controls.
40
- `set_checked` works for checkbox, radio, switch, and toggle-like refs.
41
- `upload_file` works for file input refs or associated labels; verify the file exists in the active browser environment.
42
-- For fragile forms, load skill `browser-forms`.
42
+- For fragile forms, load skill `browser-form-workflows`.
43
44
## Pointer And Keyboard
45
plugins/_browser/skills/browser-extension-control/SKILL.md
renamed
+2
-3
@@ -1,7 +1,6 @@
1
---
2
-name: a0-browser-ext
3
-description: Create, inspect, install, and safely maintain Chrome extensions for Agent Zero's built-in Browser plugin.
4
-tags: ["agent-zero", "browser", "chrome-extension", "playwright", "manifest-v3"]
2
+name: browser-extension-control
3
+description: Create, inspect, install, and safely maintain Chrome extensions for Agent Zero's built-in Browser plugin. Use when the user asks to build a browser extension, modify an existing extension, install a Chrome Web Store extension, or review extension permissions.
4
---
5
6
# Agent Zero Browser Extensions
plugins/_browser/skills/browser-form-workflows/SKILL.md
renamed
+1
-1
@@ -1,5 +1,5 @@
1
---
2
-name: browser-forms
2
+name: browser-form-workflows
3
description: Use for complex Agent Zero Browser form workflows involving selects, checkboxes, radios, file uploads, contenteditable fields, multi-step validation, or visually verified submission.
4
---
5
plugins/_browser/webui/browser-store.js
+3
-3
@@ -446,7 +446,7 @@ const model = {
446
createExtensionWithAgent() {
447
this._prefillAgentPrompt(
448
[
449
- "Use the a0-browser-ext skill to create a new Chrome extension for Agent Zero's Browser.",
449
+ "Use the browser-extension-control skill to create a new Chrome extension for Agent Zero's Browser.",
450
"Start by asking me for the extension name, purpose, target websites, and required permissions.",
451
`Create it under ${this.extensionsRoot || EXTENSIONS_ROOT}/<extension-slug> and keep permissions minimal.`,
452
].join("\n")
@@ -457,12 +457,12 @@ const model = {
457
const url = String(this.extensionInstallUrl || "").trim();
458
const prompt = url
459
? [
460
- "Use the a0-browser-ext skill to review and optionally install this Chrome Web Store extension for Agent Zero's Browser.",
460
+ "Use the browser-extension-control skill to review and optionally install this Chrome Web Store extension for Agent Zero's Browser.",
461
`Chrome Web Store URL or id: ${url}`,
462
"Explain the permissions and any sandbox risk before enabling it.",
463
].join("\n")
464
: [
465
- "Use the a0-browser-ext skill to help me install and review a Chrome Web Store extension for Agent Zero's Browser.",
465
+ "Use the browser-extension-control skill to help me install and review a Chrome Web Store extension for Agent Zero's Browser.",
466
"Ask me for the Chrome Web Store URL or extension id first.",
467
"Explain the permissions and any sandbox risk before enabling it.",
468
].join("\n");
plugins/_promptinclude/prompts/agent.system.promptinclude.md
+4
-3
@@ -1,9 +1,10 @@
1
# Behavioral prompt includes
2
"{{name_pattern}}" files in workdir auto-injected into system prompt
3
create/edit/delete persist across conversations
4
-preference change/remember/note > MUST persist via text_editor before responding
5
-never just acknowledge verbally always persist to file
6
-use for persistent notes knowledge project context
4
+preference changes, instruction files, project notes, and prompt includes > persist via text_editor before responding
5
+explicit memory requests like "remember this", "what did I ask you to remember", or "forget this" > use memory tools, not promptinclude files, unless the user asks to edit a file
6
+never just acknowledge durable project/instruction changes verbally; persist them to file when the user asks for a file/instruction/preference change
7
+use promptinclude files for persistent project context and behavioral instructions
8
recursive search alphabetical by full path
9
{{if includes}}
10
### includes
plugins/_text_editor/prompts/agent.system.tool.text_editor.md
+1
@@ -45,6 +45,7 @@ usage:
45
46
#### patch
47
edit existing file. prefer patch_text; use edits only right after read for tiny line edits
48
+if the user says patch, change without rewriting, or don't rewrite, use action patch instead of write
49
args path plus exactly one of: patch_text string OR edits [{from to content}]
50
patch_text uses current file content, no prior read required
51
patch_text update-only forms:
prompts/agent.system.skills.md
+1
@@ -1,5 +1,6 @@
1
## skills
2
use `skills_tool` action `search` when the user's wording sounds like a task, trigger phrase, or keyword match for a skill
3
+if the user asks to find/search a skill, search first before loading
4
use `skills_tool` action `list` when you need a broader catalog view
5
use `skills_tool` action `load` before following a skill
6
loaded skills may document beta/specialized tools not in the always-on tool list; use them only after loading the skill
prompts/agent.system.tool.document_query.md
+1
@@ -1,5 +1,6 @@
1
### document_query
2
read local or remote documents or answer questions about them
3
+prefer this over text_editor when the user says "check/read this document" or asks a question about a document path/url, even for Markdown files
4
args:
5
- `document`: url path or list of them
6
- `queries`: optional list of questions
prompts/agent.system.tool.notify_user.md
+2
@@ -3,4 +3,6 @@ send an out-of-band notification without ending the current task
3
args: `message`, optional `title`, `detail`, `type`, `priority`, `timeout`
4
types: `info`, `success`, `warning`, `error`, `progress`
5
priority values: `20` high urgency, `10` normal urgency; omit for high
6
+normal note/notification -> set `type: "info"` and `priority: 10`
7
+use `success` only for a completed success message, not for a generic note
8
use for progress or alerts, not as the final answer
prompts/agent.system.tool.scheduler.md
+5
-2
@@ -1,5 +1,5 @@
1
### scheduler
2
-Manage saved tasks and schedules. For complex task work, load skill `scheduler-tasks`.
2
+Manage saved tasks and schedules. For complex task work, load skill `scheduled-tasks`.
3
4
Actions: `list_tasks`, `find_task_by_name`, `show_task`, `run_task`, `update_task`, `delete_task`, `create_scheduled_task`, `create_adhoc_task`, `create_planned_task`, `wait_for_task`.
5
@@ -10,4 +10,7 @@ Rules:
10
- Do not run scheduled/planned tasks unless the user asks to run now.
11
- Do not create recursive task prompts that schedule more tasks.
12
- New tasks use a dedicated context unless `dedicated_context` is `false`.
13
-- Use IANA timezones like `Europe/Rome`; omit timezone to use the current user timezone.
13
+- Use `create_scheduled_task` for recurring/cron tasks; `schedule` must be cron fields, not an ISO datetime.
14
+- For one planned date/time, use `create_planned_task` with `plan: ["YYYY-MM-DDTHH:MM:SS"]`.
15
+- Use IANA timezones like `Europe/Rome`; include timezone when the user names a timezone.
16
+- For "tomorrow at 9:15 Rome time", scheduled shape is `schedule: {"minute":"15","hour":"9","day":"11","month":"5","weekday":"*","timezone":"Europe/Rome"}`.
prompts/agent.system.tool.skills.md
+2
@@ -7,6 +7,8 @@ workflow:
7
- action `list`: discover available skills
8
- action `load`: load one skill by `skill_name`
9
- action `read_file`: open one file inside a loaded skill directory
10
+if the user says "find/search a skill", call `search` before `load` even when the likely skill name seems obvious
11
+`read_file` requires both `skill_name` and `file_path`; load the skill first, then read `SKILL.md` or the named relative file
12
after loading a skill, follow its instructions and use referenced files or scripts with other tools
13
reload a skill if its instructions are no longer in context
14
example:
skills/a0-development/SKILL.md
+3
-3
@@ -33,7 +33,7 @@ This skill provides comprehensive, accurate guidance for extending and building
33
- Build **API Endpoints** for the Web UI
34
- Create **Agent Profiles** (subordinates) with custom prompts
35
- Understand and extend the **Prompt System**
36
-- Create **Skills** (see the dedicated `create-skill` skill for the full wizard)
36
+- Create **Skills** (see the dedicated `build-skill` skill for the full wizard)
37
- Work with **Projects** and workspace configuration
38
39
> **Path convention:** Throughout this guide, `/a0/` refers to the framework root — this is `/a0/` inside Docker, or your local repository root in development. All paths are relative to this root.
@@ -41,7 +41,7 @@ This skill provides comprehensive, accurate guidance for extending and building
41
> [!IMPORTANT]
42
> **Plugins are the primary way to extend Agent Zero.** Most new tools, extensions, and prompts should be packaged as plugins. For all plugin tasks (create, review, manage, debug, contribute), load the `a0-plugin-router` skill which routes to the appropriate specialist. This guide covers the underlying framework patterns that plugins build upon.
43
44
-Related skills: `a0-plugin-router` (plugin tasks) | `create-skill` (skill creation wizard) | `a0-create-plugin` | `a0-review-plugin` | `a0-manage-plugin` | `a0-contribute-plugin` | `a0-debug-plugin`
44
+Related skills: `a0-plugin-router` (plugin tasks) | `build-skill` (skill creation wizard) | `a0-create-plugin` | `a0-review-plugin` | `a0-manage-plugin` | `a0-contribute-plugin` | `a0-debug-plugin`
45
46
---
47
@@ -631,7 +631,7 @@ The agent interacts with skills through JSON tool calls:
631
{"tool_name": "skills_tool:load", "tool_args": {"skill_name": "my-skill"}}
632
```
633
634
-> For the complete skill creation wizard — including SKILL.md format, frontmatter fields, directory structure, best practices, and examples — load the `create-skill` skill.
634
+> For the complete skill creation wizard — including SKILL.md format, frontmatter fields, directory structure, best practices, and examples — load the `build-skill` skill.
635
636
---
637
skills/build-skill/SKILL.md
new
+72
@@ -0,0 +1,72 @@
1
+---
2
+name: build-skill
3
+description: Build or improve Agent Zero skills following the official SKILL.md standard. Use when the user asks to create, rename, move, audit, test, or refactor a skill, or when a workflow should be packaged as reusable skill instructions.
4
+---
5
+
6
+# Build Skill
7
+
8
+Skills are small folders that teach Agent Zero a repeatable workflow. Keep the always-visible metadata precise, keep `SKILL.md` lean, and move detailed material into scripts, references, or assets only when the task needs it.
9
+
10
+## Standard Shape
11
+
12
+Every skill folder must be named exactly like the skill and contain `SKILL.md`.
13
+
14
+```text
15
+skill-name/
16
+├── SKILL.md
17
+├── scripts/ # optional deterministic helpers
18
+├── references/ # optional details loaded only when needed
19
+└── assets/ # optional output resources or templates
20
+```
21
+
22
+The frontmatter should contain only `name` and `description`:
23
+
24
+```yaml
25
+---
26
+name: skill-name
27
+description: What the skill does and when to use it. Include trigger wording here because this is the part visible before the skill loads.
28
+---
29
+```
30
+
31
+Use lowercase letters, digits, and hyphens. Prefer short verb-led names such as `build-skill`, `review-plugin`, or `host-file-editing`.
32
+
33
+## Workflow
34
+
35
+1. Identify two or three real user requests that should trigger the skill.
36
+2. Decide whether the skill belongs in core `skills/` or inside a plugin's `plugins/<plugin>/skills/` directory.
37
+3. Write the frontmatter description with all trigger conditions and key contexts.
38
+4. Keep the body focused on procedure, contracts, failure handling, and the files/scripts to load next.
39
+5. Move long examples, schemas, policies, or variant-specific detail to one-level-deep `references/` files.
40
+6. Add scripts only for deterministic or repeatedly rewritten operations, and test representative scripts.
41
+7. Validate by searching, loading, and using the skill on a median-user prompt.
42
+
43
+## Placement
44
+
45
+Use plugin-scoped skills when the skill exists to explain a plugin-owned tool or UI surface. Examples: Browser workflows belong under `_browser`; A0 CLI host tools belong under `_a0_connector`; Desktop canvas workflows belong under `_desktop`.
46
+
47
+Use root `skills/` for Agent Zero framework workflows that are not owned by one plugin, such as building skills, developing core features, or managing community plugins.
48
+
49
+## Writing Rules
50
+
51
+- Put trigger language in `description`, not in a body section. The body is loaded only after the skill is already selected.
52
+- Do not add README, changelog, quick reference, or install guide files inside the skill.
53
+- Avoid compatibility aliases in prompts or skill bodies when renaming; update references to the new name.
54
+- Prefer concise examples over long prose.
55
+- Do not duplicate the same guidance in both `SKILL.md` and references.
56
+- When multiple skills could apply, keep each skill's responsibility narrow and name the handoff clearly.
57
+
58
+## Validation
59
+
60
+Run targeted checks after edits:
61
+
62
+```bash
63
+conda run -n a0 pytest tests/test_skills_runtime.py tests/test_tool_action_contracts.py -q
64
+```
65
+
66
+Also exercise the live path when the skill changes agent-facing tool behavior:
67
+
68
+```text
69
+1. Ask a short ordinary prompt that should discover the skill.
70
+2. Confirm the agent uses skills_tool search/load when appropriate.
71
+3. Confirm it calls the intended tool only after the skill is loaded when the tool is skill-gated.
72
+```
skills/create-skill/SKILL.md
deleted
-288
@@ -1,288 +0,0 @@
1
----
2
-name: "create-skill"
3
-description: "Wizard for creating new Agent Zero skills. Guides users through creating well-structured SKILL.md files. Use when users want to create custom skills."
4
-version: "1.0.0"
5
-author: "Agent Zero Team"
6
-tags: ["meta", "wizard", "creation", "tutorial", "skills"]
7
-trigger_patterns:
8
- - "create skill"
9
- - "new skill"
10
- - "make skill"
11
- - "add skill"
12
- - "skill wizard"
13
----
14
-
15
-# Create Skill Wizard
16
-
17
-This skill helps you create new Agent Zero skills that follow the SKILL.md standard.
18
-
19
-## Quick Start
20
-
21
-To create a new skill, I'll guide you through these steps:
22
-
23
-1. **Name & Purpose** - What should this skill do?
24
-2. **Trigger Patterns** - When should this skill activate?
25
-3. **Content Structure** - What instructions should the agent follow?
26
-4. **Supporting Files** - Any scripts or templates needed?
27
-
28
-## SKILL.md Format
29
-
30
-Every skill needs a `SKILL.md` file with YAML frontmatter:
31
-
32
-```yaml
33
----
34
-name: "skill-name"
35
-description: "Clear description of what this skill does and when to use it"
36
-version: "1.0.0"
37
-author: "Your Name"
38
-tags: ["category1", "category2"]
39
-trigger_patterns:
40
- - "keyword1"
41
- - "phrase that triggers this"
42
----
43
-
44
-# Skill Title
45
-
46
-Your skill instructions go here...
47
-```
48
-
49
-## Required Fields
50
-
51
-| Field | Description | Example |
52
-|-------|-------------|---------|
53
-| `name` | Unique identifier (lowercase, hyphens) | `"code-review"` |
54
-| `description` | When/why to use this skill | `"Review code for quality and security issues"` |
55
-
56
-## Optional Fields
57
-
58
-| Field | Description | Example |
59
-|-------|-------------|---------|
60
-| `version` | Semantic version | `"1.0.0"` |
61
-| `author` | Creator name | `"Jane Developer"` |
62
-| `tags` | Categorization keywords | `["review", "quality"]` |
63
-| `trigger_patterns` | Words/phrases that activate skill | `["review", "check code"]` |
64
-| `allowed_tools` | Tools this skill can use | `["code_execution", "web_search"]` |
65
-
66
-## Skill Directory Structure
67
-
68
-```
69
-/a0/usr/skills/
70
-└── my-skill/
71
- ├── SKILL.md # Required: Main skill file
72
- ├── scripts/ # Optional: Helper scripts
73
- │ ├── helper.py
74
- │ └── process.sh
75
- ├── templates/ # Optional: Templates
76
- │ └── output.md
77
- └── docs/ # Optional: Additional docs
78
- └── examples.md
79
-```
80
-
81
-## Writing Good Skill Instructions
82
-
83
-### Be Specific and Actionable
84
-
85
-```markdown
86
-# Good
87
-When reviewing code:
88
-1. Check for security vulnerabilities
89
-2. Verify error handling
90
-3. Assess test coverage
91
-
92
-# Bad
93
-Review the code and make it better.
94
-```
95
-
96
-### Include Examples
97
-
98
-```markdown
99
-## Example Usage
100
-
101
-**User**: "Review my Python function for issues"
102
-
103
-**Agent Response**:
104
-> I'll review your function using the code review checklist:
105
->
106
-> 1. **Security**: No user input validation detected
107
-> 2. **Error Handling**: Missing try-catch for file operations
108
-> 3. **Testing**: Function is testable but no tests found
109
-```
110
-
111
-### Provide Checklists
112
-
113
-```markdown
114
-## Review Checklist
115
-- [ ] Input validation present
116
-- [ ] Error handling complete
117
-- [ ] Tests included
118
-- [ ] Documentation updated
119
-```
120
-
121
-## Creating Your Skill: Step by Step
122
-
123
-### Step 1: Define Purpose
124
-
125
-Answer these questions:
126
-- What problem does this skill solve?
127
-- When should the agent use it?
128
-- What's the expected output?
129
-
130
-### Step 2: Choose a Name
131
-
132
-- Use lowercase letters and hyphens
133
-- Be descriptive but concise
134
-- Examples: `code-review`, `data-analysis`, `deploy-helper`
135
-
136
-### Step 3: Write Trigger Patterns
137
-
138
-List words/phrases that should activate this skill:
139
-
140
-```yaml
141
-trigger_patterns:
142
- - "review"
143
- - "check code"
144
- - "code quality"
145
- - "pull request"
146
-```
147
-
148
-### Step 4: Structure Your Content
149
-
150
-Organize with clear sections:
151
-
152
-```markdown
153
-# Skill Title
154
-
155
-## When to Use
156
-Describe the trigger conditions
157
-
158
-## The Process
159
-Step-by-step instructions
160
-
161
-## Examples
162
-Show sample interactions
163
-
164
-## Tips
165
-Additional guidance
166
-```
167
-
168
-### Step 5: Add Supporting Files (Optional)
169
-
170
-If your skill needs scripts or templates:
171
-
172
-```bash
173
-# Create directory structure
174
-mkdir -p /a0/usr/skills/my-skill/{scripts,templates,docs}
175
-```
176
-
177
-## Example: Complete Skill
178
-
179
-```yaml
180
----
181
-name: "python-optimizer"
182
-description: "Optimize Python code for performance and readability. Use when asked to improve or optimize Python code."
183
-version: "1.0.0"
184
-author: "Agent Zero Team"
185
-tags: ["python", "optimization", "performance"]
186
-trigger_patterns:
187
- - "optimize python"
188
- - "improve performance"
189
- - "make faster"
190
- - "python optimization"
191
----
192
-
193
-# Python Optimizer
194
-
195
-## When to Use
196
-Activate when user asks to optimize, improve, or speed up Python code.
197
-
198
-## Optimization Process
199
-
200
-### Step 1: Profile First
201
-Before optimizing, understand where time is spent:
202
-```python
203
-import cProfile
204
-cProfile.run('your_function()')
205
-```
206
-
207
-### Step 2: Common Optimizations
208
-
209
-1. **Use List Comprehensions**
210
- ```python
211
- # Slow
212
- result = []
213
- for x in data:
214
- result.append(x * 2)
215
-
216
- # Fast
217
- result = [x * 2 for x in data]
218
- ```
219
-
220
-2. **Use Sets for Lookups**
221
- ```python
222
- # Slow: O(n)
223
- if item in large_list:
224
-
225
- # Fast: O(1)
226
- if item in large_set:
227
- ```
228
-
229
-3. **Use Generators for Large Data**
230
- ```python
231
- # Memory-heavy
232
- data = [process(x) for x in huge_list]
233
-
234
- # Memory-efficient
235
- data = (process(x) for x in huge_list)
236
- ```
237
-
238
-### Step 3: Verify Improvement
239
-Always measure before and after:
240
-```python
241
-import time
242
-start = time.perf_counter()
243
-# code to measure
244
-elapsed = time.perf_counter() - start
245
-print(f"Took {elapsed:.4f} seconds")
246
-```
247
-
248
-## Anti-Patterns to Avoid
249
-- Premature optimization
250
-- Optimizing without profiling
251
-- Sacrificing readability for tiny gains
252
-```
253
-
254
-## Skill Installation
255
-
256
-### Local Installation
257
-
258
-1. Create skill directory:
259
- ```bash
260
- mkdir -p /a0/usr/skills/my-skill
261
- ```
262
-
263
-2. Create SKILL.md:
264
- ```bash
265
- touch /a0/usr/skills/my-skill/SKILL.md
266
- ```
267
-
268
-3. Add content and save
269
-
270
-4. Skills are automatically loaded on next agent initialization
271
-
272
-### Sharing Skills
273
-
274
-To share skills with others:
275
-
276
-1. Create a GitHub repository
277
-2. Include the skill directory structure
278
-3. Add a README with installation instructions
279
-4. Users can copy to their `/a0/usr/skills/` directory
280
-
281
-## Testing Your Skill
282
-
283
-After creating a skill:
284
-
285
-1. Start a new conversation
286
-2. Use one of your trigger patterns
287
-3. Verify the agent follows your instructions
288
-4. Iterate and improve based on results
\ No newline at end of file
skills/scheduled-tasks/SKILL.md
renamed
+34
-3
@@ -1,5 +1,5 @@
1
---
2
-name: scheduler-tasks
2
+name: scheduled-tasks
3
description: Use for complex Agent Zero scheduler work, including creating, updating, deleting, running, waiting for, timezone-correcting, or auditing scheduled, planned, and adhoc tasks.
4
---
5
@@ -22,7 +22,7 @@ Use the `scheduler` tool to manage saved tasks. Always inspect existing tasks be
22
23
## Schedule Fields
24
25
-Schedules use cron-like fields:
25
+Schedules use cron-like fields. Do not put ISO datetimes into `schedule`.
26
27
- `minute`
28
- `hour`
@@ -31,7 +31,38 @@ Schedules use cron-like fields:
31
- `weekday`
32
- `timezone`
33
34
-Use IANA timezones such as `Europe/Rome`. Omit timezone to use the current user timezone. Planned task datetimes should be ISO strings such as `2026-05-09T18:25:00`.
34
+Use IANA timezones such as `Europe/Rome`. Omit timezone to use the current user timezone. Planned task datetimes go in `plan`, not `schedule`, and should be ISO strings such as `2026-05-09T18:25:00`.
35
+
36
+For one future reminder, prefer `create_planned_task` with:
37
+
38
+```json
39
+{
40
+ "action": "create_planned_task",
41
+ "name": "drink water",
42
+ "prompt": "Remind the user to drink water.",
43
+ "plan": ["2026-05-11T09:15:00"],
44
+ "dedicated_context": true
45
+}
46
+```
47
+
48
+For a recurring or cron-shaped scheduled task, use `create_scheduled_task` with:
49
+
50
+```json
51
+{
52
+ "action": "create_scheduled_task",
53
+ "name": "weekday stretch",
54
+ "prompt": "Remind the user to stretch.",
55
+ "schedule": {
56
+ "minute": "15",
57
+ "hour": "9",
58
+ "day": "*",
59
+ "month": "*",
60
+ "weekday": "1-5",
61
+ "timezone": "Europe/Rome"
62
+ },
63
+ "dedicated_context": true
64
+}
65
+```
66
67
## Safety
68
tests/test_a0_connector_prompt_gating.py
+34
-16
@@ -133,7 +133,14 @@ def test_remote_file_and_exec_tools_are_standard_tool_prompts_independent_from_c
133
134
135
def test_beta_computer_use_remote_is_skill_only_not_standard_tool_prompt():
136
- skill = PROJECT_ROOT / "skills" / "computer-use-remote" / "SKILL.md"
136
+ skill = (
137
+ PROJECT_ROOT
138
+ / "plugins"
139
+ / "_a0_connector"
140
+ / "skills"
141
+ / "host-computer-use"
142
+ / "SKILL.md"
143
+ )
144
145
assert not (PROMPT_ROOT / "agent.system.tool.computer_use_remote.md").exists()
146
assert '"tool_name": "computer_use_remote"' in skill.read_text(encoding="utf-8")
@@ -288,7 +295,7 @@ def test_remote_affordance_skills_parse():
295
/ "plugins"
296
/ "_a0_connector"
297
/ "skills"
291
- / "text-editor-remote"
298
+ / "host-file-editing"
299
/ "SKILL.md"
300
)
301
code_execution_skill = _parse_skill_frontmatter(
@@ -296,32 +303,43 @@ def test_remote_affordance_skills_parse():
303
/ "plugins"
304
/ "_a0_connector"
305
/ "skills"
299
- / "code-execution-remote"
306
+ / "host-code-execution"
307
/ "SKILL.md"
308
)
309
computer_skill = _parse_skill_frontmatter(
303
- PROJECT_ROOT / "skills" / "computer-use-remote" / "SKILL.md"
310
+ PROJECT_ROOT
311
+ / "plugins"
312
+ / "_a0_connector"
313
+ / "skills"
314
+ / "host-computer-use"
315
+ / "SKILL.md"
316
)
317
318
assert not legacy_connector_skill.exists()
307
- assert text_editor_skill["name"] == "text-editor-remote"
308
- assert text_editor_skill["allowed_tools"] == ["text_editor_remote"]
309
- assert "connected local files" in text_editor_skill["trigger_patterns"]
310
- assert "not docker" in code_execution_skill["trigger_patterns"]
311
- assert "connected local terminal" in code_execution_skill["trigger_patterns"]
312
- assert code_execution_skill["name"] == "code-execution-remote"
313
- assert code_execution_skill["allowed_tools"] == ["code_execution_remote"]
314
- assert computer_skill["name"] == "computer-use-remote"
315
- assert computer_skill["allowed_tools"] == ["computer_use_remote"]
319
+ assert text_editor_skill["name"] == "host-file-editing"
320
+ assert "text_editor_remote" in text_editor_skill["description"]
321
+ assert "not Docker/server files" in text_editor_skill["description"]
322
+ assert code_execution_skill["name"] == "host-code-execution"
323
+ assert "code_execution_remote" in code_execution_skill["description"]
324
+ assert "not Docker" in code_execution_skill["description"]
325
+ assert computer_skill["name"] == "host-computer-use"
326
+ assert "computer_use_remote" in computer_skill["description"]
327
328
329
def test_remote_tool_stubs_are_self_contained_and_reference_per_tool_skills():
330
text_stub = (PROMPT_ROOT / "agent.system.tool.text_editor_remote.md").read_text(encoding="utf-8")
331
exec_stub = (PROMPT_ROOT / "agent.system.tool.code_execution_remote.md").read_text(encoding="utf-8")
321
- computer_skill = (PROJECT_ROOT / "skills" / "computer-use-remote" / "SKILL.md").read_text(encoding="utf-8")
332
+ computer_skill = (
333
+ PROJECT_ROOT
334
+ / "plugins"
335
+ / "_a0_connector"
336
+ / "skills"
337
+ / "host-computer-use"
338
+ / "SKILL.md"
339
+ ).read_text(encoding="utf-8")
340
323
- assert "optionally load skill `text-editor-remote`" in text_stub
324
- assert "optionally load skill `code-execution-remote`" in exec_stub
341
+ assert "optionally load skill `host-file-editing`" in text_stub
342
+ assert "optionally load skill `host-code-execution`" in exec_stub
343
assert '"tool_name": "text_editor_remote"' in text_stub
344
assert '"tool_name": "code_execution_remote"' in exec_stub
345
assert '"tool_name": "computer_use_remote"' in computer_skill
tests/test_browser_agent_regressions.py
+11
-4
@@ -528,7 +528,14 @@ def test_browser_extension_menu_exposes_agent_and_url_paths():
528
html = (PROJECT_ROOT / "plugins" / "_browser" / "webui" / "browser-panel.html").read_text(
529
encoding="utf-8"
530
)
531
- skill = PROJECT_ROOT / "skills" / "a0-browser-ext" / "SKILL.md"
531
+ skill = (
532
+ PROJECT_ROOT
533
+ / "plugins"
534
+ / "_browser"
535
+ / "skills"
536
+ / "browser-extension-control"
537
+ / "SKILL.md"
538
+ )
539
540
assert "Create New Extension with A0" in html
541
assert "+ Create New with A0" not in html
@@ -902,19 +909,19 @@ def test_browser_tool_does_not_auto_open_canvas_policy_is_documented():
909
assert "select_option" in prompt
910
assert "set_checked" in prompt
911
assert "upload_file" in prompt
905
- assert "browser-forms" in prompt
912
+ assert "browser-form-workflows" in prompt
913
assert "does not automatically load screenshots" in prompt
914
assert "already open" in config
915
assert "already-open Browser surface" in config_html
916
917
918
def test_browser_forms_skill_is_plugin_owned_and_discoverable():
912
- skill_path = PROJECT_ROOT / "plugins" / "_browser" / "skills" / "browser-forms" / "SKILL.md"
919
+ skill_path = PROJECT_ROOT / "plugins" / "_browser" / "skills" / "browser-form-workflows" / "SKILL.md"
920
assert skill_path.exists()
921
skill = skill_path.read_text(encoding="utf-8")
922
assert skill.startswith("---\n")
923
frontmatter = skill.split("---", 2)[1]
917
- assert "name: browser-forms" in frontmatter
924
+ assert "name: browser-form-workflows" in frontmatter
925
assert "description:" in frontmatter
926
assert "select_option" in skill
927
assert "set_checked" in skill
tests/test_default_prompt_budget.py
+8
-4
@@ -46,9 +46,13 @@ async def _build_system_text(profile: str = "agent0") -> str:
46
async def test_default_agent0_prompt_budget_and_guardrails():
47
system_text = await _build_system_text()
48
49
- assert tokens.approximate_tokens(system_text) <= 3000
50
- assert "tool_name` must exactly match a listed tool name" in system_text
51
- assert "tool_args` must stay a json object" in system_text
49
+ # The default prompt now intentionally includes the compact always-on tool
50
+ # surface plus skill metadata. Keep the guardrail close to the observed
51
+ # budget so prompt creep remains visible without pretending this surface is
52
+ # a tiny single-tool prompt.
53
+ assert tokens.approximate_tokens(system_text) <= 8500
54
+ assert "`tool_name` must be one listed tool name" in system_text
55
+ assert "- tool_args: key value pairs tool arguments" in system_text
56
assert '"tool_name": "call_subordinate"' in system_text
57
assert '"reset": true' in system_text
58
assert '"tool_name": "text_editor"' in system_text
@@ -59,7 +63,7 @@ async def test_default_agent0_prompt_budget_and_guardrails():
63
assert '"tool_name": "code_execution_remote"' in system_text
64
assert '"tool_name": "text_editor_remote"' in system_text
65
assert '"tool_name": "computer_use_remote"' not in system_text
62
- assert "computer-use-remote" in system_text
66
+ assert "host-computer-use" in system_text
67
68
69
def test_a0_small_profile_removed_and_prompt_text_generic():
tests/test_skills_runtime.py
+29
-4
@@ -198,13 +198,13 @@ def test_reactivating_name_only_scope_default_by_path_clears_hidden_override(mon
198
def test_loaded_skill_entries_come_from_agent_data():
199
agent = DummyAgent()
200
agent.data[runtime.AGENT_DATA_NAME_LOADED_SKILLS] = [
201
- "computer-use-remote",
201
+ "host-computer-use",
202
"",
203
"a0-development",
204
]
205
206
assert runtime.get_loaded_skill_entries(agent) == [
207
- {"name": "computer-use-remote"},
207
+ {"name": "host-computer-use"},
208
{"name": "a0-development"},
209
]
210
@@ -276,16 +276,41 @@ def test_a0_manage_plugin_skill_frontmatter_is_valid_yaml():
276
assert "Agent Zero Plugin Management" in body
277
278
279
+def test_renamed_skills_use_standard_frontmatter_only():
280
+ skill_paths = [
281
+ PROJECT_ROOT / "skills" / "build-skill" / "SKILL.md",
282
+ PROJECT_ROOT / "skills" / "scheduled-tasks" / "SKILL.md",
283
+ PROJECT_ROOT / "plugins" / "_a0_connector" / "skills" / "host-code-execution" / "SKILL.md",
284
+ PROJECT_ROOT / "plugins" / "_a0_connector" / "skills" / "host-computer-use" / "SKILL.md",
285
+ PROJECT_ROOT / "plugins" / "_a0_connector" / "skills" / "host-file-editing" / "SKILL.md",
286
+ PROJECT_ROOT / "plugins" / "_a0_connector" / "skills" / "setup-a0-cli" / "SKILL.md",
287
+ PROJECT_ROOT / "plugins" / "_browser" / "skills" / "browser-automation" / "SKILL.md",
288
+ PROJECT_ROOT / "plugins" / "_browser" / "skills" / "browser-extension-control" / "SKILL.md",
289
+ PROJECT_ROOT / "plugins" / "_browser" / "skills" / "browser-form-workflows" / "SKILL.md",
290
+ ]
291
+
292
+ for path in skill_paths:
293
+ frontmatter, body, errors = runtime.split_frontmatter(path.read_text(encoding="utf-8"))
294
+ assert errors == []
295
+ assert set(frontmatter) == {"name", "description"}
296
+ assert frontmatter["name"] == path.parent.name
297
+ assert frontmatter["description"]
298
+ assert body
299
+
300
+
301
def test_unload_agent_skill_removes_loaded_skill_by_name():
302
agent = DummyAgent()
303
agent.data[runtime.AGENT_DATA_NAME_LOADED_SKILLS] = [
282
- "computer-use-remote",
304
+ "host-computer-use",
305
"a0-development",
306
]
307
308
removed = runtime.unload_agent_skill(
309
agent,
288
- {"name": "computer-use-remote", "path": "/a0/skills/computer-use-remote"},
310
+ {
311
+ "name": "host-computer-use",
312
+ "path": "/a0/plugins/_a0_connector/skills/host-computer-use",
313
+ },
314
)
315
316
assert removed is True
tests/test_tool_action_contracts.py
+8
-7
@@ -66,7 +66,7 @@ def _load_skills_tool(monkeypatch, skill_root: Path):
66
skills_stub.AGENT_DATA_NAME_LOADED_SKILLS = "loaded_skills"
67
skills_stub.MAX_ACTIVE_SKILLS = 20
68
fake_skill = _FakeSkill(
69
- name="browser-forms",
69
+ name="browser-form-workflows",
70
description="Use for complex browser forms.",
71
path=skill_root,
72
tags=[],
@@ -99,13 +99,13 @@ def test_skills_tool_accepts_action_alias_for_search(monkeypatch, tmp_path: Path
99
100
response = asyncio.run(tool.execute(**tool.args))
101
102
- assert "browser-forms" in response.message
102
+ assert "browser-form-workflows" in response.message
103
104
105
def test_skills_tool_read_file_action_reads_inside_skill_dir(
106
monkeypatch, tmp_path: Path
107
):
108
- skill_root = tmp_path / "browser-forms"
108
+ skill_root = tmp_path / "browser-form-workflows"
109
skill_root.mkdir()
110
(skill_root / "notes.md").write_text("Use labels before typing.\n", encoding="utf-8")
111
module = _load_skills_tool(monkeypatch, skill_root)
@@ -115,7 +115,7 @@ def test_skills_tool_read_file_action_reads_inside_skill_dir(
115
None,
116
{
117
"action": "read_file",
118
- "skill_name": "browser-forms",
118
+ "skill_name": "browser-form-workflows",
119
"file_path": "notes.md",
120
},
121
"",
@@ -124,7 +124,7 @@ def test_skills_tool_read_file_action_reads_inside_skill_dir(
124
125
response = asyncio.run(tool.execute(**tool.args))
126
127
- assert "Skill file: browser-forms/notes.md" in response.message
127
+ assert "Skill file: browser-form-workflows/notes.md" in response.message
128
assert "Use labels before typing." in response.message
129
130
@@ -464,9 +464,10 @@ def test_computer_use_remote_is_skill_gated():
464
/ "plugins/_a0_connector/prompts/agent.system.tool.computer_use_remote.md"
465
)
466
skill_text = (
467
- project_root / "skills/computer-use-remote/SKILL.md"
467
+ project_root
468
+ / "plugins/_a0_connector/skills/host-computer-use/SKILL.md"
469
).read_text(encoding="utf-8")
470
471
assert not prompt_path.exists()
472
assert '"tool_name": "computer_use_remote"' in skill_text
472
- assert "Beta local desktop control" in skill_text
473
+ assert "Beta desktop control" in skill_text