zubo 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (222) hide show
  1. package/.github/workflows/ci.yml +35 -0
  2. package/README.md +149 -0
  3. package/bun.lock +216 -0
  4. package/desktop/README.md +57 -0
  5. package/desktop/package.json +12 -0
  6. package/desktop/src-tauri/Cargo.toml +25 -0
  7. package/desktop/src-tauri/build.rs +3 -0
  8. package/desktop/src-tauri/icons/README.md +17 -0
  9. package/desktop/src-tauri/icons/icon.png +0 -0
  10. package/desktop/src-tauri/src/main.rs +189 -0
  11. package/desktop/src-tauri/tauri.conf.json +68 -0
  12. package/docs/ROADMAP.md +490 -0
  13. package/migrations/001_init.sql +9 -0
  14. package/migrations/002_memory.sql +33 -0
  15. package/migrations/003_cron.sql +24 -0
  16. package/migrations/004_usage.sql +12 -0
  17. package/migrations/005_secrets.sql +8 -0
  18. package/migrations/006_agents.sql +1 -0
  19. package/migrations/007_workflows.sql +22 -0
  20. package/migrations/008_proactive.sql +24 -0
  21. package/migrations/009_uploads.sql +9 -0
  22. package/migrations/010_observability.sql +22 -0
  23. package/migrations/011_api_keys.sql +7 -0
  24. package/migrations/012_indexes.sql +5 -0
  25. package/migrations/013_budget.sql +11 -0
  26. package/migrations/014_usage_session_idx.sql +2 -0
  27. package/package.json +39 -0
  28. package/site/404.html +156 -0
  29. package/site/CNAME +1 -0
  30. package/site/docs/agents.html +294 -0
  31. package/site/docs/api.html +446 -0
  32. package/site/docs/channels.html +345 -0
  33. package/site/docs/cli.html +238 -0
  34. package/site/docs/config.html +1034 -0
  35. package/site/docs/index.html +433 -0
  36. package/site/docs/integrations.html +381 -0
  37. package/site/docs/memory.html +254 -0
  38. package/site/docs/security.html +375 -0
  39. package/site/docs/skills.html +322 -0
  40. package/site/docs.css +412 -0
  41. package/site/index.html +638 -0
  42. package/site/install.sh +98 -0
  43. package/site/logo.svg +1 -0
  44. package/site/og-image.png +0 -0
  45. package/site/robots.txt +4 -0
  46. package/site/script.js +361 -0
  47. package/site/sitemap.xml +63 -0
  48. package/site/skills.html +532 -0
  49. package/site/style.css +1686 -0
  50. package/src/agent/agents.ts +159 -0
  51. package/src/agent/compaction.ts +53 -0
  52. package/src/agent/context.ts +18 -0
  53. package/src/agent/delegate.ts +118 -0
  54. package/src/agent/loop.ts +318 -0
  55. package/src/agent/prompts.ts +111 -0
  56. package/src/agent/session.ts +87 -0
  57. package/src/agent/teams.ts +116 -0
  58. package/src/agent/workflow-executor.ts +192 -0
  59. package/src/agent/workflow.ts +175 -0
  60. package/src/channels/adapter.ts +21 -0
  61. package/src/channels/dashboard.html.ts +2969 -0
  62. package/src/channels/discord.ts +137 -0
  63. package/src/channels/optional-deps.d.ts +17 -0
  64. package/src/channels/router.ts +199 -0
  65. package/src/channels/signal.ts +133 -0
  66. package/src/channels/slack.ts +101 -0
  67. package/src/channels/telegram.ts +102 -0
  68. package/src/channels/utils.ts +18 -0
  69. package/src/channels/webchat.ts +1797 -0
  70. package/src/channels/whatsapp.ts +119 -0
  71. package/src/config/loader.ts +22 -0
  72. package/src/config/paths.ts +43 -0
  73. package/src/config/schema.ts +121 -0
  74. package/src/db/connection.ts +20 -0
  75. package/src/db/export.ts +148 -0
  76. package/src/db/migrations.ts +42 -0
  77. package/src/index.ts +261 -0
  78. package/src/llm/claude.ts +193 -0
  79. package/src/llm/factory.ts +115 -0
  80. package/src/llm/failover.ts +101 -0
  81. package/src/llm/openai-compat.ts +409 -0
  82. package/src/llm/provider.ts +83 -0
  83. package/src/llm/smart-router.ts +241 -0
  84. package/src/logs.ts +53 -0
  85. package/src/memory/chunker.ts +58 -0
  86. package/src/memory/document-parser.ts +115 -0
  87. package/src/memory/embedder.ts +235 -0
  88. package/src/memory/engine.ts +170 -0
  89. package/src/memory/fts-index.ts +55 -0
  90. package/src/memory/hybrid-search.ts +72 -0
  91. package/src/memory/store.ts +56 -0
  92. package/src/memory/vector-index.ts +72 -0
  93. package/src/model.ts +118 -0
  94. package/src/registry/cli.ts +43 -0
  95. package/src/registry/client.ts +54 -0
  96. package/src/registry/installer.ts +67 -0
  97. package/src/scheduler/briefing.ts +71 -0
  98. package/src/scheduler/cron.ts +258 -0
  99. package/src/scheduler/heartbeat.ts +58 -0
  100. package/src/scheduler/memory-triggers.ts +100 -0
  101. package/src/scheduler/natural-cron.ts +163 -0
  102. package/src/scheduler/proactive.ts +25 -0
  103. package/src/scheduler/recipes.ts +110 -0
  104. package/src/secrets/store.ts +64 -0
  105. package/src/setup.ts +413 -0
  106. package/src/skills.ts +293 -0
  107. package/src/start.ts +373 -0
  108. package/src/status.ts +165 -0
  109. package/src/tools/builtin/connect-service.ts +205 -0
  110. package/src/tools/builtin/cron.ts +126 -0
  111. package/src/tools/builtin/datetime.ts +36 -0
  112. package/src/tools/builtin/delegate-task.ts +81 -0
  113. package/src/tools/builtin/delegate.ts +42 -0
  114. package/src/tools/builtin/diagnose.ts +41 -0
  115. package/src/tools/builtin/google-oauth.ts +379 -0
  116. package/src/tools/builtin/manage-agents.ts +149 -0
  117. package/src/tools/builtin/manage-skills.ts +294 -0
  118. package/src/tools/builtin/manage-teams.ts +89 -0
  119. package/src/tools/builtin/manage-triggers.ts +94 -0
  120. package/src/tools/builtin/manage-workflows.ts +119 -0
  121. package/src/tools/builtin/memory-search.ts +38 -0
  122. package/src/tools/builtin/memory-write.ts +30 -0
  123. package/src/tools/builtin/run-workflow.ts +36 -0
  124. package/src/tools/builtin/secrets.ts +122 -0
  125. package/src/tools/builtin/skill-registry.ts +75 -0
  126. package/src/tools/builtin-integrations/api-helpers.ts +26 -0
  127. package/src/tools/builtin-integrations/github/github_issues/SKILL.md +56 -0
  128. package/src/tools/builtin-integrations/github/github_issues/handler.ts +108 -0
  129. package/src/tools/builtin-integrations/github/github_prs/SKILL.md +57 -0
  130. package/src/tools/builtin-integrations/github/github_prs/handler.ts +113 -0
  131. package/src/tools/builtin-integrations/github/github_repos/SKILL.md +37 -0
  132. package/src/tools/builtin-integrations/github/github_repos/handler.ts +88 -0
  133. package/src/tools/builtin-integrations/google/gmail/SKILL.md +51 -0
  134. package/src/tools/builtin-integrations/google/gmail/handler.ts +125 -0
  135. package/src/tools/builtin-integrations/google/google_calendar/SKILL.md +35 -0
  136. package/src/tools/builtin-integrations/google/google_calendar/handler.ts +105 -0
  137. package/src/tools/builtin-integrations/google/google_docs/SKILL.md +35 -0
  138. package/src/tools/builtin-integrations/google/google_docs/handler.ts +108 -0
  139. package/src/tools/builtin-integrations/google/google_drive/SKILL.md +39 -0
  140. package/src/tools/builtin-integrations/google/google_drive/handler.ts +106 -0
  141. package/src/tools/builtin-integrations/google/google_sheets/SKILL.md +36 -0
  142. package/src/tools/builtin-integrations/google/google_sheets/handler.ts +116 -0
  143. package/src/tools/builtin-integrations/jira/jira_boards/SKILL.md +21 -0
  144. package/src/tools/builtin-integrations/jira/jira_boards/handler.ts +74 -0
  145. package/src/tools/builtin-integrations/jira/jira_issues/SKILL.md +28 -0
  146. package/src/tools/builtin-integrations/jira/jira_issues/handler.ts +140 -0
  147. package/src/tools/builtin-integrations/linear/linear_issues/SKILL.md +30 -0
  148. package/src/tools/builtin-integrations/linear/linear_issues/handler.ts +75 -0
  149. package/src/tools/builtin-integrations/linear/linear_projects/SKILL.md +21 -0
  150. package/src/tools/builtin-integrations/linear/linear_projects/handler.ts +43 -0
  151. package/src/tools/builtin-integrations/notion/notion_databases/SKILL.md +39 -0
  152. package/src/tools/builtin-integrations/notion/notion_databases/handler.ts +83 -0
  153. package/src/tools/builtin-integrations/notion/notion_pages/SKILL.md +43 -0
  154. package/src/tools/builtin-integrations/notion/notion_pages/handler.ts +130 -0
  155. package/src/tools/builtin-integrations/notion/notion_search/SKILL.md +27 -0
  156. package/src/tools/builtin-integrations/notion/notion_search/handler.ts +69 -0
  157. package/src/tools/builtin-integrations/slack/slack_messages/SKILL.md +42 -0
  158. package/src/tools/builtin-integrations/slack/slack_messages/handler.ts +72 -0
  159. package/src/tools/builtin-integrations/twitter/twitter_posts/SKILL.md +24 -0
  160. package/src/tools/builtin-integrations/twitter/twitter_posts/handler.ts +133 -0
  161. package/src/tools/builtin-skills/file-read/SKILL.md +26 -0
  162. package/src/tools/builtin-skills/file-read/handler.ts +66 -0
  163. package/src/tools/builtin-skills/file-write/SKILL.md +30 -0
  164. package/src/tools/builtin-skills/file-write/handler.ts +64 -0
  165. package/src/tools/builtin-skills/http-request/SKILL.md +34 -0
  166. package/src/tools/builtin-skills/http-request/handler.ts +87 -0
  167. package/src/tools/builtin-skills/shell/SKILL.md +26 -0
  168. package/src/tools/builtin-skills/shell/handler.ts +96 -0
  169. package/src/tools/builtin-skills/url-fetch/SKILL.md +26 -0
  170. package/src/tools/builtin-skills/url-fetch/handler.ts +37 -0
  171. package/src/tools/builtin-skills/web-search/SKILL.md +26 -0
  172. package/src/tools/builtin-skills/web-search/handler.ts +50 -0
  173. package/src/tools/executor.ts +205 -0
  174. package/src/tools/integration-installer.ts +106 -0
  175. package/src/tools/permissions.ts +45 -0
  176. package/src/tools/registry.ts +39 -0
  177. package/src/tools/sandbox-runner.ts +56 -0
  178. package/src/tools/sandbox.ts +82 -0
  179. package/src/tools/skill-installer.ts +52 -0
  180. package/src/tools/skill-loader.ts +259 -0
  181. package/src/types/optional-deps.d.ts +23 -0
  182. package/src/util/auth.ts +121 -0
  183. package/src/util/costs.ts +59 -0
  184. package/src/util/error-buffer.ts +32 -0
  185. package/src/util/google-tokens.ts +180 -0
  186. package/src/util/logger.ts +73 -0
  187. package/src/util/perf-collector.ts +35 -0
  188. package/src/util/rate-limiter.ts +70 -0
  189. package/src/util/tokens.ts +17 -0
  190. package/src/voice/stt.ts +57 -0
  191. package/src/voice/tts.ts +103 -0
  192. package/tests/agent/session.test.ts +109 -0
  193. package/tests/agent-loop.test.ts +54 -0
  194. package/tests/auth.test.ts +89 -0
  195. package/tests/channels.test.ts +67 -0
  196. package/tests/compaction.test.ts +44 -0
  197. package/tests/config.test.ts +51 -0
  198. package/tests/costs.test.ts +19 -0
  199. package/tests/cron.test.ts +55 -0
  200. package/tests/db/export.test.ts +219 -0
  201. package/tests/executor.test.ts +144 -0
  202. package/tests/export.test.ts +137 -0
  203. package/tests/helpers/mock-llm.ts +34 -0
  204. package/tests/helpers/test-db.ts +74 -0
  205. package/tests/integration/chat-flow.test.ts +48 -0
  206. package/tests/integrations.test.ts +97 -0
  207. package/tests/memory/engine.test.ts +114 -0
  208. package/tests/memory-engine.test.ts +57 -0
  209. package/tests/permissions.test.ts +21 -0
  210. package/tests/rate-limiter.test.ts +70 -0
  211. package/tests/registry.test.ts +67 -0
  212. package/tests/router.test.ts +36 -0
  213. package/tests/session.test.ts +58 -0
  214. package/tests/skill-loader.test.ts +44 -0
  215. package/tests/tokens.test.ts +30 -0
  216. package/tests/tools/executor.test.ts +130 -0
  217. package/tests/util/auth.test.ts +75 -0
  218. package/tests/util/rate-limiter.test.ts +73 -0
  219. package/tests/voice.test.ts +60 -0
  220. package/tests/webchat.test.ts +88 -0
  221. package/tests/workflow.test.ts +38 -0
  222. package/tsconfig.json +16 -0
