Agent Zero AI framework
fix(prompts): validate examples and sharpen skill descriptions
Alessandro2d400f5099c6
diff --git a/agents/agent0/prompts/agent.system.tool.response.md b/agents/agent0/prompts/agent.system.tool.response.mdindex 8a56d06bf..e706c9f6b 100644--- a/agents/agent0/prompts/agent.system.tool.response.md+++ b/agents/agent0/prompts/agent.system.tool.response.md@@ -17,12 +17,12 @@ usage:~~~json{"thoughts": [- "...",+ "..."],"headline": "Explaining why...","tool_name": "response","tool_args": {- "text": "Answer to the user",+ "text": "Answer to the user"}}~~~diff --git a/plugins/_browser/skills/browser-automation/SKILL.md b/plugins/_browser/skills/browser-automation/SKILL.mdindex 9efd61708..3aa5e8f15 100644--- a/plugins/_browser/skills/browser-automation/SKILL.md+++ b/plugins/_browser/skills/browser-automation/SKILL.md@@ -1,6 +1,6 @@---name: browser-automation-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.+description: "Control web pages: tabs, clicks, forms, downloads, screenshots; host or Docker browser."triggers:- "browser automation"- "web automation"diff --git a/plugins/_browser/skills/browser-extension-control/SKILL.md b/plugins/_browser/skills/browser-extension-control/SKILL.mdindex 0ebad1ad5..73e9a2458 100644--- a/plugins/_browser/skills/browser-extension-control/SKILL.md+++ b/plugins/_browser/skills/browser-extension-control/SKILL.md@@ -1,6 +1,10 @@---name: browser-extension-control-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.+description: "Build, edit, install or audit Chrome Web Store extensions in Agent Zero Browser."+triggers:+ - "build browser extension"+ - "modify browser extension"+ - "extension permissions"---# Agent Zero Browser Extensionsdiff --git a/plugins/_browser/skills/browser-form-workflows/SKILL.md b/plugins/_browser/skills/browser-form-workflows/SKILL.mdindex 0a199d4bb..621e97431 100644--- a/plugins/_browser/skills/browser-form-workflows/SKILL.md+++ b/plugins/_browser/skills/browser-form-workflows/SKILL.md@@ -1,6 +1,6 @@---name: browser-form-workflows-description: Use for complex Agent Zero Browser form workflows involving selects, checkboxes, radios, file uploads, contenteditable fields, multi-step validation, or visually verified submission.+description: "Fill and submit web forms: uploads, selects, validation and contenteditable fields."triggers:- "browser form"- "web form"diff --git a/plugins/_code_execution/prompts/agent.system.tool.code_exe.md b/plugins/_code_execution/prompts/agent.system.tool.code_exe.mdindex 56a6f355c..7a851308b 100644--- a/plugins/_code_execution/prompts/agent.system.tool.code_exe.md+++ b/plugins/_code_execution/prompts/agent.system.tool.code_exe.md@@ -28,7 +28,7 @@ examples:{"thoughts": ["Need to do...",- "Need to install...",+ "Need to install..."],"headline": "Installing zip package via terminal","tool_name": "code_execution_tool",@@ -36,7 +36,7 @@ examples:"runtime": "terminal","session": 0,"reset": false,- "code": "apt-get install zip",+ "code": "apt-get install zip"}}~~~@@ -48,7 +48,7 @@ examples:"thoughts": ["Need to do...","I can use...",- "Then I can...",+ "Then I can..."],"headline": "Executing Python code to check current directory","tool_name": "code_execution_tool",@@ -56,7 +56,7 @@ examples:"runtime": "python","session": 0,"reset": false,- "code": "import os\nprint(os.getcwd())",+ "code": "import os\nprint(os.getcwd())"}}~~~@@ -68,7 +68,7 @@ examples:"thoughts": ["Need to do...","I can use...",- "Then I can...",+ "Then I can..."],"headline": "Executing Javascript code to check current directory","tool_name": "code_execution_tool",@@ -76,7 +76,7 @@ examples:"runtime": "nodejs","session": 0,"reset": false,- "code": "console.log(process.cwd());",+ "code": "console.log(process.cwd());"}}~~~@@ -85,13 +85,13 @@ examples:~~~json{"thoughts": [- "Waiting for program to finish...",+ "Waiting for program to finish..."],"headline": "Waiting for long-running program to complete","tool_name": "code_execution_tool","tool_args": {"runtime": "output",- "session": 0,+ "session": 0}}~~~diff --git a/plugins/_code_execution/prompts/agent.system.tool.input.md b/plugins/_code_execution/prompts/agent.system.tool.input.mdindex 63354017c..c87f845ed 100644--- a/plugins/_code_execution/prompts/agent.system.tool.input.md+++ b/plugins/_code_execution/prompts/agent.system.tool.input.md@@ -8,7 +8,7 @@ usage:~~~json{"thoughts": [- "The program asks for Y/N...",+ "The program asks for Y/N..."],"headline": "Responding to terminal program prompt","tool_name": "input",diff --git a/plugins/_commands/skills/commands-create-slash-command/SKILL.md b/plugins/_commands/skills/commands-create-slash-command/SKILL.mdindex a594038bc..d6aaded5c 100644--- a/plugins/_commands/skills/commands-create-slash-command/SKILL.md+++ b/plugins/_commands/skills/commands-create-slash-command/SKILL.md@@ -1,6 +1,6 @@---name: commands-create-slash-command-description: Create or update Agent Zero slash commands for the built-in Commands plugin. Use when the user asks to add, edit, duplicate, or refine a reusable /command backed by YAML config plus text/python content files.+description: "Create or edit reusable Agent Zero /commands with YAML and text/Python templates."version: 1.0.0tags: ["commands", "slash-commands", "plugin", "yaml", "python", "templates"]triggers:diff --git a/plugins/_desktop/skills/linux-desktop/SKILL.md b/plugins/_desktop/skills/linux-desktop/SKILL.mdindex 9ede17908..0051c513f 100644--- a/plugins/_desktop/skills/linux-desktop/SKILL.md+++ b/plugins/_desktop/skills/linux-desktop/SKILL.md@@ -1,6 +1,6 @@---name: linux-desktop-description: Use only for Agent Zero's built-in Docker/Xpra Linux Desktop, XFCE apps, LibreOffice GUI apps, file manager, terminal, or visual workflows inside the Agent Zero runtime. Not for A0 CLI /computer-use or computer_use_remote host control.+description: "Control Agent Zero's Docker/Xpra desktop and GUI apps; not the user's host computer."version: "0.3.0"author: "Agent Zero Core Team"tags: ["linux", "desktop", "xfce", "libreoffice", "gui", "files", "terminal"]diff --git a/plugins/_document_query/skills/document-query/SKILL.md b/plugins/_document_query/skills/document-query/SKILL.mdindex f82902b5a..eb63d7710 100644--- a/plugins/_document_query/skills/document-query/SKILL.md+++ b/plugins/_document_query/skills/document-query/SKILL.md@@ -1,6 +1,6 @@---name: document-query-description: Use when reading, extracting, summarizing, comparing, or answering questions over local or remote documents, code files, PDFs, Office files, HTML/text files, large text-heavy files, and fallback OCR for document images or scans when vision tools are unavailable or insufficient.+description: "Read, extract or compare PDFs, Office files, URLs and large text; OCR when vision fails."version: 1.0.0author: Agent Zero Teamtags: ["documents", "ocr", "qa", "pdf", "code", "analysis"]diff --git a/plugins/_office/skills/calc-spreadsheets/SKILL.md b/plugins/_office/skills/calc-spreadsheets/SKILL.mdindex 04a99688f..3ebe288f2 100644--- a/plugins/_office/skills/calc-spreadsheets/SKILL.md+++ b/plugins/_office/skills/calc-spreadsheets/SKILL.md@@ -1,6 +1,6 @@---name: calc-spreadsheets-description: Use when creating, opening, or editing LibreOffice Calc ODS spreadsheets, or XLSX workbooks only when Excel compatibility is explicitly required.+description: "Create, open or edit Calc spreadsheets: ODS default; XLSX for Excel compatibility."version: "1.1.0"author: "Agent Zero Core Team"tags: ["calc", "ods", "opendocument", "excel", "xlsx", "spreadsheet", "workbook", "tables", "charts", "budget"]diff --git a/plugins/_office/skills/impress-presentations/SKILL.md b/plugins/_office/skills/impress-presentations/SKILL.mdindex 5bc6994ef..ee7ef4b31 100644--- a/plugins/_office/skills/impress-presentations/SKILL.md+++ b/plugins/_office/skills/impress-presentations/SKILL.md@@ -1,6 +1,6 @@---name: impress-presentations-description: Use when creating, opening, or editing LibreOffice Impress ODP presentations, or PPTX decks only when PowerPoint compatibility is explicitly required.+description: "Create, open or edit slides: ODP default; PPTX for PowerPoint compatibility."version: "1.1.0"author: "Agent Zero Core Team"tags: ["presentation", "odp", "opendocument", "pptx", "powerpoint", "slides", "deck", "impress"]diff --git a/plugins/_office/skills/markdown-documents/SKILL.md b/plugins/_office/skills/markdown-documents/SKILL.mdindex 2336a5eed..8042f74aa 100644--- a/plugins/_office/skills/markdown-documents/SKILL.md+++ b/plugins/_office/skills/markdown-documents/SKILL.md@@ -1,6 +1,6 @@---name: markdown-documents-description: Use when creating or editing Markdown documents, notes, reports, briefs, drafts, or other editable writing where Markdown should be the primary artifact format.+description: "Write or edit Markdown notes, reports and plain text; default for non-Office writing."version: "1.0.0"author: "Agent Zero Core Team"tags: ["markdown", "md", "documents", "writing", "notes", "reports", "briefs", "editor"]diff --git a/plugins/_office/skills/office-artifacts/SKILL.md b/plugins/_office/skills/office-artifacts/SKILL.mdindex 5e5a29c28..abdab595d 100644--- a/plugins/_office/skills/office-artifacts/SKILL.md+++ b/plugins/_office/skills/office-artifacts/SKILL.md@@ -1,6 +1,6 @@---name: office-artifacts-description: Use when creating, opening, reading, or editing Office artifacts such as LibreOffice-native ODT/ODS/ODP files and compatibility DOCX/XLSX/PPTX files with the office_artifact tool.+description: "Manage Office files, formats and versions; use Writer, Calc or Impress for content."version: "1.4.0"author: "Agent Zero Core Team"tags: ["office", "documents", "odt", "ods", "odp", "docx", "xlsx", "pptx", "spreadsheets", "presentations", "libreoffice", "opendocument"]diff --git a/plugins/_office/skills/writer-documents/SKILL.md b/plugins/_office/skills/writer-documents/SKILL.mdindex e996fa898..7868950e9 100644--- a/plugins/_office/skills/writer-documents/SKILL.md+++ b/plugins/_office/skills/writer-documents/SKILL.md@@ -1,6 +1,6 @@---name: writer-documents-description: Use when creating, opening, or editing LibreOffice Writer ODT documents, or DOCX documents only when Microsoft Word compatibility is explicitly required.+description: "Create, open or edit Writer documents: ODT default; DOCX for Word compatibility."version: "1.1.0"author: "Agent Zero Core Team"tags: ["writer", "odt", "opendocument", "word", "docx", "documents", "reports", "memos", "contracts"]diff --git a/plugins/_orchestrator/skills/orchestrator/SKILL.md b/plugins/_orchestrator/skills/orchestrator/SKILL.mdindex 2eabe23a1..99bc141bc 100644--- a/plugins/_orchestrator/skills/orchestrator/SKILL.md+++ b/plugins/_orchestrator/skills/orchestrator/SKILL.md@@ -1,6 +1,6 @@---name: orchestrator-description: Use when delegating coding or repository work to external terminal coding agents such as the user's host Claude Code/Codex/Cursor/Gemini CLI or container-installed pal agents.+description: "Delegate to external coding CLIs: A0 headless, Codex, Claude Code and others."triggers:- "terminal agent"- "external coding agent"diff --git a/skills/AGENTS.md b/skills/AGENTS.mdindex f247d2592..bf885cd0f 100644--- a/skills/AGENTS.md+++ b/skills/AGENTS.md@@ -18,6 +18,7 @@- Skill instructions must be operational and scoped to the skill's purpose.- Do not include secrets, private user data, or environment-specific credentials.- Supporting files referenced by a skill must exist relative to that skill directory.+- Keep bundled catalog descriptions within the 100-character prompt preview, with distinct task and environment/format boundaries. Keep lexical triggers separate.## Work Guidancediff --git a/skills/a0-contribute-plugin/SKILL.md b/skills/a0-contribute-plugin/SKILL.mdindex 08ddd27fc..90063648e 100644--- a/skills/a0-contribute-plugin/SKILL.md+++ b/skills/a0-contribute-plugin/SKILL.md@@ -1,6 +1,6 @@---name: a0-contribute-plugin-description: Guide for publishing an Agent Zero plugin to the community Plugin Index (a0-plugins repo). Covers GitHub repo setup, index.yaml creation, CI validation rules, and PR submission. Use when the user wants to share, publish, submit, or contribute a plugin to the Plugin Hub so other Agent Zero users can find and install it.+description: "Publish an Agent Zero plugin to the community Plugin Index: repository, index.yaml and PR."version: 1.0.0tags: ["plugins", "contribute", "publish", "plugin-hub", "community", "index", "PR"]trigger_patterns:diff --git a/skills/a0-create-agent/SKILL.md b/skills/a0-create-agent/SKILL.mdindex 36cc663ea..8050e9c43 100644--- a/skills/a0-create-agent/SKILL.md+++ b/skills/a0-create-agent/SKILL.md@@ -1,6 +1,6 @@---name: a0-create-agent-description: Create a new Agent Zero agent profile (subordinate). Covers where profiles live (user / plugin-distributed / project-scoped), the agent.yaml schema, the prompt inheritance & override model, and optional profile-specific tools and extensions. Use for any "create/add/new agent profile" request.+description: "Create Agent Zero profiles with agent.yaml, prompt overrides, tools and extensions."version: 1.0.0tags: ["agents", "profile", "create", "new", "subordinate"]trigger_patterns:diff --git a/skills/a0-create-plugin/SKILL.md b/skills/a0-create-plugin/SKILL.mdindex 9e7298741..d4cb80b21 100644--- a/skills/a0-create-plugin/SKILL.md+++ b/skills/a0-create-plugin/SKILL.md@@ -1,6 +1,6 @@---name: a0-create-plugin-description: Create, extend, or modify Agent Zero plugins. Follows strict full-stack conventions (usr/plugins, plugin.yaml, Store Gating, AgentContext, plugin settings). Use for UI hooks, API handlers, lifecycle extensions, or plugin settings UI.+description: "Build or extend Agent Zero plugins: tools, hooks, API handlers and settings UI."version: 1.0.0tags: ["plugins", "create", "build", "develop", "extend"]trigger_patterns:diff --git a/skills/a0-debug-plugin/SKILL.md b/skills/a0-debug-plugin/SKILL.mdindex 28c2d6a04..5c43345eb 100644--- a/skills/a0-debug-plugin/SKILL.md+++ b/skills/a0-debug-plugin/SKILL.md@@ -1,6 +1,6 @@---name: a0-debug-plugin-description: Diagnose and fix Agent Zero plugin problems. Covers plugin not appearing, won't enable, API endpoints not responding, frontend store errors, extension point injection, settings resolution, hooks.py issues, and log inspection. Use when a plugin is not working, not loading, crashing, missing from the list, or behaving unexpectedly.+description: "Diagnose Agent Zero plugin failures: loading, crashes, hooks, APIs, UI and settings."version: 1.0.0tags: ["plugins", "debug", "troubleshoot", "fix", "diagnose", "error", "broken"]trigger_patterns:diff --git a/skills/a0-development/SKILL.md b/skills/a0-development/SKILL.mdindex 94d44a500..6f51cb39d 100644--- a/skills/a0-development/SKILL.md+++ b/skills/a0-development/SKILL.md@@ -1,6 +1,6 @@---name: a0-development-description: Development guide for extending Agent Zero from current source and DOX. Use for framework architecture, tools, extensions, API/WebUI handlers, agent profiles, prompts, skills, projects, runtime boundaries, and contribution workflow. Load the focused reference files before giving implementation guidance.+description: "Develop Agent Zero itself: framework, tools, API/WebUI, prompts, runtimes and DOX."version: 1.1.0author: Agent Zero Teamtags: ["development", "framework", "agent-zero", "extending", "tools", "extensions", "skills", "api", "agents", "prompts", "dox"]diff --git a/skills/a0-manage-plugin/SKILL.md b/skills/a0-manage-plugin/SKILL.mdindex 2a9deb15e..708233419 100644--- a/skills/a0-manage-plugin/SKILL.md+++ b/skills/a0-manage-plugin/SKILL.md@@ -1,6 +1,6 @@---name: a0-manage-plugin-description: "Manage Agent Zero plugins lifecycle: browse the Plugin Hub, scan for security, install from Git/ZIP/Plugin Hub, update, uninstall, enable, disable, debug, and troubleshoot. Use when asked to install, update, uninstall, remove, scan, find, search, enable, disable, debug, or troubleshoot a plugin."+description: "Find, scan, install, update, remove, enable or disable Agent Zero plugins in the Plugin Hub."version: 1.2.0tags: ["plugins", "install", "uninstall", "update", "scan", "security", "debug", "troubleshoot", "plugin-hub", "manage"]trigger_patterns:diff --git a/skills/a0-plugin-router/SKILL.md b/skills/a0-plugin-router/SKILL.mdindex a70238f83..1a5119c87 100644--- a/skills/a0-plugin-router/SKILL.md+++ b/skills/a0-plugin-router/SKILL.md@@ -1,6 +1,6 @@---name: a0-plugin-router-description: Main entry point for all Agent Zero plugin tasks. Routes to specialist skills for creating, reviewing, contributing, managing, or debugging plugins. Use when the user mentions plugins, asks how the plugin system works, wants to build/install/uninstall/publish/debug a plugin, or asks about the Plugin Hub.+description: "Route Agent Zero plugin requests to build, debug, review, publish or management skills."version: 1.0.0tags: ["plugins", "router", "meta", "create", "review", "contribute", "manage", "plugin-hub"]trigger_patterns:diff --git a/skills/a0-review-plugin/SKILL.md b/skills/a0-review-plugin/SKILL.mdindex 924ed73e0..9e4f74a1e 100644--- a/skills/a0-review-plugin/SKILL.md+++ b/skills/a0-review-plugin/SKILL.md@@ -1,6 +1,6 @@---name: a0-review-plugin-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.+description: "Audit Agent Zero plugins: manifest, code, security and community duplicates before release."version: 1.0.0tags: ["plugins", "review", "audit", "validate", "security", "checklist"]trigger_patterns:diff --git a/skills/build-skill/SKILL.md b/skills/build-skill/SKILL.mdindex 45edfb429..724b06b0a 100644--- a/skills/build-skill/SKILL.md+++ b/skills/build-skill/SKILL.md@@ -1,6 +1,6 @@---name: build-skill-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.+description: "Create, rename, move, audit, test or refine Agent Zero skills and reusable workflows."---# Build Skilldiff --git a/skills/scheduled-tasks/SKILL.md b/skills/scheduled-tasks/SKILL.mdindex b7a09f6ca..931ecabf7 100644--- a/skills/scheduled-tasks/SKILL.md+++ b/skills/scheduled-tasks/SKILL.md@@ -1,6 +1,6 @@---name: scheduled-tasks-description: Use for complex Agent Zero scheduler work, including creating, updating, deleting, running, waiting for, timezone-correcting, or auditing scheduled, planned, and adhoc tasks.+description: "Create, edit, run or audit scheduled, planned and adhoc tasks; cron, timezones and reminders."---# Scheduler Tasksdiff --git a/skills/setup-a0-cli/SKILL.md b/skills/setup-a0-cli/SKILL.mdindex b6867dba7..6d548fc30 100644--- a/skills/setup-a0-cli/SKILL.md+++ b/skills/setup-a0-cli/SKILL.md@@ -1,6 +1,12 @@---name: setup-a0-cli-description: Briefly guide installing, connecting, or troubleshooting the A0 CLI on the user's host so Dockerized Agent Zero can work with real local files. Use for install A0, enable the host connector, connect local files, remote tools, host-vs-container confusion, or A0 CLI setup problems.+description: "Install, connect or troubleshoot A0 CLI host access, local files and remote tools."+triggers:+ - "install A0"+ - "connect local files"+ - "enable host connector"+ - "A0 CLI setup"+ - "host vs container"---# A0 CLI Host Setupdiff --git a/tests/test_prompt_catalogs.py b/tests/test_prompt_catalogs.pynew file mode 100644index 000000000..fc6dee8b4--- /dev/null+++ b/tests/test_prompt_catalogs.py@@ -0,0 +1,50 @@+import json+import re+from pathlib import Path++import pytest++from helpers import skills+++ROOT = Path(__file__).resolve().parents[1]++[email protected]("path", [+ "plugins/_code_execution/prompts/agent.system.tool.code_exe.md",+ "plugins/_code_execution/prompts/agent.system.tool.input.md",+ "agents/agent0/prompts/agent.system.tool.response.md",+])+def test_tool_examples_are_complete_valid_json(path):+ examples = re.findall(r"~~~json\n(.*?)\n~~~", (ROOT / path).read_text(), re.S)+ assert examples+ for example in examples:+ request = json.loads(example)+ assert {"thoughts", "headline", "tool_name", "tool_args"} <= request.keys()+ assert isinstance(request["tool_args"], dict)+++def test_default_skill_descriptions_fit_preview_and_remain_searchable(monkeypatch):+ paths = [*ROOT.glob("skills/*/SKILL.md"), *ROOT.glob("plugins/*/skills/*/SKILL.md")]+ candidates = []+ for path in paths:+ if "_a0_connector" in path.parts: # Host-only skills are outside the default catalog.+ continue+ skill = skills.skill_from_markdown(path)+ assert skill is not None, path+ assert 0 < len(skill.description) <= 100, path+ candidates.append(skill)+ monkeypatch.setattr(skills, "list_skills", lambda *args, **kwargs: candidates)+ for query, name in [+ ("publish plugin", "a0-contribute-plugin"),+ ("plugin not loading", "a0-debug-plugin"),+ ("create agent", "a0-create-agent"),+ ("form validation", "browser-form-workflows"),+ ("Chrome Web Store", "browser-extension-control"),+ ("extension permissions", "browser-extension-control"),+ ("connect local files", "setup-a0-cli"),+ ("Word document", "writer-documents"),+ ("Docker desktop terminal", "linux-desktop"),+ ("framework development", "a0-development"),+ ]:+ assert name in [skill.name for skill in skills.search_skills(query, limit=3)], query