@toolbeltai/skills 0.1.0

package/multi-agent-workspace/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: multi-agent-workspace
+description: >
+  Set up a shared Toolbelt workspace for multi-agent collaboration. Toolbelt is a
+  multi-modal data platform combining SQL analytics, vector search, and real-time
+  streaming. Uploads a document to a namespace, generates a shareable asset URL,
+  and emits connection instructions for a second agent to join the same workspace.
+  Use when two or more agents need to share data, or when handing off context
+  between sessions without duplicating ingestion work.
+license: MIT
+compatibility: >
+  Requires a Toolbelt account (provision free at https://toolbelt.ai) and an
+  MCP-compatible AI agent (Claude Code, Claude Desktop, or any client that
+  supports MCP server connections). MCP connection must be pre-established
+  before invocation.
+metadata:
+  author: toolbeltai
+  version: "1.0"
+  openclaw:
+    emoji: "🤝"
+    homepage: "https://toolbelt.ai/docs/multi-agent"
+    skillKey: "multi-agent-workspace"
+---
+
+Set up a shared Toolbelt workspace and generate collaboration artifacts for a
+second agent using Toolbelt MCP tools. Work through each phase in order without
+prompting for user input. On unrecoverable error, emit a structured failure and halt.
+
+## When Not To Use
+
+- For single-agent workflows where data sharing between agents is not needed.
+- When you only need to analyze data yourself — use `sql-analyst`, `streaming-analyst`, or `knowledge-graph` instead.
+
+## Invocation Parameters
+
+Extract these from the args string or conversation context before starting:
+
+| Parameter | Required | Description |
+|---|---|---|
+| `namespace_id` | No | UUID of target namespace. Auto-select if omitted and only one exists; fail if ambiguous. |
+| `document_content` | No | Raw text to upload as the shared document. Uses the embedded sample if omitted. |
+| `document_name` | No | Name for the shared document asset. Defaults to `shared-workspace-doc`. |
+| `expires_in_days` | No | Days until the share link expires. Defaults to `7`. |
+
+---
+
+## Default Sample Document
+
+If no `document_content` is provided, use this research briefing verbatim:
+
+```
+Project Aurora: Q1 Research Briefing
+
+This briefing summarizes findings from the Aurora team's Q1 initiative on
+sustainable materials for industrial packaging.
+
+Key findings:
+- Bio-composite material BX-14 achieved 87% tensile strength retention after
+  6 months in humid storage conditions, outperforming the baseline polymer by 22%.
+- Pilot production run at the Riverside facility yielded 94% defect-free units,
+  meeting the target threshold of 90% set by the operations team.
+- Cost per unit for BX-14 is currently $0.42, compared to $0.31 for the baseline.
+  The team projects cost parity by Q3 as production volume scales.
+
+Risks identified:
+- Supplier lead time for BX-14 precursors is 14 weeks, creating potential
+  inventory gaps if demand spikes. Procurement has been notified.
+- Field testing in sub-zero conditions (-15°C) is pending. Results expected by
+  end of April.
+
+Next steps:
+- Dr. Maya Patel (materials lead) to complete cold-weather field tests by April 30.
+- Operations team to submit revised unit cost forecast by April 15.
+- Executive review scheduled for May 8, presenting go/no-go recommendation for
+  full-scale production in Q3.
+
+Prepared by: Aurora Research Team
+Date: March 28, 2024
+Classification: Internal — Project Team Only
+```
+
+---
+
+## Phase 0: Verify Connection
+
+Call `get_semantic_names` (no arguments) immediately.
+
+- **If it succeeds:** proceed to Phase 1 using the returned namespaces.
+- **If it fails:** emit structured failure and halt.
+
+```
+FAILURE: Toolbelt MCP connection is not established.
+The MCP server must be connected before invoking this skill.
+See: https://toolbelt.ai/docs/mcp for setup instructions.
+```
+
+---
+
+## Phase 1: Resolve Namespace
+
+Use the namespaces returned from Phase 0.
+
+Resolution order:
+1. If `namespace_id` was provided as a parameter, use it directly.
+2. If only one namespace exists, use it.
+3. If multiple exist and no `namespace_id` was specified, emit structured failure and halt.
+
+```
+FAILURE: Multiple namespaces found and none specified.
+Available: [<list namespace display names and IDs>]
+Re-invoke with namespace_id=<uuid>.
+```
+
+Store the resolved `namespace_id` and the namespace display name — both appear in the RESULT.
+
+---
+
+## Phase 2: Upload Shared Document
+
+Resolve `document_content` (use parameter value or default sample above).
+Resolve `document_name` (use parameter value or default `shared-workspace-doc`).
+
+Call `toolbelt_save`:
+
+```json
+{
+  "asset_type": "document",
+  "namespace_id": "<namespace_id>",
+  "name": "<document_name>",
+  "file_name": "document.txt",
+  "content": "<document_content>",
+  "content_encoding": "text"
+}
+```
+
+Record the returned `asset_id` — it is required for `toolbelt_share` in Phase 4.
+
+---
+
+## Phase 3: Poll for Ingestion
+
+Call `toolbelt_jobs` with `{ "namespace_id": "<namespace_id>" }` every 10 seconds.
+
+Wait for the `ingest` job to reach `completed`. Typical duration: 15–60 seconds. Maximum wait: 3 minutes.
+
+If the job reaches `failed` or the timeout elapses, emit structured failure and halt:
+```
+FAILURE: Document ingestion did not complete.
+Job status: <last observed status>
+```
+
+---
+
+## Phase 4: Generate Share URL
+
+Call `toolbelt_share` with the `asset_id` from Phase 2:
+
+```json
+{
+  "namespace_id": "<namespace_id>",
+  "asset_id": "<asset_id>",
+  "expiresInDays": <expires_in_days or 7>
+}
+```
+
+Parse the response to extract:
+- `share_url`: the shareable download/view link for the document
+- `expires_at`: expiration date of the link (if returned)
+
+If the call fails, emit structured failure and halt:
+```
+FAILURE: toolbelt_share failed.
+Error: <error message>
+```
+
+---
+
+## Phase 5: Structured Output
+
+After all phases complete, emit a single structured result followed by
+second-agent connection instructions.
+
+```
+RESULT:
+  namespace_id: <uuid>
+  namespace_name: <display name>
+  document_name: <name of uploaded document>
+  asset_id: <uuid of the uploaded asset>
+  phases_run: [0, 1, 2, 3, 4]
+
+  share_url: <URL returned by toolbelt_share>
+  expires_in_days: <days until expiry>
+
+  second_agent_instructions:
+    connect_via: "MCP server configured to point at https://toolbelt.ai"
+    namespace_id: <uuid>
+    steps:
+      1. "Configure the MCP server with your Toolbelt API key"
+      2. "Pass namespace_id=<uuid> to scope the agent to this workspace"
+      3. "Call toolbelt_context to see the shared document in the namespace"
+      4. "Call toolbelt_search to ask questions about the shared document"
+    note: "Both agents share the same namespace — any document, table, or query
+           result one agent uploads is immediately visible to the other."
+```
+
+---
+
+## Tool Reference
+
+| Phase | Tool(s) |
+|---|---|
+| 0. Verify connection | `get_semantic_names` |
+| 1. Resolve namespace | (from Phase 0 result) |
+| 2. Upload document | `toolbelt_save` |
+| 3. Poll for ingestion | `toolbelt_jobs` |
+| 4. Generate share URL | `toolbelt_share` |
+| 5. Emit result | (structured output) |

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@toolbeltai/skills",
+  "version": "0.1.0",
+  "description": "Official Toolbelt skills for Claude Code and MCP agents — run-toolbelt, geo-analyst, knowledge-graph, sql-analyst, vector-search, streaming-analyst, multi-agent-workspace, data-blend.",
+  "license": "MIT",
+  "homepage": "https://toolbelt.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/toolbeltai/toolbelt-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/toolbeltai/toolbelt-skills/issues"
+  },
+  "author": "Toolbelt",
+  "keywords": [
+    "toolbelt",
+    "claude-code",
+    "mcp",
+    "skills",
+    "openclaw",
+    "sql",
+    "knowledge-graph",
+    "geospatial",
+    "vector-search"
+  ],
+  "bin": {
+    "toolbelt-skills": "./bin/install.js"
+  },
+  "files": [
+    "bin",
+    "assets",
+    "data-blend",
+    "geo-analyst",
+    "knowledge-graph",
+    "multi-agent-workspace",
+    "run-toolbelt",
+    "sql-analyst",
+    "streaming-analyst",
+    "vector-search",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/run-toolbelt/README.md

@@ -0,0 +1,122 @@
+# run-toolbelt
+
+![run-toolbelt demo](../assets/run-toolbelt-demo.gif)
+
+Autonomous end-to-end Toolbelt agent. Provisions a namespace, ingests documents, connects streaming data sources, and answers questions — all without human interaction.
+
+Invoke via `/run-toolbelt` in Claude Code, or via the `Skill` tool in any MCP-capable agent.
+
+---
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `namespace_id` | No | UUID of target namespace. Auto-selected if only one exists. |
+| `document_content` | No* | Raw text to upload as a document |
+| `document_url` | No* | Public URL to a file (PDF, DOCX, etc.) |
+| `document_name` | No | Name for the asset. Derived from URL or auto-generated if omitted. |
+| `kafka_broker` | No | Kafka broker URL (e.g. `kafka-broker:9092`) |
+| `kafka_topic` | No | Kafka topic name |
+| `kafka_schema` | No | SQL-style column schema (e.g. `id INTEGER, event VARCHAR(256), ts TIMESTAMP`) |
+| `kafka_group_id` | No | Kafka consumer group ID |
+| `question` | No | Question to answer over ingested data |
+
+*At least one of `document_content` or `document_url` is required to run document ingestion. Phases are skipped if their required parameters are absent.
+
+---
+
+## Usage
+
+### Smoke test — connection and namespace only
+
+```
+/run-toolbelt
+```
+
+Runs phases 0–2. Verifies the MCP connection is live and resolves your namespace. No data is written.
+
+---
+
+### Ingest a document and ask a question
+
+```
+/run-toolbelt document_url=https://example.com/report.pdf question="What are the key findings?"
+```
+
+```
+/run-toolbelt document_content="Q1 revenue was $4.2M across three product lines." document_name="q1-summary" question="What was Q1 revenue?"
+```
+
+---
+
+### Target a specific namespace
+
+```
+/run-toolbelt namespace_id=<uuid> document_url=https://example.com/report.pdf question="Summarize this."
+```
+
+Required when your account has multiple namespaces. Omit to auto-select when only one exists.
+
+---
+
+### Connect a Kafka source
+
+```
+/run-toolbelt kafka_broker=kafka-broker:9092 kafka_topic=events kafka_schema="id INTEGER, event VARCHAR(256), ts TIMESTAMP"
+```
+
+Connects the topic and verifies it is queryable. Combine with `question` to search over streaming data.
+
+---
+
+### Full pipeline
+
+```
+/run-toolbelt \
+  namespace_id=<uuid> \
+  document_url=https://example.com/report.pdf \
+  kafka_broker=kafka-broker:9092 \
+  kafka_topic=events \
+  kafka_schema="id INTEGER, event VARCHAR(256), ts TIMESTAMP" \
+  question="What events occurred after the report's cutoff date?"
+```
+
+Runs all phases: document ingestion, Kafka connection, and cross-source search.
+
+---
+
+### From another agent (Skill tool)
+
+```javascript
+{ skill: "run-toolbelt", args: "namespace_id=<uuid> document_url=https://... question=..." }
+```
+
+The skill emits a structured `RESULT:` block — parseable by the calling agent without human interpretation.
+
+---
+
+## Output
+
+On success:
+
+```
+RESULT:
+  namespace_id: <uuid>
+  phases_run: [0, 1, 2, 3, 5]
+  document_table: <table name>
+  kafka_table: <table name, if Phase 4 ran>
+  answer: |
+    <synthesized answer>
+  sql_generated: <SQL, if any>
+  sources: [<cited documents>]
+```
+
+On failure:
+
+```
+FAILURE: <reason>
+<diagnostic detail>
+```
+
+Failures are terminal — the skill halts and does not continue to subsequent phases.

package/run-toolbelt/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: run-toolbelt
+description: >
+  Toolbelt is a multi-modal data platform combining SQL analytics, vector search,
+  and real-time streaming — all queryable through natural language via MCP. This
+  skill provisions a namespace, ingests documents, connects Kafka topics, and
+  answers questions over the ingested data, end-to-end and autonomously. Use when
+  an AI agent needs to onboard to Toolbelt, add assets, connect a streaming source,
+  or run queries without any human interaction.
+license: MIT
+compatibility: >
+  Requires a Toolbelt account (provision free at https://toolbelt.ai) and an
+  MCP-compatible AI agent (Claude Code, Claude Desktop, OpenClaw, or any client
+  that supports MCP server connections). MCP connection must be pre-established
+  before invocation.
+metadata:
+  author: toolbeltai
+  version: "2.0"
+  openclaw:
+    emoji: "🧰"
+    homepage: "https://toolbelt.ai/docs/mcp"
+    skillKey: "run-toolbelt"
+---
+
+Execute Toolbelt end-to-end autonomously using the Toolbelt MCP tools.
+Work through each phase in order. Extract all required inputs from task parameters
+or invocation context — do not prompt for user input. Progress through phases
+without confirmation. On unrecoverable error, emit a structured failure and halt.
+
+## When Not To Use
+
+- When the Toolbelt MCP connection is not yet established — the connection must exist before invocation.
+- When you only need to query data already in Toolbelt — use `sql-analyst` instead.
+- When you only need to upload and analyze a CSV — use `sql-analyst` instead.
+
+## Invocation Parameters
+
+Extract these from the args string or conversation context before starting:
+
+| Parameter | Required | Description |
+|---|---|---|
+| `namespace_id` | No | UUID of target namespace. Auto-select if omitted and only one exists; fail if ambiguous. |
+| `document_content` | No* | Raw text content to upload as a document asset |
+| `document_url` | No* | Public URL to a file (PDF, DOCX, etc.) to upload |
+| `document_name` | No | Name for the document asset. Derive from URL filename or generate if omitted. |
+| `kafka_broker` | No | Kafka broker URL (e.g. `kafka-broker:9092`) |
+| `kafka_topic` | No | Kafka topic name |
+| `kafka_schema` | No | SQL-style column schema (e.g. `id INTEGER, event VARCHAR(256), ts TIMESTAMP`) |
+| `kafka_group_id` | No | Kafka consumer group ID |
+| `question` | No | Question to ask over ingested data in Phase 5 |
+
+*At least one of `document_content` or `document_url` is required to run Phase 3.
+Skip Phase 3 if neither is provided. Skip Phase 4 if Kafka parameters are absent.
+Skip Phase 5 if `question` is absent.
+
+---
+
+## Phase 0: Verify Connection
+
+Call `get_semantic_names` (no arguments) immediately.
+
+- **If it succeeds:** proceed to Phase 1 using the returned namespaces.
+- **If it fails:** emit structured failure and halt.
+
+```
+FAILURE: Toolbelt MCP connection is not established.
+The MCP server must be connected before invoking this skill.
+See: https://toolbelt.ai/docs/mcp for setup instructions.
+```
+
+Do not attempt reconnection or emit manual setup instructions. The connection
+is an environment contract that must be satisfied before invocation.
+
+---
+
+## Phase 1: Resolve Namespace
+
+Use the namespaces returned from Phase 0.
+
+Resolution order:
+1. If `namespace_id` was provided as a parameter, use it directly.
+2. If only one namespace exists, use it.
+3. If multiple exist and no `namespace_id` was specified, emit structured failure and halt.
+
+```
+FAILURE: Multiple namespaces found and none specified.
+Available: [<list namespace display names and IDs>]
+Re-invoke with namespace_id=<uuid>.
+```
+
+Store the resolved `namespace_id` — pass it to every subsequent tool call.
+Never use the display name as the ID.
+
+---
+
+## Phase 2: Inspect Current State
+
+Call `toolbelt_context` with the resolved `namespace_id`.
+
+Store the returned context internally:
+- Relational tables (`relevant_tables`, `table_schemas`)
+- Vector collections (`collections`)
+- Domain summary and suggested prompts
+
+Do not output a summary unless this is the only phase being run.
+
+---
+
+## Phase 3: Add a Document Asset
+
+Skip this phase if neither `document_content` nor `document_url` was provided.
+
+Derive `document_name` from URL filename if not provided. If content was provided
+directly and no name exists, use `document-<ISO timestamp>`.
+
+Call `toolbelt_save`:
+
+**From text content:**
+```json
+{
+  "asset_type": "document",
+  "namespace_id": "<namespace_id>",
+  "name": "<document_name>",
+  "file_name": "document.txt",
+  "content": "<document_content>",
+  "content_encoding": "text"
+}
+```
+
+**From a public URL:**
+```json
+{
+  "asset_type": "document",
+  "namespace_id": "<namespace_id>",
+  "name": "<document_name>",
+  "file_name": "<filename from URL>",
+  "file_url": "<document_url>"
+}
+```
+
+### Poll for completion
+
+Call `toolbelt_jobs` with `{ "namespace_id": "<namespace_id>" }` every 10 seconds.
+
+Job chain: `ingest` (parse + store) → `semantic` (embed + extract entities). Both must reach `completed`.
+Typical duration: 30–120 seconds. Maximum wait: 5 minutes.
+
+If either job reaches `failed` or the timeout elapses, emit structured failure and halt:
+```
+FAILURE: Document ingestion did not complete.
+Job status: <last observed status>
+```
+
+Once complete, call `toolbelt_context` again to confirm the new asset's table appears.
+Record the new table name for use in Phase 5.
+
+---
+
+## Phase 4: Connect a Kafka Source
+
+Skip this phase if `kafka_broker` or `kafka_topic` is absent.
+
+Call `toolbelt_connect`:
+```json
+{
+  "source_type": "kafka",
+  "namespace_id": "<namespace_id>",
+  "location": "KAFKA://<kafka_broker>",
+  "external_table_name": "<kafka_topic>",
+  "asset_name": "<kafka_topic>",
+  "kafka_column_definitions": "<kafka_schema>",
+  "kafka_subscribe": true,
+  "extra_options": { "kafka.group.id": "<kafka_group_id>" }
+}
+```
+
+Omit `extra_options` if `kafka_group_id` was not provided.
+
+Verify the table is queryable with `toolbelt_execute`:
+```json
+{
+  "namespace_id": "<namespace_id>",
+  "query": "SELECT COUNT(*) FROM <kafka_topic> LIMIT 1"
+}
+```
+
+If the query fails, emit structured failure and halt:
+```
+FAILURE: Kafka source connected but table is not queryable.
+Query: SELECT COUNT(*) FROM <kafka_topic> LIMIT 1
+Error: <error message>
+```
+
+---
+
+## Phase 5: Ask a Question
+
+Skip this phase if `question` was not provided.
+
+Call `toolbelt_search`:
+```json
+{
+  "question": "<question>",
+  "namespace_id": "<namespace_id>",
+  "synthesize": true
+}
+```
+
+---
+
+## Structured Output
+
+After all phases complete, emit a single structured result:
+
+```
+RESULT:
+  namespace_id: <uuid>
+  phases_run: [0, 1, 2, ...]
+  document_table: <table name, if Phase 3 ran>
+  kafka_table: <table name, if Phase 4 ran>
+  answer: |
+    <synthesized answer from toolbelt_search, if Phase 5 ran>
+  sql_generated: <SQL from search result, if any>
+  sources: [<cited source documents, if any>]
+```
+
+---
+
+## Tool Reference
+
+| Phase | Tool(s) |
+|---|---|
+| 0. Verify connection | `get_semantic_names` |
+| 1. Resolve namespace | (from Phase 0 result) |
+| 2. Inspect state | `toolbelt_context` |
+| 3. Add document | `toolbelt_save`, `toolbelt_jobs`, `toolbelt_context` |
+| 4. Connect Kafka | `toolbelt_connect`, `toolbelt_execute` |
+| 5. Ask a question | `toolbelt_search` |