Skip to content

Agent Zero AI framework

Add browser skill discovery triggers

Alessandroec3c4cf81b83
diff --git a/plugins/_browser/AGENTS.md b/plugins/_browser/AGENTS.md
index 515ff382c..f77cc9938 100644
--- a/plugins/_browser/AGENTS.md
+++ b/plugins/_browser/AGENTS.md
@@ -23,6 +23,7 @@
- Coordinate tool, helper, and panel changes so browser state shown in the UI matches tool behavior.
- Keep `prompts/agent.system.tool.browser.md` as a compact callable contract; move detailed browser workflows into `skills/browser-automation/SKILL.md`.
+- Keep `skills/browser-automation/SKILL.md` frontmatter triggers current with rendered browsing, host-browser, screenshot, and web-interaction user phrasing so relevant-skill recall can surface the skill before the full browser workflow is needed.
- Keep fragile form guidance progressively disclosed through `skills/browser-form-workflows/SKILL.md`, linked from the browser prompt through `browser-automation`.
## Verification
diff --git a/plugins/_browser/skills/browser-automation/SKILL.md b/plugins/_browser/skills/browser-automation/SKILL.md
index 96a2cf590..f83d51bb3 100644
--- a/plugins/_browser/skills/browser-automation/SKILL.md
+++ b/plugins/_browser/skills/browser-automation/SKILL.md
@@ -1,6 +1,23 @@
---
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.
+triggers:
+ - "browser automation"
+ - "web automation"
+ - "open website"
+ - "open URL"
+ - "navigate browser"
+ - "interact with web page"
+ - "JavaScript page"
+ - "browser screenshot"
+ - "screenshot webpage"
+ - "visual verification"
+ - "multi-tab browsing"
+ - "download file from website"
+ - "upload file in browser"
+ - "host browser"
+ - "local browser"
+ - "my browser"
---
# Browser Tool
diff --git a/plugins/_browser/skills/browser-form-workflows/SKILL.md b/plugins/_browser/skills/browser-form-workflows/SKILL.md
index 879902f09..0a199d4bb 100644
--- a/plugins/_browser/skills/browser-form-workflows/SKILL.md
+++ b/plugins/_browser/skills/browser-form-workflows/SKILL.md
@@ -1,6 +1,19 @@
---
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.
+triggers:
+ - "browser form"
+ - "web form"
+ - "fill form"
+ - "fill web form"
+ - "submit form"
+ - "select option"
+ - "dropdown"
+ - "checkbox"
+ - "radio button"
+ - "file upload"
+ - "contenteditable"
+ - "form validation"
---
# Browser Forms
diff --git a/skills/build-skill/AGENTS.md b/skills/build-skill/AGENTS.md
index c591f6511..6de6fb063 100644
--- a/skills/build-skill/AGENTS.md
+++ b/skills/build-skill/AGENTS.md
@@ -18,6 +18,7 @@
## Work Guidance
- Update this skill when skill metadata, discovery, or validation behavior changes.
+- Keep frontmatter examples aligned with runtime-supported discovery fields such as `triggers`.
- Keep examples concise and avoid duplicating long reference material in the skill body.
## Verification
diff --git a/skills/build-skill/SKILL.md b/skills/build-skill/SKILL.md
index 1204f8371..45edfb429 100644
--- a/skills/build-skill/SKILL.md
+++ b/skills/build-skill/SKILL.md
@@ -19,12 +19,14 @@ skill-name/
└── assets/ # optional output resources or templates
```
-The frontmatter should contain only `name` and `description`:
+The frontmatter should contain `name`, `description`, and optional `triggers` when lexical discovery needs phrases that do not fit naturally in the description:
```yaml
---
name: skill-name
-description: What the skill does and when to use it. Include trigger wording here because this is the part visible before the skill loads.
+description: What the skill does and when to use it.
+triggers:
+ - "user phrase that should surface this skill"
---
```
@@ -34,7 +36,7 @@ Use lowercase letters, digits, and hyphens. Prefer short verb-led names such as
1. Identify two or three real user requests that should trigger the skill.
2. Decide whether the skill belongs in core `skills/` or inside a plugin's `plugins/<plugin>/skills/` directory.
-3. Write the frontmatter description with all trigger conditions and key contexts.
+3. Write the frontmatter description with the core trigger condition and key context; add `triggers` for short user phrases that should rank highly in skill search or relevant-skill recall.
4. Keep the body focused on procedure, contracts, failure handling, and the files/scripts to load next.
5. Move long examples, schemas, policies, or variant-specific detail to one-level-deep `references/` files.
6. Add scripts only for deterministic or repeatedly rewritten operations, and test representative scripts.
@@ -48,7 +50,7 @@ Use root `skills/` for Agent Zero framework workflows that are not owned by one
## Writing Rules
-- Put trigger language in `description`, not in a body section. The body is loaded only after the skill is already selected.
+- Put trigger language in frontmatter, not in a body section. Use `description` for the compact always-visible purpose and `triggers` for phrase matches used by search and relevant-skill recall.
- Do not add README, changelog, quick reference, or install guide files inside the skill.
- Avoid compatibility aliases in prompts or skill bodies when renaming; update references to the new name.
- Prefer concise examples over long prose.
diff --git a/tests/test_browser_agent_regressions.py b/tests/test_browser_agent_regressions.py
index 16dd6857b..a7dbf686a 100644
--- a/tests/test_browser_agent_regressions.py
+++ b/tests/test_browser_agent_regressions.py
@@ -934,9 +934,17 @@ def test_browser_skills_are_plugin_owned_and_progressively_linked():
automation = automation_path.read_text(encoding="utf-8")
skill = skill_path.read_text(encoding="utf-8")
assert skill.startswith("---\n")
+ automation_frontmatter = automation.split("---", 2)[1]
frontmatter = skill.split("---", 2)[1]
+ assert "name: browser-automation" in automation_frontmatter
+ assert "triggers:" in automation_frontmatter
+ assert "browser screenshot" in automation_frontmatter
+ assert "host browser" in automation_frontmatter
assert "name: browser-form-workflows" in frontmatter
assert "description:" in frontmatter
+ assert "triggers:" in frontmatter
+ assert "fill web form" in frontmatter
+ assert "file upload" in frontmatter
assert "progressive-disclosure workflow guide" in automation
assert "`browser-form-workflows` with `skills_tool:load`" in automation
assert 'skill_name: "browser-form-workflows"' in automation
diff --git a/tests/test_skills_runtime.py b/tests/test_skills_runtime.py
index 4a64e66b2..60193b73b 100644
--- a/tests/test_skills_runtime.py
+++ b/tests/test_skills_runtime.py
@@ -330,12 +330,62 @@ def test_renamed_skills_use_standard_frontmatter_only():
expected_keys = {"name", "description"}
if path.parent.name == "host-computer-use":
expected_keys.update({"tags", "triggers"})
+ if path.parent.name in {"browser-automation", "browser-form-workflows"}:
+ expected_keys.add("triggers")
assert set(frontmatter) == expected_keys
assert frontmatter["name"] == path.parent.name
assert frontmatter["description"]
assert body
+def test_browser_skills_rank_for_browser_trigger_phrases(monkeypatch):
+ browser_automation = runtime.skill_from_markdown(
+ PROJECT_ROOT / "plugins" / "_browser" / "skills" / "browser-automation" / "SKILL.md"
+ )
+ browser_forms = runtime.skill_from_markdown(
+ PROJECT_ROOT / "plugins" / "_browser" / "skills" / "browser-form-workflows" / "SKILL.md"
+ )
+ document_query = runtime.skill_from_markdown(
+ PROJECT_ROOT / "plugins" / "_document_query" / "skills" / "document-query" / "SKILL.md"
+ )
+ host_computer = runtime.skill_from_markdown(
+ PROJECT_ROOT / "plugins" / "_a0_connector" / "skills" / "host-computer-use" / "SKILL.md"
+ )
+ assert browser_automation is not None
+ assert browser_forms is not None
+ assert document_query is not None
+ assert host_computer is not None
+ monkeypatch.setattr(
+ runtime,
+ "list_skills",
+ lambda *args, **kwargs: [
+ document_query,
+ host_computer,
+ browser_forms,
+ browser_automation,
+ ],
+ )
+
+ browser_queries = (
+ "open this URL in my browser and take a screenshot",
+ "interact with a JavaScript page and verify it visually",
+ "use the host browser for multi-tab browsing",
+ )
+ for query in browser_queries:
+ results = runtime.search_skills(query, limit=3)
+ assert results[0].name == "browser-automation"
+
+ form_results = [
+ skill.name
+ for skill in runtime.search_skills(
+ "fill a web form with a checkbox and file upload",
+ limit=3,
+ )
+ ]
+ assert "browser-automation" in form_results
+ assert "browser-form-workflows" in form_results
+
+
def test_host_computer_use_ranks_before_linux_desktop_for_host_screen_queries(monkeypatch):
host_skill = runtime.skill_from_markdown(
PROJECT_ROOT / "plugins" / "_a0_connector" / "skills" / "host-computer-use" / "SKILL.md"