Merge pull request #1496 from 3clyp50/cli

add a0-setup-cli Skill and restore lexical trigger matching

Author: 3clyp50

docs/README.md

@@ -7,13 +7,15 @@ Welcome to the Agent Zero documentation hub. Whether you're getting started or d
 
 - **[Quickstart Guide](quickstart.md):** Get up and running in 5 minutes with Agent Zero.
 - **[Installation Guide](setup/installation.md):** Install scripts, updates, and advanced Docker setup (includes [How to Update](setup/installation.md#how-to-update-agent-zero)).
+- **[A0 CLI Connector](guides/a0-cli-connector.md):** Install the terminal-native connector, connect it to Agent Zero, and copy a setup brief for another agent.
 - **[Self Update](guides/self-update.md):** How the in-app updater works (technical reference).
 - **[VPS Deployment](setup/vps-deployment.md):** Deploy Agent Zero on a remote server.
 - **[Development Setup](setup/dev-setup.md):** Set up a local development environment.
 
 ## User Guides
 
 - **[Usage Guide](guides/usage.md):** Comprehensive guide to Agent Zero's features and capabilities.
+- **[A0 CLI Connector](guides/a0-cli-connector.md):** Terminal-first companion workflow for Agent Zero.
 - **[Projects Tutorial](guides/projects.md):** Learn to create isolated workspaces with dedicated context and memory.
 - **[API Integration](guides/api-integration.md):** Add external APIs without writing code.
 - **[MCP Setup](guides/mcp-setup.md):** Configure Model Context Protocol servers.
@@ -69,6 +71,7 @@ Welcome to the Agent Zero documentation hub. Whether you're getting started or d
   - [Self Update (technical)](guides/self-update.md)
   - [VPS Deployment](setup/vps-deployment.md)
   - [Development Setup](setup/dev-setup.md)
+  - [A0 CLI Connector](guides/a0-cli-connector.md)
 
 - [User Guides](#user-guides)
   - [Usage Guide](guides/usage.md)
@@ -91,6 +94,7 @@ Welcome to the Agent Zero documentation hub. Whether you're getting started or d
     - [Voice Interface](guides/usage.md#voice-interface)
     - [Memory Management](guides/usage.md#memory-management)
     - [Backup & Restore](guides/usage.md#backup--restore)
+  - [A0 CLI Connector](guides/a0-cli-connector.md)
   - [Projects Tutorial](guides/projects.md)
   - [API Integration](guides/api-integration.md)
   - [MCP Setup](guides/mcp-setup.md)

docs/guides/a0-cli-connector.md

@@ -0,0 +1,66 @@
+# A0 CLI Connector
+
+Agent Zero lives in Docker for a reason. That keeps it safer. The problem is that people see Docker and assume the agent can never really touch the code on their computer.
+
+A0 CLI is the answer to that.
+
+Agent Zero stays in Docker. A0 CLI installs on the host machine. That is what lets Agent Zero finally work on the real files on your real computer.
+
+For now, use the install commands below.
+
+## Quick Install
+
+**macOS / Linux:**
+```bash
+curl -LsSf https://raw.githubusercontent.com/agent0ai/a0-connector/main/install.sh | sh
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/agent0ai/a0-connector/main/install.ps1 | iex
+```
+
+**Manual fallback when uv is already installed or if URLs give 404:**
+```bash
+uv tool install git+https://github.com/agent0ai/a0-connector
+```
+
+Run these on the host machine, not inside the Agent Zero container.
+
+The installer uses `uv`, and `uv` will select or download a compatible Python if needed.
+
+## Open it and start working
+
+1. Make sure Agent Zero is already running.
+2. Launch A0 CLI on the host machine:
+
+```bash
+a0
+```
+
+3. If Agent Zero is running on the same machine, A0 CLI will usually find it for you.
+4. If Agent Zero is somewhere else, enter the exact web address or set `AGENT_ZERO_HOST` as env variable before launching `a0`.
+5. Open or create a chat and confirm you can talk to Agent Zero from the host machine.
+
+> [!NOTE]
+> Current Agent Zero builds starting from v1.9 include the builtin connector support that A0 CLI expects. If you see a connector-specific `404`, update Agent Zero first.
+
+## Give this to another agent
+
+If another agent is helping with setup, do not paste a whole checklist. Paste one line:
+
+```text
+Set up the A0 CLI connector for Agent Zero on this machine using the a0-setup-cli Skill.
+```
+
+## Troubleshooting
+
+- **Nothing appears locally:** Enter the Agent Zero web address manually or export `AGENT_ZERO_HOST`.
+- **You tried to install from inside Docker:** A0 CLI belongs on the host machine. Agent Zero stays in Docker.
+- **Function keys do nothing:** Some terminals and IDEs capture function keys. Use `Ctrl+P`.
+- **Connector route returns `404`:** Update Agent Zero to a build with builtin connector support.
+
+## Related links
+
+- [Quick Start](../quickstart.md)
+- [Installation Guide](../setup/installation.md)

docs/quickstart.md

@@ -23,6 +23,34 @@ Follow the CLI prompts for port and authentication, complete onboarding, then op
 > [!NOTE]
 > For manual Docker Desktop setup, volume mapping, and platform-specific detail, see the [Installation Guide](setup/installation.md#manual-installation-advanced).
 
+## Use Agent Zero on your real local files
+
+If you want Agent Zero to work on the actual files on your computer, this is the important part.
+
+Agent Zero stays in Docker for safety. The A0 CLI installs and runs on your host machine. That host-side CLI is what lets Agent Zero work on the real files on your real computer.
+
+**macOS / Linux:**
+```bash
+curl -LsSf https://raw.githubusercontent.com/agent0ai/a0-connector/main/install.sh | sh
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/agent0ai/a0-connector/main/install.ps1 | iex
+```
+
+Run those on the host machine, not inside the Agent Zero container.
+
+Then launch:
+
+```bash
+a0
+```
+
+Once `a0` connects, open or create a chat there. That is the path that lets Agent Zero stay in Docker while still working on real local files on your machine.
+
+For the full setup flow, manual fallback install paths, remote-host tips, and a copy-ready brief for another agent, see the [A0 CLI Connector guide](guides/a0-cli-connector.md).
+
 ### Open the Web UI and configure your API key
 
 Open your browser and navigate to `http://localhost:<PORT>`. The Web UI will show the onboarding banner. Click Start Onboarding to set your AI models and API key.

docs/setup/installation.md

@@ -25,6 +25,9 @@ docker run -p 80:80 agent0ai/agent-zero
 
 Once the install completes, open the URL shown in your terminal to access the Web UI. Follow the prompts in the CLI to set your port and authentication, complete onboarding, add your API key, then continue to [Step 3: Configure Agent Zero](#step-3-configure-agent-zero).
 
+> [!TIP]
+> Prefer a terminal-native workflow too? Install the optional [A0 CLI Connector](../guides/a0-cli-connector.md) from GitHub, then run `a0` to connect to this Agent Zero instance from your terminal.
+
 ---
 
 ## How to Update Agent Zero

extensions/python/message_loop_prompts_after/_63_recall_relevant_skills.py

@@ -0,0 +1,39 @@
+from agent import LoopData
+from helpers.extension import Extension
+from helpers import skills as skills_helper
+
+
+class RecallRelevantSkills(Extension):
+    async def execute(self, loop_data: LoopData = LoopData(), **kwargs):
+        if not self.agent or loop_data.iteration != 0:
+            return
+
+        user_instruction = (
+            loop_data.user_message.output_text() if loop_data.user_message else ""
+        ).strip()
+        if len(user_instruction) < 8:
+            return
+
+        matches = skills_helper.search_skills(
+            user_instruction,
+            limit=6,
+            agent=self.agent,
+        )
+        if not matches:
+            return
+
+        lines: list[str] = []
+        for skill in matches:
+            name = skill.name.strip().replace("\n", " ")[:100]
+            desc = (skill.description or "").replace("\n", " ").strip()
+            if len(desc) > 220:
+                desc = desc[:220].rstrip() + "…"
+            lines.append(f"- {name}: {desc}")
+
+        if not lines:
+            return
+
+        loop_data.extras_temporary["relevant_skills"] = self.agent.read_prompt(
+            "agent.system.skills.relevant.md",
+            skills="\n".join(lines),
+        )

helpers/skills.py

@@ -450,23 +450,43 @@ def search_skills(
     if not q:
         return []
 
-    terms = [t for t in re.split(r"\s+", q) if t]
+    raw_terms = [t for t in re.split(r"\s+", q) if t]
+    terms = [
+        t for t in raw_terms
+        if len(t) >= 3 or any(ch.isdigit() for ch in t)
+    ] or raw_terms
     candidates = list_skills(agent)
 
     scored: List[Tuple[int, Skill]] = []
     for s in candidates:
         name = s.name.lower()
         desc = (s.description or "").lower()
         tags = [t.lower() for t in s.tags]
+        triggers = [t.lower() for t in s.triggers]
 
         score = 0
+        if q == name:
+            score += 10
+        if any(q == trigger for trigger in triggers):
+            score += 9
+        if q in name:
+            score += 6
+        if q in desc:
+            score += 4
+        if any(q in tag for tag in tags):
+            score += 3
+        if any(q in trigger for trigger in triggers):
+            score += 8
+
         for term in terms:
             if term in name:
                 score += 3
             if term in desc:
                 score += 2
             if any(term in tag for tag in tags):
                 score += 1
+            if any(term in trigger for trigger in triggers):
+                score += 4
 
         if score > 0:
             scored.append((score, s))
@@ -524,4 +544,3 @@ def validate_skill_md(skill_md_path: Path) -> List[str]:
     if not skill:
         return ["Unable to parse SKILL.md frontmatter"]
     return validate_skill(skill)
-

helpers/skills_cli.py

@@ -42,10 +42,19 @@ class Skill:
 def get_skills_dirs() -> List[Path]:
     """Get all skill directories"""
     base = Path(files.get_abs_path("usr", "skills"))
-    return [
+    roots = [
+        Path(files.get_abs_path("skills")),
+        base,
         base / "custom",
         base / "default",
     ]
+    seen: set[Path] = set()
+    ordered: List[Path] = []
+    for root in roots:
+        if root not in seen:
+            seen.add(root)
+            ordered.append(root)
+    return ordered
 
 
 def parse_skill_file(skill_path: Path) -> Optional[Skill]:

prompts/agent.system.skills.md

@@ -1,3 +1,4 @@
 ## skills
-use `skills_tool:list` to discover skills when specialized instructions may help
+use `skills_tool:search` when the user's wording sounds like a task, trigger phrase, or keyword match for a skill
+use `skills_tool:list` when you need a broader catalog view
 use `skills_tool:load` before following a skill

prompts/agent.system.skills.relevant.md

@@ -0,0 +1,5 @@
+# relevant skills
+- the following skills matched the user's current request by lexical search, including trigger phrases
+- use `skills_tool:load` to load one before following it
+
+{{skills}}

prompts/agent.system.tool.skills.md

@@ -1,18 +1,19 @@
 ### skills_tool
 use skills only when relevant
 workflow:
+- `skills_tool:search`: find candidate skills by keywords or trigger phrases from the current task
 - `skills_tool:list`: discover available skills
 - `skills_tool:load`: load one skill by `skill_name`
 after loading a skill, follow its instructions and use referenced files or scripts with other tools
 reload a skill if its instructions are no longer in context
 example:
 ~~~json
 {
-  "thoughts": ["A skill may already encode the workflow I need."],
-  "headline": "Loading relevant skill",
-  "tool_name": "skills_tool:load",
+  "thoughts": ["The user's request sounds like a skill trigger phrase, so I should search first."],
+  "headline": "Searching for relevant skill",
+  "tool_name": "skills_tool:search",
   "tool_args": {
-    "skill_name": "playwright"
+    "query": "set up a0 cli connector"
   }
 }
 ~~~