package/site/docs/skills.html ADDED
@@ -0,0 +1,322 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>Skills — Zubo Docs</title>
7
+ <meta name="description" content="Build custom skills for Zubo. Single-file TypeScript tools that extend your AI agent's capabilities with hot-loading and sandboxed execution.">
8
+ <meta name="theme-color" content="#060608">
9
+ <link rel="canonical" href="https://zubo.bot/docs/skills.html">
10
+ <meta property="og:title" content="Skills — Zubo Docs">
11
+ <meta property="og:description" content="Build custom skills for Zubo. Single-file TypeScript tools with hot-loading and sandboxed execution.">
12
+ <meta property="og:type" content="article">
13
+ <meta property="og:url" content="https://zubo.bot/docs/skills.html">
14
+ <meta property="og:image" content="https://zubo.bot/og-image.png">
15
+ <meta property="og:site_name" content="Zubo">
16
+ <meta name="twitter:card" content="summary_large_image">
17
+ <meta name="twitter:title" content="Skills — Zubo Docs">
18
+ <meta name="twitter:description" content="Build custom skills for Zubo. Single-file TypeScript tools with hot-loading and sandboxed execution.">
19
+ <meta name="twitter:image" content="https://zubo.bot/og-image.png">
20
+ <meta name="twitter:creator" content="@thomaskanze">
21
+ <link rel="preconnect" href="https://fonts.googleapis.com">
22
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
23
+ <link href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,600;12..96,700;12..96,800&family=DM+Sans:ital,opsz,wght@0,9..40,400;0,9..40,500;0,9..40,600;0,9..40,700;1,9..40,400&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
24
+ <link rel="stylesheet" href="../style.css">
25
+ <link rel="stylesheet" href="../docs.css">
26
+ <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><rect width='100' height='100' rx='20' fill='%237c3aed'/><path d='M50 15C52 37 63 48 85 50C63 52 52 63 50 85C48 63 37 52 15 50C37 48 48 37 50 15Z' fill='white'/></svg>">
27
+ </head>
28
+ <body>
29
+
30
+ <header class="nav scrolled" id="nav">
31
+ <div class="nav-inner">
32
+ <a href="../index.html" class="nav-logo">
33
+ <span class="logo-wordmark">zubo</span>
34
+ </a>
35
+ <nav class="nav-links" id="nav-links">
36
+ <a href="../index.html#features">Features</a>
37
+ <a href="index.html" style="color:#fff;">Docs</a>
38
+ <a href="../skills.html">Skills</a>
39
+ <a href="../index.html#get-started">Get Started</a>
40
+ </nav>
41
+ <div class="nav-right">
42
+ <a href="https://github.com/apwn/zubo" class="nav-github" aria-label="GitHub">
43
+ <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>
44
+ </a>
45
+ <a href="../index.html#get-started" class="btn btn-primary btn-nav">Get Started</a>
46
+ <button class="nav-toggle" id="nav-toggle" aria-label="Toggle menu">
47
+ <span></span><span></span><span></span>
48
+ </button>
49
+ </div>
50
+ </div>
51
+ </header>
52
+
53
+ <div class="docs-layout">
54
+ <aside class="docs-sidebar" id="docs-sidebar">
55
+ <div class="docs-sidebar-section">
56
+ <div class="docs-sidebar-heading">Getting Started</div>
57
+ <div class="docs-sidebar-links">
58
+ <a href="index.html">Overview</a>
59
+ <a href="config.html">Configuration</a>
60
+ </div>
61
+ </div>
62
+ <div class="docs-sidebar-section">
63
+ <div class="docs-sidebar-heading">Core Concepts</div>
64
+ <div class="docs-sidebar-links">
65
+ <a href="agents.html">Agents &amp; Workflows</a>
66
+ <a href="memory.html">Memory System</a>
67
+ <a href="skills.html" class="active">Skills</a>
68
+ </div>
69
+ </div>
70
+ <div class="docs-sidebar-section">
71
+ <div class="docs-sidebar-heading">Guides</div>
72
+ <div class="docs-sidebar-links">
73
+ <a href="channels.html">Channel Setup</a>
74
+ <a href="integrations.html">Integrations</a>
75
+ <a href="security.html">Security &amp; Auth</a>
76
+ </div>
77
+ </div>
78
+ <div class="docs-sidebar-section">
79
+ <div class="docs-sidebar-heading">Reference</div>
80
+ <div class="docs-sidebar-links">
81
+ <a href="api.html">API Reference</a>
82
+ <a href="cli.html">CLI Commands</a>
83
+ </div>
84
+ </div>
85
+ </aside>
86
+
87
+ <main class="docs-content">
88
+ <div class="docs-breadcrumb">
89
+ <a href="../index.html">Home</a>
90
+ <span>/</span>
91
+ <a href="index.html">Docs</a>
92
+ <span>/</span>
93
+ Skills
94
+ </div>
95
+
96
+ <h1>Skills</h1>
97
+ <p>Skills are user-created tools that extend Zubo's capabilities. Each skill is a single TypeScript file that the agent can invoke during conversations to perform actions, fetch data, or interact with external services. Skills are hot-loaded &mdash; you can add, edit, or remove them without restarting Zubo. User-installed skills run in sandboxed subprocesses for security, ensuring they cannot access Zubo's internal state or database.</p>
98
+
99
+ <h2>Quick Start</h2>
100
+ <p>The fastest way to create a skill is with the built-in scaffolding command:</p>
101
+ <pre><code>zubo skills new</code></pre>
102
+ <p>This interactive wizard walks you through choosing a name, writing a description, and defining parameters. It generates a ready-to-use <code>handler.ts</code> file in your skills directory.</p>
103
+ <p>Even easier &mdash; just tell Zubo what you need in plain language:</p>
104
+ <pre><code>"Build a skill that checks the weather for a location"</code></pre>
105
+ <p>Zubo will generate the entire skill file for you, including parameter definitions, error handling, and a working implementation. You can then refine it by chatting: <em>"Add a units parameter that accepts celsius or fahrenheit."</em></p>
106
+
107
+ <h2>Single-File Format</h2>
108
+ <p>Every skill is a single TypeScript file with two exports: a <code>skill</code> configuration object and a default handler function. Here is a complete example:</p>
109
+ <pre><code>export const skill = {
110
+ name: "weather",
111
+ description: "Get current weather for a location",
112
+ params: {
113
+ location: { type: "string", description: "City or coordinates", required: true },
114
+ units: { type: "string", description: "celsius or fahrenheit" }
115
+ }
116
+ };
117
+
118
+ export default async function (input: Record&lt;string, unknown&gt;): Promise&lt;string&gt; {
119
+ const location = input.location as string;
120
+ const units = (input.units as string) || "metric";
121
+ const res = await fetch(`https://api.example.com/weather?q=${location}&amp;units=${units}`);
122
+ return JSON.stringify(await res.json());
123
+ }</code></pre>
124
+ <p>The <code>skill</code> object tells the AI what this tool does and what parameters it accepts. The default export is the function that runs when the skill is invoked. This is all you need &mdash; no boilerplate, no build step, no configuration files.</p>
125
+
126
+ <h2>Skill Config</h2>
127
+ <p>The exported <code>skill</code> object defines metadata that Zubo uses to register the tool with the LLM:</p>
128
+ <table>
129
+ <thead>
130
+ <tr><th>Field</th><th>Required</th><th>Description</th></tr>
131
+ </thead>
132
+ <tbody>
133
+ <tr><td><code>name</code></td><td>Yes</td><td>Unique identifier. Lowercase letters, numbers, and underscores only (<code>[a-z0-9_]+</code>). This is how the AI references your skill internally.</td></tr>
134
+ <tr><td><code>description</code></td><td>Yes</td><td>A natural-language explanation shown to the AI. The LLM uses this to decide when to invoke your skill, so be specific and descriptive.</td></tr>
135
+ <tr><td><code>params</code></td><td>No</td><td>An object mapping parameter names to their definitions (see Params Format below). If omitted, the skill accepts no parameters.</td></tr>
136
+ </tbody>
137
+ </table>
138
+
139
+ <h2>Params Format</h2>
140
+ <p>Each key in the <code>params</code> object is a parameter name. The value is an object with the following fields:</p>
141
+ <table>
142
+ <thead>
143
+ <tr><th>Field</th><th>Type</th><th>Description</th></tr>
144
+ </thead>
145
+ <tbody>
146
+ <tr><td><code>type</code></td><td>string</td><td>The data type: <code>"string"</code>, <code>"number"</code>, or <code>"boolean"</code>. Determines how the LLM formats the argument.</td></tr>
147
+ <tr><td><code>description</code></td><td>string</td><td>Explains what this parameter does. Shown to the AI to help it provide the correct value.</td></tr>
148
+ <tr><td><code>required</code></td><td>boolean</td><td>Whether the parameter must be provided. Defaults to <code>false</code> if omitted.</td></tr>
149
+ </tbody>
150
+ </table>
151
+ <p>The params are automatically converted to JSON Schema and passed to the LLM as part of the tool definition. You do not need to write JSON Schema yourself &mdash; Zubo handles the conversion.</p>
152
+
153
+ <h2>Handler Function</h2>
154
+ <p>The handler is the default export of your skill file. It is the function that executes when the AI decides to use your skill.</p>
155
+ <ul>
156
+ <li><strong>Must be the default export</strong> &mdash; use <code>export default async function</code></li>
157
+ <li><strong>Signature:</strong> <code>async (input: Record&lt;string, unknown&gt;) =&gt; Promise&lt;string&gt;</code></li>
158
+ <li><strong>Must return a string</strong> &mdash; JSON is recommended for structured data. If the handler returns a non-string value, Zubo will automatically coerce it to JSON via <code>JSON.stringify()</code>.</li>
159
+ <li><strong>Access params</strong> via <code>input.paramName</code> &mdash; cast to the appropriate type as needed (e.g., <code>input.location as string</code>)</li>
160
+ <li><strong>Available APIs:</strong> <code>fetch()</code>, Bun APIs, built-in Node/Bun modules (<code>fs</code>, <code>path</code>, <code>crypto</code>, etc.)</li>
161
+ <li><strong>Cannot import from Zubo internals</strong> &mdash; skills run in a sandboxed subprocess and have no access to Zubo's core modules, database, or session state</li>
162
+ </ul>
163
+
164
+ <h2>Accessing Secrets</h2>
165
+ <p>Skills often need API keys or credentials to call external services. Zubo provides a secure way to pass secrets to skill handlers via environment variables:</p>
166
+ <pre><code>export default async function (input: Record&lt;string, unknown&gt;): Promise&lt;string&gt; {
167
+ const apiKey = process.env.ZUBO_SECRET_WEATHER_API_KEY;
168
+ if (!apiKey) return JSON.stringify({ error: "Weather API key not configured" });
169
+
170
+ const location = input.location as string;
171
+ const res = await fetch(
172
+ `https://api.weatherapi.com/v1/current.json?key=${apiKey}&amp;q=${location}`
173
+ );
174
+ return JSON.stringify(await res.json());
175
+ }</code></pre>
176
+ <p>Secrets referenced in the handler code are automatically passed to the sandboxed subprocess as environment variables with the <code>ZUBO_SECRET_</code> prefix. Only the secrets that your handler actually references are injected &mdash; other secrets are not exposed.</p>
177
+ <p>Set secrets via the dashboard or by telling Zubo in chat:</p>
178
+ <pre><code>"Store my weather API key: abc123"</code></pre>
179
+ <p>You can also use the CLI: <code>zubo secrets set WEATHER_API_KEY abc123</code></p>
180
+
181
+ <h2>Skill Directory Structure</h2>
182
+ <p>All skills live under the Zubo workspace directory. Each skill gets its own folder containing a <code>handler.ts</code> file:</p>
183
+ <pre><code>~/.zubo/workspace/skills/
184
+ ├── weather/
185
+ │ └── handler.ts # Single-file skill
186
+ ├── calculator/
187
+ │ ├── SKILL.md # Legacy format (still supported)
188
+ │ └── handler.ts
189
+ ├── email_sender/
190
+ │ └── handler.ts
191
+ └── stock_price/
192
+ └── handler.ts</code></pre>
193
+ <p>When Zubo starts (or when a skill is added/modified), it scans this directory and hot-loads all valid skills. You can manually place files here or use <code>zubo skills new</code> to scaffold them.</p>
194
+
195
+ <h2>Sandbox Behavior</h2>
196
+ <p>Security is a core concern when running user-authored code. Zubo enforces the following sandbox rules for user-installed skills:</p>
197
+ <ul>
198
+ <li><strong>Isolated subprocesses</strong> &mdash; each skill invocation runs in its own Bun subprocess, fully isolated from the main Zubo process</li>
199
+ <li><strong>30-second timeout</strong> &mdash; skills are killed after 30 seconds by default. Configure this via <code>sandbox.timeoutMs</code> in your config</li>
200
+ <li><strong>Minimal secrets</strong> &mdash; only secrets that the handler code explicitly references (via <code>process.env.ZUBO_SECRET_*</code>) are passed to the subprocess</li>
201
+ <li><strong>No internal access</strong> &mdash; sandboxed skills cannot access Zubo's database, session state, memory store, or any other internal APIs</li>
202
+ <li><strong>Built-in tools are NOT sandboxed</strong> &mdash; tools like <code>get_current_datetime</code>, <code>memory_write</code>, <code>memory_search</code>, and other built-in tools run in the main process. Only user-created and registry-installed skills are sandboxed.</li>
203
+ </ul>
204
+
205
+ <h2>Skill Registry</h2>
206
+ <p>The Zubo skill registry is a community-driven marketplace where you can discover, install, and publish skills:</p>
207
+ <ul>
208
+ <li><strong>Browse skills:</strong> <code>zubo search &lt;query&gt;</code> or use the dashboard's Skills tab</li>
209
+ <li><strong>Install a skill:</strong> <code>zubo install &lt;skill-name&gt;</code> or click "Install" in the dashboard</li>
210
+ <li><strong>Publish your skill:</strong> <code>zubo publish &lt;skill-name&gt;</code> to share it with the community</li>
211
+ <li><strong>Automatic sandboxing:</strong> all registry-installed skills are sandboxed by default, just like locally created skills</li>
212
+ </ul>
213
+ <p>You can also browse and install skills by chatting with Zubo: <em>"Search for a skill that sends emails"</em> or <em>"Install the github_issues skill."</em></p>
214
+
215
+ <h2>Managing Skills</h2>
216
+ <p>Use the CLI to manage your installed skills:</p>
217
+ <pre><code>zubo skills list # List all installed skills
218
+ zubo skills new # Create a new skill interactively
219
+ zubo skills remove # Remove an installed skill
220
+ zubo install weather # Install a skill from the registry
221
+ zubo search "email" # Search the registry for skills
222
+ zubo publish my_skill # Publish your skill to the registry</code></pre>
223
+ <p>Or manage skills conversationally by telling Zubo:</p>
224
+ <ul>
225
+ <li><em>"List my skills"</em></li>
226
+ <li><em>"Remove the weather skill"</em></li>
227
+ <li><em>"Build a skill that converts currencies"</em></li>
228
+ <li><em>"Search for a skill that checks DNS records"</em></li>
229
+ </ul>
230
+
231
+ <h2>Built-in Tools Reference</h2>
232
+ <p>Zubo ships with a comprehensive set of built-in tools that are always available. These are not sandboxed &mdash; they run in the main process and have full access to Zubo's internals.</p>
233
+ <table>
234
+ <thead>
235
+ <tr><th>Tool</th><th>Description</th><th>Permission</th></tr>
236
+ </thead>
237
+ <tbody>
238
+ <tr><td><code>get_current_datetime</code></td><td>Get current date and time with timezone</td><td>auto</td></tr>
239
+ <tr><td><code>memory_write</code></td><td>Save a fact or note to persistent memory</td><td>auto</td></tr>
240
+ <tr><td><code>memory_search</code></td><td>Search memory using semantic and full-text search</td><td>auto</td></tr>
241
+ <tr><td><code>manage_skills</code></td><td>Create, list, or remove user skills</td><td>auto</td></tr>
242
+ <tr><td><code>secret_set</code></td><td>Store a secret (API key, token, etc.)</td><td>auto</td></tr>
243
+ <tr><td><code>secret_list</code></td><td>List all stored secret names</td><td>auto</td></tr>
244
+ <tr><td><code>secret_delete</code></td><td>Delete a stored secret</td><td>confirm</td></tr>
245
+ <tr><td><code>cron_create</code></td><td>Create a scheduled task (cron job)</td><td>auto</td></tr>
246
+ <tr><td><code>cron_list</code></td><td>List all scheduled tasks</td><td>auto</td></tr>
247
+ <tr><td><code>cron_delete</code></td><td>Delete a scheduled task</td><td>auto</td></tr>
248
+ <tr><td><code>connect_service</code></td><td>Connect an external integration (GitHub, Google, etc.)</td><td>auto</td></tr>
249
+ <tr><td><code>delegate</code></td><td>Delegate a task to a sub-agent</td><td>auto</td></tr>
250
+ <tr><td><code>manage_agents</code></td><td>Create, list, or remove sub-agents</td><td>auto</td></tr>
251
+ <tr><td><code>manage_workflows</code></td><td>Create and manage multi-step workflows</td><td>auto</td></tr>
252
+ <tr><td><code>manage_teams</code></td><td>Manage agent teams and coordination</td><td>auto</td></tr>
253
+ <tr><td><code>manage_triggers</code></td><td>Manage proactive triggers and alerts</td><td>auto</td></tr>
254
+ <tr><td><code>run_workflow</code></td><td>Execute a defined workflow</td><td>auto</td></tr>
255
+ <tr><td><code>skill_registry</code></td><td>Search and install skills from the registry</td><td>auto</td></tr>
256
+ <tr><td><code>shell</code></td><td>Execute shell commands on the host system</td><td>confirm</td></tr>
257
+ <tr><td><code>file_read</code></td><td>Read the contents of a file</td><td>auto</td></tr>
258
+ <tr><td><code>file_write</code></td><td>Write or append content to a file</td><td>confirm</td></tr>
259
+ <tr><td><code>web_search</code></td><td>Search the web via DuckDuckGo</td><td>auto</td></tr>
260
+ <tr><td><code>url_fetch</code></td><td>Fetch and extract content from a web page</td><td>auto</td></tr>
261
+ <tr><td><code>http_request</code></td><td>Make a generic HTTP request (GET, POST, etc.)</td><td>auto</td></tr>
262
+ </tbody>
263
+ </table>
264
+ <p>Tools marked <strong>confirm</strong> require user confirmation before execution. Tools marked <strong>auto</strong> run immediately without prompting.</p>
265
+
266
+ <h2>Legacy Format (SKILL.md)</h2>
267
+ <p>Earlier versions of Zubo used a Markdown-based skill definition file called <code>SKILL.md</code>. This format is still fully supported for backward compatibility:</p>
268
+ <pre><code># weather
269
+ Get current weather for a location.
270
+
271
+ ## Input Schema
272
+ ```json
273
+ {
274
+ "type": "object",
275
+ "properties": {
276
+ "location": { "type": "string", "description": "City or coordinates" }
277
+ },
278
+ "required": ["location"]
279
+ }
280
+ ```</code></pre>
281
+ <p>If both a <code>SKILL.md</code> file and an exported <code>skill</code> configuration object exist in the same skill directory, the <code>SKILL.md</code> definition takes precedence. For new skills, the inline <code>export const skill</code> format is recommended as it keeps everything in a single file.</p>
282
+
283
+ <h2>Best Practices</h2>
284
+ <ul>
285
+ <li><strong>Keep skills focused</strong> &mdash; one tool, one purpose. A skill that does too many things makes it harder for the AI to know when to use it.</li>
286
+ <li><strong>Write clear descriptions</strong> &mdash; the AI relies on your description to decide when to invoke the skill. Be specific: <em>"Get current weather for a city"</em> is better than <em>"Weather stuff."</em></li>
287
+ <li><strong>Return JSON strings</strong> for structured data &mdash; this makes it easy for the AI to parse and present results to the user.</li>
288
+ <li><strong>Handle errors gracefully</strong> &mdash; return error messages as JSON strings instead of throwing exceptions. For example: <code>return JSON.stringify({ error: "API key not configured" })</code></li>
289
+ <li><strong>Use <code>process.env</code> for API keys</strong> &mdash; never hardcode secrets in your skill files. Use <code>ZUBO_SECRET_*</code> environment variables.</li>
290
+ <li><strong>Test by chatting</strong> &mdash; the easiest way to test a skill is to ask Zubo to use it: <em>"Use the weather skill for London"</em></li>
291
+ <li><strong>Keep response sizes reasonable</strong> &mdash; extremely large responses consume context window tokens. Summarize or paginate when dealing with large datasets.</li>
292
+ </ul>
293
+
294
+ <div class="docs-page-nav">
295
+ <a href="memory.html">
296
+ <span class="nav-dir">Previous</span>
297
+ <span class="nav-label">&larr; Memory System</span>
298
+ </a>
299
+ <a href="channels.html">
300
+ <span class="nav-dir">Next</span>
301
+ <span class="nav-label">Channel Setup &rarr;</span>
302
+ </a>
303
+ </div>
304
+ </main>
305
+ </div>
306
+
307
+ <button class="docs-sidebar-toggle" id="docs-sidebar-toggle" aria-label="Toggle sidebar">&#9776;</button>
308
+
309
+ <script src="../script.js"></script>
310
+ <script type="application/ld+json">
311
+ {
312
+ "@context": "https://schema.org",
313
+ "@type": "BreadcrumbList",
314
+ "itemListElement": [
315
+ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://zubo.bot/" },
316
+ { "@type": "ListItem", "position": 2, "name": "Docs", "item": "https://zubo.bot/docs/" },
317
+ { "@type": "ListItem", "position": 3, "name": "Skills", "item": "https://zubo.bot/docs/skills.html" }
318
+ ]
319
+ }
320
+ </script>
321
+ </body>
322
+ </html>