@vellumai/assistant 0.4.11 → 0.4.13

package/src/config/bundled-skills/oauth-setup/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: "OAuth Setup"
+description: "Connect any OAuth service — create app credentials and authorize via browser automation"
+user-invocable: true
+includes: ["browser"]
+metadata: {"vellum": {"emoji": "🔑"}}
+---
+
+You are helping the user connect an OAuth-based service to Vellum. This is a generic setup flow that works for any provider with a well-known OAuth config.
+
+**Tone:** Be friendly and reassuring throughout. Narrate what you're doing in plain language so the user always knows what's happening. After each step, briefly confirm what was accomplished before moving on.
+
+## Input
+
+You will be given a `service` name (e.g., "discord", "linear", "spotify"). If not provided, ask the user which service they want to connect.
+
+## Step 1: Read the service config
+
+Use `credential_store` with `action: "describe"` and `service: "<name>"` to get the well-known OAuth config. This returns:
+- `scopes` — permissions to request
+- `redirectUri` — the callback URL to register
+- `callbackTransport` — loopback or gateway
+- `requiresClientSecret` — whether a client secret is needed
+- `authUrl` / `tokenUrl` — OAuth endpoints
+
+It may also include a `setup` object with rich metadata:
+- `setup.displayName` — the provider's name
+- `setup.dashboardUrl` — where to create the app
+- `setup.appType` — what kind of app to create
+- `setup.requiresClientSecret` — whether a client secret is needed
+- `setup.notes` — provider-specific guidance
+
+If no config is found, tell the user this service doesn't have a pre-configured setup and offer to help them configure it manually via `oauth2_connect`.
+
+## Step 2: Choose the flow based on setup metadata
+
+### If `setup` metadata is present (rich flow)
+
+Continue to Step 3 (Rich Flow).
+
+### If `setup` metadata is absent (manual flow)
+
+The provider has OAuth config (endpoints, scopes) but no setup automation metadata. Guide the user through a manual app creation:
+
+1. Tell the user: "I have the OAuth endpoints and scopes for this service, but I don't have developer dashboard automation for it. You'll need to create an OAuth app manually."
+2. Provide the details they need:
+   - **Scopes to request:** list the `scopes` from the config
+   - **Redirect URI:** show the `redirectUri` value
+   - **Whether a client secret is required:** use the top-level `requiresClientSecret` field
+3. Ask the user to:
+   - Go to the provider's developer dashboard
+   - Create an OAuth app (name it "Vellum Assistant")
+   - Set the redirect URI
+   - Configure the required scopes
+   - Copy the Client ID (and Client Secret if required)
+4. Once they provide the credentials, skip to **Step 8: Connect**.
+
+---
+
+## Rich Flow (when `setup` is present)
+
+### Step 3: Tell the user what's happening
+
+Tell the user:
+- "I'll walk you through creating a {setup.appType} so Vellum can connect to {setup.displayName}. The whole process takes a few minutes."
+- "I'll be automating the {setup.displayName} developer dashboard in the browser — you'll be able to see everything I'm doing."
+- "I'll ask for your approval before each major step, so nothing happens without your say-so."
+
+### Step 4: Navigate to the developer dashboard
+
+Use `browser_navigate` to go to `setup.dashboardUrl`.
+
+Take a `browser_screenshot` and `browser_snapshot`:
+- **If a sign-in page appears:** Tell the user to sign in and wait for confirmation.
+- **If the dashboard loads:** Continue to Step 5.
+
+### Step 5: Create an app
+
+**Ask for approval before proceeding.** Use `ui_show` with `surface_type: "confirmation"` explaining what you're about to create.
+
+Once approved:
+1. Find and click the "Create App" / "New Application" / "New Integration" button (adapt to the provider's UI)
+2. Name it "Vellum Assistant"
+3. Follow any guidance from `setup.notes`
+4. Complete the creation flow
+
+Take a `browser_screenshot` to confirm.
+
+### Step 6: Configure scopes/permissions
+
+**Ask for approval before proceeding.** List the `scopes` from the config and explain what each grants.
+
+Once approved, navigate to the OAuth/permissions section and add each scope. Follow `setup.notes` for any provider-specific guidance (e.g., "User Token Scopes" vs "Bot Token Scopes").
+
+Take a `browser_screenshot` after adding all scopes.
+
+### Step 7: Set redirect URL
+
+Check the `redirectUri` from the config:
+- If it mentions "not currently configured", `GATEWAY_BASE_URL`, or `INGRESS_PUBLIC_BASE_URL` — the user needs a public gateway URL configured. Check if one is set; if not, load the `public-ingress` skill first.
+- If it says "automatic" — skip this step entirely (no redirect URI needed).
+- Otherwise, enter the `redirectUri` exactly as provided.
+
+Take a `browser_snapshot` to confirm.
+
+### Step 7b: Extract credentials
+
+Navigate to the app's credentials/settings section.
+
+Use `browser_extract` to read:
+1. **Client ID** (or equivalent)
+2. **Client Secret** (if `requiresClientSecret` is true) — click "Show"/"Reveal" first if needed
+
+---
+
+## Step 8: Connect
+
+Tell the user you're opening the authorization page.
+
+Use `credential_store` with:
+```
+action: "oauth2_connect"
+service: "<service name>"
+client_id: "<extracted client ID>"
+client_secret: "<extracted client secret>"  (if required)
+```
+
+Everything else (endpoints, scopes, params) is auto-filled from the well-known config. Wait for the flow to complete.
+
+## Step 9: Celebrate!
+
+Once connected, tell the user:
+- If `setup` is present: "**{setup.displayName} is connected!** You're all set."
+- If `setup` is absent: "**{service} is connected!** You're all set."
+
+Summarize what was accomplished.
+
+## Error Handling
+
+- **Page load failures:** Retry once. If it still fails, ask the user to check their connection.
+- **Element not found:** Take a fresh `browser_snapshot`. The provider's UI may have changed — adapt dynamically.
+- **User declines an approval gate:** Don't push back. Explain why it matters, offer to retry or cancel.
+- **OAuth flow timeout or failure:** Offer to retry. The app is already created, so only the connect step needs to be re-run.
+- **Any unexpected state:** Take a `browser_screenshot` and `browser_snapshot`, describe what you see, and ask for guidance.

package/src/config/bundled-skills/phone-calls/SKILL.md

@@ -2,7 +2,8 @@
 name: "Phone Calls"
 description: "Set up Twilio for AI-powered voice calls — both outgoing calls on behalf of the user and incoming calls where the assistant answers as a receptionist"
 user-invocable: true
-metadata: {"vellum": {"emoji": "📞", "requires": {"config": ["calls.enabled"]}}}
+metadata:
+  { "vellum": { "emoji": "📞", "requires": { "config": ["calls.enabled"] } } }
 includes: ["public-ingress"]
 ---
 
@@ -34,6 +35,7 @@ When someone dials the assistant's Twilio phone number:
 6. The assistant converses naturally, using ASK_GUARDIAN to consult the user when needed, just like outbound calls.
 
 Three voice quality modes are available:
+
 - **`twilio_standard`** (default) — Fully supported. Standard Twilio TTS with Google voices. No extra setup required.
 - **`twilio_elevenlabs_tts`** — Fully supported. Uses ElevenLabs voices through Twilio ConversationRelay for more natural speech.
 - **`elevenlabs_agent`** — **Experimental/restricted.** Full ElevenLabs conversational agent mode. Consultation bridging (`waiting_on_user`) is not yet supported in this mode; the runtime guard blocks it before any ElevenLabs API calls are made. See the "Runtime behavior" section below for fallback and strict-fail details.
@@ -60,8 +62,7 @@ If `hasCredentials` is `true`, `phoneNumber` is set, and `calls.enabled` is `tru
 
 If Twilio is not yet configured, load the **twilio-setup** skill — it handles credential storage, phone number provisioning, and public ingress setup:
 
-- Call `vellum_skills_catalog` with `action: "install"`, `skill_id: "twilio-setup"`, and `overwrite: true`.
-- Then call `skill_load` with `skill: "twilio-setup"`.
+- Call `skill_load` with `skill_id: "twilio-setup"` to load the dependency skill.
 
 Once twilio-setup completes, return here to enable calls.
 
@@ -74,6 +75,7 @@ vellum config set calls.enabled true
 ```
 
 Verify:
+
 ```bash
 vellum config get calls.enabled
 ```
@@ -108,10 +110,10 @@ credential_store action=store service=twilio field=user_phone_number value=+1415
 
 ### Configuration reference
 
-| Setting | Description | Default |
-|---|---|---|
-| `calls.callerIdentity.allowPerCallOverride` | Whether per-call mode selection is allowed | `true` |
-| `calls.callerIdentity.userNumber` | Optional E.164 phone number for user-number mode (alternative to storing via `credential_store`) | *(empty)* |
+| Setting                                     | Description                                                                                      | Default   |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------ | --------- |
+| `calls.callerIdentity.allowPerCallOverride` | Whether per-call mode selection is allowed                                                       | `true`    |
+| `calls.callerIdentity.userNumber`           | Optional E.164 phone number for user-number mode (alternative to storing via `credential_store`) | _(empty)_ |
 
 ## DTMF Callee Verification
 
@@ -127,10 +129,10 @@ An optional verification step where the callee must enter a numeric code via the
 
 ### Configuration
 
-| Setting | Description | Default |
-|---|---|---|
-| `calls.verification.enabled` | Enable DTMF callee verification | `false` |
-| `calls.verification.codeLength` | Number of digits in the verification code | `6` |
+| Setting                         | Description                               | Default |
+| ------------------------------- | ----------------------------------------- | ------- |
+| `calls.verification.enabled`    | Enable DTMF callee verification           | `false` |
+| `calls.verification.codeLength` | Number of digits in the verification code | `6`     |
 
 ## Optional: Higher Quality Voice with ElevenLabs
 
@@ -218,6 +220,7 @@ vellum config set calls.voice.mode twilio_standard
 ## Making Outbound Calls
 
 Use the `call_start` tool to place outbound calls. Every call requires:
+
 - **phone_number**: The number to call in E.164 format (e.g. `+14155551234`)
 - **task**: What the call should accomplish — this becomes the AI voice agent's objective
 - **context** (optional): Additional background information for the conversation
@@ -225,16 +228,19 @@ Use the `call_start` tool to place outbound calls. Every call requires:
 ### Example calls:
 
 **Making a reservation:**
+
 ```
 call_start phone_number="+14155551234" task="Make a dinner reservation for 2 people tonight at 7pm" context="The user's name is John Smith. Prefer a table by the window if available."
 ```
 
 **Calling a business:**
+
 ```
 call_start phone_number="+18005551234" task="Check if they have a specific product in stock" context="Looking for a 65-inch Samsung OLED TV, model QN65S95D. Ask about availability and price."
 ```
 
 **Following up on an appointment:**
+
 ```
 call_start phone_number="+12125551234" task="Confirm the dentist appointment scheduled for next Tuesday at 2pm" context="The appointment is under the name Jane Doe, DOB 03/15/1990."
 ```
@@ -244,11 +250,13 @@ call_start phone_number="+12125551234" task="Confirm the dentist appointment sch
 Implicit calls always use the assistant's Twilio number (`assistant_number`). Only specify `caller_identity_mode` when the user explicitly requests a different identity for a specific call.
 
 **Default call (assistant number):**
+
 ```
 call_start phone_number="+14155551234" task="Check store hours for today"
 ```
 
 **Call from the user's own number:**
+
 ```
 call_start phone_number="+14155551234" task="Check store hours for today" caller_identity_mode="user_number"
 ```
@@ -258,6 +266,7 @@ call_start phone_number="+14155551234" task="Check store hours for today" caller
 ### Phone number format
 
 Phone numbers MUST be in E.164 format: `+` followed by country code and number with no spaces, dashes, or parentheses.
+
 - US/Canada: `+1XXXXXXXXXX` (e.g. `+14155551234`)
 - UK: `+44XXXXXXXXXX` (e.g. `+442071234567`)
 - International: `+{country_code}{number}`
@@ -267,6 +276,7 @@ If the user provides a number in a different format, convert it to E.164 before
 ### Trial account limitations
 
 On Twilio trial accounts, outbound calls can ONLY be made to **verified numbers**. If a call fails with a "not verified" error:
+
 1. Tell the user they need to verify the number at https://console.twilio.com/us1/develop/phone-numbers/manage/verified
 2. Or upgrade to a paid Twilio account to call any number
 
@@ -283,7 +293,7 @@ No additional configuration is needed beyond Twilio setup and `calls.enabled` be
 
 ### Guardian voice verification for inbound calls
 
-For guardian verification setup, first install the skill via `vellum_skills_catalog` with `action: "install"` and `skill_id: "guardian-verify-setup"`, then load it with `skill_load` using `skill: "guardian-verify-setup"`. This skill handles the full outbound verification flow; `phone-calls` does not orchestrate it inline. Do not use `call_start` to place guardian verification calls — the guardian outbound verification endpoints already place those calls.
+For guardian verification setup, load the skill by calling `skill_load` with `skill_id: "guardian-verify-setup"`. This skill handles the full outbound verification flow; `phone-calls` does not orchestrate it inline. Do not use `call_start` to place guardian verification calls — the guardian outbound verification endpoints already place those calls.
 
 Once a guardian binding exists for the voice channel, inbound callers may be prompted for verification before calls proceed. The relay server detects pending challenges and prompts callers: "Please enter your six-digit verification code using your keypad, or speak the digits now." If verification fails after 3 attempts, the call ends with "Verification failed. Goodbye."
 
@@ -345,6 +355,7 @@ The instruction is injected into the AI voice agent's conversation context as hi
 ### Ending a call early
 
 Use `call_end` with the call session ID to terminate an active call:
+
 ```
 call_end call_session_id="<session_id>" reason="User requested to end the call"
 ```
@@ -371,6 +382,7 @@ sqlite3 ~/.vellum/workspace/data/db/assistant.db \
 ```
 
 This returns all messages in chronological order with:
+
 - `role: "user"` — caller speech (prefixed with `[SPEAKER]` tags) and system events
 - `role: "assistant"` — assistant responses, including `text` content and any `tool_use`/`tool_result` blocks
 
@@ -385,22 +397,22 @@ sqlite3 ~/.vellum/workspace/data/db/assistant.db \
 
 ### Additional tables for call metadata
 
-| Table | What it contains |
-|---|---|
-| `call_sessions` | Session metadata (start time, duration, phone numbers, status) |
-| `call_events` | Granular event log for the call lifecycle |
-| `notification_decisions` | Whether notifications were evaluated during the call |
-| `notification_deliveries` | Notification delivery attempts |
+| Table                     | What it contains                                               |
+| ------------------------- | -------------------------------------------------------------- |
+| `call_sessions`           | Session metadata (start time, duration, phone numbers, status) |
+| `call_events`             | Granular event log for the call lifecycle                      |
+| `notification_decisions`  | Whether notifications were evaluated during the call           |
+| `notification_deliveries` | Notification delivery attempts                                 |
 
 ### Key paths
 
-| Resource | Path |
-|---|---|
+| Resource                                   | Path                                       |
+| ------------------------------------------ | ------------------------------------------ |
 | Daemon logs (caller-side transcripts only) | `~/.vellum/workspace/data/logs/vellum.log` |
-| Full conversation database | `~/.vellum/workspace/data/db/assistant.db` |
-| Messages table | `messages` (keyed by `conversation_id`) |
-| Call sessions table | `call_sessions` |
-| Call events table | `call_events` |
+| Full conversation database                 | `~/.vellum/workspace/data/db/assistant.db` |
+| Messages table                             | `messages` (keyed by `conversation_id`)    |
+| Call sessions table                        | `call_sessions`                            |
+| Call events table                          | `call_events`                              |
 
 ### Important
 
@@ -429,6 +441,7 @@ The `context` field is powerful — use it to give the agent background that hel
 ### Things the AI voice agent handles well
 
 **Outbound calls:**
+
 - Making reservations and appointments
 - Checking business hours, availability, or pricing
 - Confirming or rescheduling existing appointments
@@ -437,6 +450,7 @@ The `context` field is powerful — use it to give the agent background that hel
 - Leaving voicemails (it will speak the message if voicemail picks up)
 
 **Inbound calls:**
+
 - Answering as a receptionist and routing caller requests to the user via ASK_GUARDIAN
 - Taking messages when the user is unavailable
 - Answering questions the assistant already knows from memory/context
@@ -453,27 +467,27 @@ The `context` field is powerful — use it to give the agent background that hel
 
 All call-related settings can be managed via `vellum config`:
 
-| Setting | Description | Default |
-|---|---|---|
-| `calls.enabled` | Master switch for the calling feature | `false` |
-| `calls.provider` | Voice provider (currently only `twilio`) | `twilio` |
-| `calls.maxDurationSeconds` | Maximum call length in seconds | `3600` (1 hour) |
-| `calls.userConsultTimeoutSeconds` | How long to wait for user answers | `120` (2 min) |
-| `calls.disclosure.enabled` | Whether the AI announces itself at call start | `true` |
-| `calls.disclosure.text` | The disclosure message spoken at call start | `"At the very beginning of the call, introduce yourself as an assistant calling on behalf of my human."` |
-| `calls.model` | Override LLM model for call orchestration | *(uses default model)* |
-| `calls.callerIdentity.allowPerCallOverride` | Allow per-call caller identity selection | `true` |
-| `calls.callerIdentity.userNumber` | E.164 phone number for user-number mode | *(empty)* |
-| `calls.voice.mode` | Voice quality mode (`twilio_standard`, `twilio_elevenlabs_tts`, `elevenlabs_agent`) | `twilio_standard` |
-| `calls.voice.language` | Language code for TTS and transcription | `en-US` |
-| `calls.voice.transcriptionProvider` | Speech-to-text provider (`Deepgram`, `Google`) | `Deepgram` |
-| `calls.voice.fallbackToStandardOnError` | Auto-fallback to standard Twilio TTS on ElevenLabs errors | `true` |
-| `calls.voice.elevenlabs.voiceId` | Advanced/internal ElevenLabs voice identifier. Usually set by the assistant based on requested voice style | *(empty)* |
-| `calls.voice.elevenlabs.voiceModelId` | Optional Twilio ConversationRelay model suffix. Leave empty to send bare `voiceId` | *(empty)* |
-| `calls.voice.elevenlabs.agentId` | ElevenLabs agent ID (for `elevenlabs_agent` mode) | *(empty)* |
-| `calls.voice.elevenlabs.speed` | Playback speed (`0.7` – `1.2`) | `1.0` |
-| `calls.voice.elevenlabs.stability` | Voice stability (`0.0` – `1.0`) | `0.5` |
-| `calls.voice.elevenlabs.similarityBoost` | Voice similarity boost (`0.0` – `1.0`) | `0.75` |
+| Setting                                     | Description                                                                                                | Default                                                                                                  |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `calls.enabled`                             | Master switch for the calling feature                                                                      | `false`                                                                                                  |
+| `calls.provider`                            | Voice provider (currently only `twilio`)                                                                   | `twilio`                                                                                                 |
+| `calls.maxDurationSeconds`                  | Maximum call length in seconds                                                                             | `3600` (1 hour)                                                                                          |
+| `calls.userConsultTimeoutSeconds`           | How long to wait for user answers                                                                          | `120` (2 min)                                                                                            |
+| `calls.disclosure.enabled`                  | Whether the AI announces itself at call start                                                              | `true`                                                                                                   |
+| `calls.disclosure.text`                     | The disclosure message spoken at call start                                                                | `"At the very beginning of the call, introduce yourself as an assistant calling on behalf of my human."` |
+| `calls.model`                               | Override LLM model for call orchestration                                                                  | _(uses default model)_                                                                                   |
+| `calls.callerIdentity.allowPerCallOverride` | Allow per-call caller identity selection                                                                   | `true`                                                                                                   |
+| `calls.callerIdentity.userNumber`           | E.164 phone number for user-number mode                                                                    | _(empty)_                                                                                                |
+| `calls.voice.mode`                          | Voice quality mode (`twilio_standard`, `twilio_elevenlabs_tts`, `elevenlabs_agent`)                        | `twilio_standard`                                                                                        |
+| `calls.voice.language`                      | Language code for TTS and transcription                                                                    | `en-US`                                                                                                  |
+| `calls.voice.transcriptionProvider`         | Speech-to-text provider (`Deepgram`, `Google`)                                                             | `Deepgram`                                                                                               |
+| `calls.voice.fallbackToStandardOnError`     | Auto-fallback to standard Twilio TTS on ElevenLabs errors                                                  | `true`                                                                                                   |
+| `calls.voice.elevenlabs.voiceId`            | Advanced/internal ElevenLabs voice identifier. Usually set by the assistant based on requested voice style | _(empty)_                                                                                                |
+| `calls.voice.elevenlabs.voiceModelId`       | Optional Twilio ConversationRelay model suffix. Leave empty to send bare `voiceId`                         | _(empty)_                                                                                                |
+| `calls.voice.elevenlabs.agentId`            | ElevenLabs agent ID (for `elevenlabs_agent` mode)                                                          | _(empty)_                                                                                                |
+| `calls.voice.elevenlabs.speed`              | Playback speed (`0.7` – `1.2`)                                                                             | `1.0`                                                                                                    |
+| `calls.voice.elevenlabs.stability`          | Voice stability (`0.0` – `1.0`)                                                                            | `0.5`                                                                                                    |
+| `calls.voice.elevenlabs.similarityBoost`    | Voice similarity boost (`0.0` – `1.0`)                                                                     | `0.75`                                                                                                   |
 
 ### Adjusting settings
 
@@ -494,60 +508,77 @@ vellum config set calls.userConsultTimeoutSeconds 300
 ## Troubleshooting
 
 ### "Twilio credentials not configured"
+
 Load the `twilio-setup` skill to store your Account SID and Auth Token.
 
 ### "Calls feature is disabled"
+
 Run `vellum config set calls.enabled true`.
 
 ### "No public base URL configured"
+
 Run the **public-ingress** skill to set up ngrok and configure `ingress.publicBaseUrl`.
 
 ### Call fails immediately after initiating
+
 - Check that the phone number is in E.164 format
 - Verify Twilio credentials are correct (wrong auth token causes API errors)
 - On trial accounts, ensure the destination number is verified
 - Check that the ngrok tunnel is still running (`curl -s http://127.0.0.1:4040/api/tunnels`)
 
 ### Call connects but no audio / one-way audio
+
 - The ConversationRelay WebSocket may not be connecting. Check that `ingress.publicBaseUrl` is correct and the tunnel is active
 - Verify the gateway is running at `$GATEWAY_BASE_URL`
 
 ### "Number not eligible for caller identity"
+
 The user's phone number is not owned by or verified with the Twilio account. The number must be either purchased through Twilio or added as a verified caller ID at https://console.twilio.com/us1/develop/phone-numbers/manage/verified.
 
 ### "Per-call caller identity override is disabled"
+
 The setting `calls.callerIdentity.allowPerCallOverride` is set to `false`, so per-call `caller_identity_mode` selection is not allowed. Re-enable overrides with `vellum config set calls.callerIdentity.allowPerCallOverride true`.
 
 ### Caller identity call fails on trial account
+
 Twilio trial accounts can only place calls to verified numbers, regardless of caller identity mode. The user's phone number must also be verified with Twilio. Upgrade to a paid account or verify both the source and destination numbers.
 
 ### "This phone number is not allowed to be called"
+
 Emergency numbers (911, 112, 999, 000, 110, 119) are permanently blocked for safety.
 
 ### ngrok tunnel URL changed
+
 If you restarted ngrok, the public URL has changed. Update it:
+
 ```bash
 vellum config set ingress.publicBaseUrl "<new-url>"
 ```
+
 Or re-run the public-ingress skill to auto-detect and save the new URL.
 
 ### Call drops after 30 seconds of silence
+
 The system has a 30-second silence timeout. If nobody speaks for 30 seconds, the agent will ask "Are you still there?" This is expected behavior.
 
 ### Call quality didn't improve after enabling ElevenLabs
+
 - Verify `calls.voice.mode` is set to `twilio_elevenlabs_tts` or `elevenlabs_agent` (not still `twilio_standard`)
 - Ask for the desired voice style again and try a different voice selection
 - If configuring manually: check that `calls.voice.elevenlabs.voiceId` contains a valid ElevenLabs voice ID
 - If mode is `elevenlabs_agent`, ensure `calls.voice.elevenlabs.agentId` is also set
 
 ### Twilio says "application error" right after answer
+
 - This often means ConversationRelay rejected voice configuration after TwiML fetch
 - Keep `calls.voice.elevenlabs.voiceModelId` empty first (bare `voiceId` mode)
 - If you set `voiceModelId`, try clearing it and retesting:
   `vellum config set calls.voice.elevenlabs.voiceModelId ""`
 
 ### ElevenLabs mode falls back to standard
+
 When `calls.voice.fallbackToStandardOnError` is `true` (the default), the system silently falls back to standard Twilio TTS if ElevenLabs encounters an error or restriction. Check:
+
 - For `elevenlabs_agent` mode: this mode is currently restricted (consultation bridging not yet supported) and will always fall back to standard when fallback is enabled. If fallback is disabled, the voice webhook returns HTTP 501.
 - For `twilio_elevenlabs_tts` mode: verify `calls.voice.elevenlabs.voiceId` is set to a valid voice ID
 - For invalid configs (missing voiceId/agentId): if fallback is disabled, the voice webhook returns HTTP 500 with the config error

package/src/config/bundled-skills/skills-catalog/SKILL.md

@@ -1,52 +1,55 @@
 ---
 name: "Skills Catalog"
-description: "Browse and install skills from the Vellum catalog using the vellum skills CLI"
+description: "Discover bundled skills and search/install community skills from Clawhub"
 user-invocable: true
-metadata: {"vellum": {"emoji": "🧩"}}
+metadata: { "vellum": { "emoji": "🧩" } }
 ---
 
-You can help the user discover and install skills from the Vellum first-party catalog using the `vellum skills` CLI.
+You can help the user discover what skills are available and find community skills to extend the assistant's capabilities.
 
-## Listing available skills
+## Bundled skills (first-party)
 
-```bash
-vellum skills list --json
+First-party skills are **bundled** with the assistant — they are compiled in and always available. They do not need to be installed or downloaded. To activate a bundled skill, use the `skill_load` tool:
+
+```
+skill_load skill=<skill-id>
 ```
 
-Returns a JSON object with `ok: true` and a `skills` array. Each skill has:
-- `id` — the skill identifier (used for install)
-- `name` — human-readable name
-- `description` — what the skill does
-- `emoji` — optional emoji
-- `includes` — optional list of dependency skill IDs
-- `version` — optional version string
+The skill catalog shown in the system prompt lists all bundled skills with their IDs. When a user asks about capabilities, refer to this list to find relevant bundled skills and load them as needed.
 
-## Installing a skill
+## Community skills (Clawhub)
 
-```bash
-vellum skills install <skill-id> --json
-```
+Community skills are published on [Clawhub](https://clawhub.com) and can be searched and installed on demand.
+
+### Searching for community skills
+
+Use the `skill_load` tool to search the catalog, or check the system prompt's available skills list. The IPC `skills_search` message searches community skills on Clawhub. Bundled skills are already listed in the system prompt.
+
+### Installing a community skill
+
+Community skills are installed via the IPC `skills_install` message with a `slug` parameter. Once installed, they appear in `~/.vellum/workspace/skills/<slug>/` and can be loaded with `skill_load` like any other skill.
 
-Installs the skill to the managed skills directory. If the skill is already installed, pass `--overwrite` to replace it.
+### Inspecting a community skill
 
-Returns `{ "ok": true, "skillId": "<id>" }` on success.
+Before installing, you can inspect a community skill via the IPC `skills_inspect` message with a `slug` parameter. This returns metadata (author, stats, version) and optionally the skill's SKILL.md content so the user can review it.
 
 ## Typical flow
 
 1. **User asks about capabilities** — "Can you order food?" or "What can you do?"
-   - Run `vellum skills list --json` to see what's available
+   - Check the bundled skills list in the system prompt
    - Present relevant skills to the user
+   - Load any that match with `skill_load`
 
-2. **User wants a new skill** — "I want to use Slack" or "Set up Telegram"
-   - Run `vellum skills list --json` to find matching skills
-   - Run `vellum skills install <skill-id> --json` to install it
-   - The skill will be available on the next conversation turn
+2. **User wants a capability not covered by bundled skills** — "Can you do X?"
+   - Search for community skills that provide the capability
+   - Present matching results with descriptions and install counts
+   - Install the chosen skill, then load it with `skill_load`
 
-3. **Skill has dependencies** — if `includes` lists other skill IDs, install those first
+3. **Skill has dependencies** — if `includes` lists other skill IDs, load those first with `skill_load`
 
 ## Notes
 
-- Skills are fetched from the Vellum platform API
-- Installed skills are stored in `~/.vellum/workspace/skills/<skill-id>/`
-- After installing, the skill may need to be enabled in settings
-- Use `--json` on all commands for reliable parsing
+- Bundled skills are always available and do not need installation
+- Community skills are installed to `~/.vellum/workspace/skills/<slug>/`
+- After installing a community skill, it may need to be enabled in settings
+- Skills can be enabled or disabled via feature flags without uninstalling them

package/src/config/bundled-skills/slack/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: "Slack"
+description: "Scan channels, summarize threads, and manage Slack with privacy guardrails"
+user-invocable: true
+metadata: {"vellum": {"emoji": "💬"}}
+---
+
+You are a Slack assistant that helps users stay on top of their Slack workspace. Use the slack tools for channel scanning, thread summarization, and Slack-specific operations.
+
+## Channel Scanning
+
+When the user says "scan my Slack", "what's happening on Slack", or similar:
+
+1. Call `slack_scan_digest` immediately. If preferred channels are configured, scan those; otherwise scan top active channels.
+2. Present results progressively: overview first (channel names, message counts, top threads), then offer to drill into specific threads.
+3. For threads the user wants to explore, use `messaging_read` with `thread_id` to fetch full content, then summarize with attribution (who said what, decisions made, open questions).
+
+## Thread Summarization
+
+When summarizing threads surfaced by the digest:
+
+- Include attribution: who said what, what decisions were made, what questions remain open
+- Note the thread's channel and whether it's private
+- Keep summaries concise but complete
+
+## Context Sharing (Privacy Rules)
+
+**This is critical.** Channel privacy must be respected at all times:
+
+- Content from `isPrivate: true` channels MUST NEVER be shared to other channels, DMs, or external destinations
+- Before sharing any content, always check the source channel's `isPrivate` flag in the digest data
+- If the user asks to share private channel content, explain that the content is from a private channel and cannot be shared externally, then offer alternatives (e.g., summarize the topic without quoting, ask the user to share manually)
+- Public channel content can be shared with attribution ("From #channel: ...")
+- Always confirm with the user before sending content to any destination
+
+## Channel Preferences
+
+Use `slack_configure_channels` to save and load preferred channels for scanning.
+
+- After a first scan, suggest configuring defaults: "Want me to remember these channels for future scans?"
+- Saved preferences are used automatically by `slack_scan_digest` when no specific channels are requested
+
+## Watcher Integration
+
+For real-time monitoring (not just on-demand scanning), the user can set up a Slack watcher using the watcher skill with the same channel IDs. Mention this if the user wants ongoing monitoring.
+
+## Connection
+
+Before using any Slack tool, verify that Slack is connected. If not connected, guide the user through the Slack setup flow described in the messaging skill.