web-agent

Use when shell commands fail, npx/curl/git won't run, or you must choose run_shell vs web_fetch vs file tools in Nodebox vs host.

Use when the user says remember this, save a preference or API key, or you must pick memory_save vs session notes vs skill (action=manage) vs wiki_* tools.

Use when the input is an image, screenshot, diagram, PDF/DOCX, audio file, or YouTube link—extract metadata/text before reasoning.

Use when the user wants to discover, search, or install agent skills from online registries—top results by installs, stars, or votes. Or user sends /find_skills.

Use when calling REST or GraphQL APIs with web_fetch/web_post — auth headers, query params, GraphQL shape, Directus GraphQL mutations/relations, discovery order, and reading error bodies.

Use when the user or agent installs a skill from skills.sh or GitHub — map WebFetch, Bash, Python, Playwright, and MCP references to Web Agent built-ins.

Use when starting a new app, demo, spike, starter, or multi-file project—make_dir under projects/ or work/ before any writes.

Use when writing or fixing Python for run_python — browser WASM Pyodide contract, forbidden APIs, package substitutes, and webagent.http.

Use when the user reports a bug, error, flaky test, crash, regression, or "it doesn't work"—hypothesis-first debugging before random edits.

Use when fixing or extending Web Agent itself—runtime, bundled skills, capabilities, adapter, or self-evolution of this repo.

Use when the user wants backup, export, checkpoint, or before bulk deletes, rm -rf, or wide refactors.

Use when the user asks to connect, add, or configure an MCP server (Directus, a Hub URL, a streamable-HTTP/SSE endpoint, or a stdio command). Covers the exact .webagent/mcp-servers.json + mcp-secrets.json schema and how tools reload.

Use when finished work must be shown to the user—or when they ask to see/display a visual—artifact_present for files, inline markdown with remote image URLs, terminal preview, email or Telegram delivery.

Use when intent is ambiguous or conflicting—emit one <<<CLARIFY>>> block (option buttons in UI, no tools). Or user sends /clarify.

Use when connecting OAuth-backed SaaS apps (Gmail, Calendar, Sheets, HubSpot, Slack, X, LinkedIn, Instagram) or calling curated Composio actions.

Use when a visual would clarify a plan, flow, or report — ```mermaid fences plus artifact_present View popup for SVG (GitHub-style).

Use when the user wants scheduled jobs, daily digests, recurring reminders, or cron_register—not host crontab or shell pipelines.

Use when the user wants to find, list, or discover people, creators, companies, or content on the open web—search many queries, fetch URLs, then synthesize.

Use when the user wants papers, arXiv, citations, literature review, or Semantic Scholar—not general creator or product discovery.

Use when the user wants tables, lists, or JSON pulled from fetched pages, feeds, or APIs—web_fetch then parse cleanly.

Use when a multi-step goal needs decomposition and end-to-end delivery—todo_write plan, one-at-a-time execution, failure recovery, and a final report.