vellum 0.2.10 → 0.2.12

package/src/cli/main-screen.tsx

@@ -1,19 +1,9 @@
-import { type ReactElement } from "react";
-import { basename } from "node:path";
-import { Box, render as inkRender, Text } from "ink";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
 import { getSocketPath, getWorkspaceDir } from "../util/platform.js";
-import { APP_VERSION } from "../version.js";
 
 const LEFT_PANEL_WIDTH = 36;
-
-const VELLY_ART = [
-  "    ,___,",
-  "   ( O O )",
-  "    /)V(\\",
-  "   //   \\\\",
-  '  /"     "\\',
-  "  ^       ^",
-];
+const RIGHT_LINE_COUNT = 11;
 
 export interface MainScreenLayout {
   height: number;
@@ -21,116 +11,24 @@ export interface MainScreenLayout {
   statusCol: number;
 }
 
-function DefaultMainScreen(): ReactElement {
+export function renderMainScreen(): MainScreenLayout {
   const socketPath = getSocketPath();
   const workspace = getWorkspaceDir();
-  const dirName = basename(workspace);
-
-  const tips = [
-    "Send a message to start chatting",
-    "Use /help to see available commands",
-  ];
-
-  const leftLines = [
-    " ",
-    "    Meet your Assistant!",
-    " ",
-    ...VELLY_ART.map((l) => `  ${l}`),
-    " ",
-    `  ${socketPath}`,
-    `  ~/${dirName}`,
-  ];
-
-  const rightLines = [
-    " ",
-    "Tips for getting started",
-    ...tips,
-    " ",
-    "Daemon",
-    "connecting...",
-    "Version",
-    APP_VERSION,
-    "Status",
-    "checking...",
-  ];
+  const assistantId = workspace.split("/").pop() ?? "vellum";
 
-  const maxLines = Math.max(leftLines.length, rightLines.length);
-
-  return (
-    <Box flexDirection="column" width={72}>
-      <Text dimColor>{"── Vellum " + "─".repeat(62)}</Text>
-      <Box flexDirection="row">
-        <Box flexDirection="column" width={LEFT_PANEL_WIDTH}>
-          {Array.from({ length: maxLines }, (_, i) => {
-            const line = leftLines[i] ?? " ";
-            if (i === 1) {
-              return (
-                <Text key={i} bold>
-                  {line}
-                </Text>
-              );
-            }
-            if (i > 2 && i <= 2 + VELLY_ART.length) {
-              return (
-                <Text key={i} color="magenta">
-                  {line}
-                </Text>
-              );
-            }
-            if (i > 2 + VELLY_ART.length) {
-              return (
-                <Text key={i} dimColor>
-                  {line}
-                </Text>
-              );
-            }
-            return <Text key={i}>{line}</Text>;
-          })}
-        </Box>
-        <Box flexDirection="column">
-          {Array.from({ length: maxLines }, (_, i) => {
-            const line = rightLines[i] ?? " ";
-            const isHeading = i === 1 || i === 6;
-            const isDim = i === 5 || i === 7 || i === 9;
-            if (isHeading) {
-              return (
-                <Text key={i} color="magenta">
-                  {line}
-                </Text>
-              );
-            }
-            if (isDim) {
-              return (
-                <Text key={i} dimColor>
-                  {line}
-                </Text>
-              );
-            }
-            return <Text key={i}>{line}</Text>;
-          })}
-        </Box>
-      </Box>
-      <Text dimColor>{"─".repeat(72)}</Text>
-      <Text> </Text>
-      <Text dimColor> ? for shortcuts</Text>
-      <Text> </Text>
-    </Box>
-  );
-}
-
-export function renderMainScreen(): MainScreenLayout {
-  const leftLineCount = 3 + VELLY_ART.length + 3;
-  const rightLineCount = 11;
-  const maxLines = Math.max(leftLineCount, rightLineCount);
+  const require = createRequire(import.meta.url);
+  const cliPkgPath = require.resolve("@vellumai/cli/package.json");
+  const cliRoot = dirname(cliPkgPath);
+  // Dynamic require to bypass NodeNext strict module resolution for the
+  // CLI package which ships raw TypeScript with bundler-style imports.
+  const { render } = require(join(cliRoot, "src", "components", "DefaultMainScreen.tsx")) as {
+    render: (runtimeUrl: string, assistantId: string, species: string) => number;
+  };
 
-  const { unmount } = inkRender(<DefaultMainScreen />, {
-    exitOnCtrlC: false,
-  });
-  unmount();
+  const height = render(socketPath, assistantId, "vellum");
 
-  const statusCanvasLine = rightLineCount + 1;
+  const statusCanvasLine = RIGHT_LINE_COUNT + 1;
   const statusCol = LEFT_PANEL_WIDTH + 1;
-  const height = 1 + maxLines + 4;
 
   return { height, statusLine: statusCanvasLine, statusCol };
 }

package/src/config/bundled-skills/macos-automation/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: "macOS Automation"
+description: "Automate native macOS apps and system interactions via osascript (AppleScript)"
+user-invocable: false
+disable-model-invocation: false
+metadata: {"vellum": {"emoji": "🍎", "os": ["darwin"]}}
+---
+
+Use this skill to interact with native macOS apps and system-level features via `osascript` (AppleScript) through `host_bash`. Always prefer osascript over browser automation or computer-use for anything involving a native macOS app.
+
+## Supported Apps
+
+**Communication:** Messages, Mail, Microsoft Outlook, FaceTime
+**Contacts & Calendar:** Contacts, Calendar, Reminders
+**Notes & Writing:** Notes, TextEdit, Pages, BBEdit, CotEditor
+**Files:** Finder, Path Finder
+**Browsers:** Safari, Google Chrome
+**Music & Media:** Music (iTunes), Spotify, VLC, Podcasts, TV
+**Productivity:** OmniFocus, Things 3, OmniOutliner, OmniPlan, OmniGraffle
+**Office:** Microsoft Word, Microsoft Excel, Numbers, Keynote
+**Developer tools:** Xcode, Terminal, iTerm2, Script Editor
+**System:** System Events (UI scripting for any app), System Settings
+**Automation:** Keyboard Maestro, Alfred, Automator
+**Creative:** Adobe Photoshop, Final Cut Pro
+
+For any unlisted app, check scriptability first:
+```bash
+osascript -e 'tell application "AppName" to get name'
+```
+
+## Examples
+
+```bash
+# Send an iMessage
+osascript -e 'tell application "Messages" to send "Hello!" to buddy "user@example.com"'
+
+# Look up a contact
+osascript -e 'tell application "Contacts" to get {name, phones} of every person whose name contains "Marina"'
+
+# Read upcoming calendar events
+osascript -e 'tell application "Calendar" to get summary of every event of calendar "Home" whose start date > (current date)'
+
+# Create a reminder
+osascript -e 'tell application "Reminders" to make new reminder with properties {name:"Buy milk", due date:((current date) + 1 * hours)}'
+
+# Send an email
+osascript -e 'tell application "Mail" to send (make new outgoing message with properties {subject:"Hi", content:"Hello", visible:true})'
+
+# Create a note
+osascript -e 'tell application "Notes" to make new note at folder "Notes" with properties {body:"My note"}'
+
+# Open a URL in Safari
+osascript -e 'tell application "Safari" to open location "https://example.com"'
+
+# Play/pause Music
+osascript -e 'tell application "Music" to playpause'
+
+# Display a system notification
+osascript -e 'display notification "Done!" with title "Vellum"'
+```
+
+## Tips
+
+- For multi-line scripts, write them to a `.applescript` file and run with `osascript path/to/script.applescript`
+- Use `System Events` for UI scripting apps that don't have their own AppleScript dictionary
+- AppleScript permissions are gated by macOS TCC — if a command fails with a permission error, use `request_system_permission` to prompt the user

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

@@ -0,0 +1,334 @@
+---
+name: "Phone Calls"
+description: "Set up Twilio for outgoing phone calls and place AI-powered voice calls on behalf of the user"
+user-invocable: true
+metadata: {"vellum": {"emoji": "📞", "requires": {"config": ["calls.enabled"]}}}
+includes: ["public-ingress"]
+---
+
+You are helping the user set up and make outgoing phone calls via Twilio. This skill covers the full lifecycle: Twilio account setup, credential storage, public ingress configuration, enabling the calls feature, placing calls, and monitoring live transcripts.
+
+## Overview
+
+The calling system uses Twilio's ConversationRelay to place outbound phone calls. When a call is placed:
+
+1. The assistant initiates an outbound call via the Twilio REST API
+2. Twilio connects to the gateway's voice webhook, which returns TwiML
+3. Twilio opens a ConversationRelay WebSocket for real-time voice streaming
+4. An LLM-driven orchestrator manages the conversation — receiving caller speech (transcribed by Deepgram), generating responses via Claude, and streaming text back for TTS playback
+5. The transcript is relayed live to the user's conversation thread
+
+The user's assistant gets its own personal phone number through Twilio.
+
+## Step 1: Check Current Configuration
+
+First, check whether Twilio is already configured:
+
+```bash
+vellum config get calls.enabled
+```
+
+Also check for existing credentials:
+
+```bash
+credential_store action=get service=credential:twilio:account_sid
+credential_store action=get service=credential:twilio:auth_token
+credential_store action=get service=credential:twilio:phone_number
+```
+
+If all three credentials exist and `calls.enabled` is `true`, skip to the **Making Calls** section. If credentials are partially configured, skip to whichever step is still needed.
+
+## Step 2: Create a Twilio Account
+
+If the user doesn't have a Twilio account yet, guide them through setup:
+
+1. Tell the user: **"You'll need a Twilio account to make phone calls. Sign up at https://www.twilio.com/try-twilio — it's free to start and includes trial credit."**
+2. Once they have an account, they need three pieces of information:
+   - **Account SID** — found on the Twilio Console dashboard at https://console.twilio.com
+   - **Auth Token** — found on the same dashboard (click "Show" to reveal it)
+   - **Phone Number** — a Twilio phone number capable of making voice calls
+
+### Getting a Twilio Phone Number
+
+If the user doesn't have a Twilio phone number yet:
+
+1. Direct them to https://console.twilio.com/us1/develop/phone-numbers/manage/incoming
+2. Click **"Buy a Number"**
+3. Select a number with **Voice** capability enabled
+4. For trial accounts, Twilio provides one free number automatically — check "Active Numbers" first
+
+Tell the user: **"This will be your assistant's personal phone number — the number that shows up on caller ID when calls are placed."**
+
+## Step 3: Store Twilio Credentials
+
+Once the user provides their credentials, store them securely using the `credential_store` tool. Ask the user to paste each value, then store them one at a time:
+
+**Account SID:**
+```
+credential_store action=set service=credential:twilio:account_sid value=<their_account_sid>
+```
+
+**Auth Token:**
+```
+credential_store action=set service=credential:twilio:auth_token value=<their_auth_token>
+```
+
+**Phone Number** (must be in E.164 format, e.g. `+14155551234`):
+```
+credential_store action=set service=credential:twilio:phone_number value=<their_phone_number>
+```
+
+After storing, verify each credential was saved:
+```
+credential_store action=get service=credential:twilio:account_sid
+credential_store action=get service=credential:twilio:auth_token
+credential_store action=get service=credential:twilio:phone_number
+```
+
+**Important:** Credentials are stored in the OS keychain (macOS Keychain / Linux secret-service) or encrypted at rest. They are never logged or exposed in plaintext.
+
+## Step 4: Set Up Public Ingress
+
+Twilio needs a publicly reachable URL to send voice webhooks and establish the ConversationRelay WebSocket. The **public-ingress** skill handles this via ngrok.
+
+Check if ingress is already configured:
+
+```bash
+vellum config get ingress.publicBaseUrl
+vellum config get ingress.enabled
+```
+
+If not configured, load and run the public-ingress skill:
+
+```
+skill_load skill=public-ingress
+```
+
+Follow the public-ingress skill's instructions to set up the ngrok tunnel. Once complete, the gateway will be reachable at the configured `ingress.publicBaseUrl`.
+
+**Twilio needs these webhook endpoints (handled automatically by the gateway):**
+- Voice webhook: `{publicBaseUrl}/webhooks/twilio/voice`
+- Status callback: `{publicBaseUrl}/webhooks/twilio/status`
+- ConversationRelay WebSocket: `{publicBaseUrl}/webhooks/twilio/relay` (wss://)
+
+No manual Twilio webhook configuration is needed — the assistant registers webhook URLs dynamically when placing each call.
+
+## Step 5: Enable Calls
+
+Enable the calls feature:
+
+```bash
+vellum config set calls.enabled true
+```
+
+Verify:
+```bash
+vellum config get calls.enabled
+```
+
+## Step 6: Verify Setup (Test Call)
+
+Before making real calls, offer a quick verification:
+
+1. Confirm credentials are stored: all three `credential:twilio:*` keys must be present
+2. Confirm ingress is running: `ingress.publicBaseUrl` must be set and the tunnel active
+3. Confirm calls are enabled: `calls.enabled` must be `true`
+
+Suggest a test call to the user's own phone: **"Want to do a quick test call to your phone to make sure everything works?"**
+
+If they agree, ask for their personal phone number and place a test call with a simple task like "Introduce yourself and confirm the call system is working."
+
+## Making 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
+
+### 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."
+```
+
+### 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}`
+
+If the user provides a number in a different format, convert it to E.164 before calling. If the country is ambiguous, ask.
+
+### 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
+
+## Live Call Monitoring
+
+### Showing the live transcript
+
+By default, always show the live transcript of the call as it happens. When a call is in progress:
+
+1. After placing the call with `call_start`, immediately begin polling with `call_status` to track the call state
+2. The system fires transcript notifications as the conversation unfolds — both caller speech and assistant responses appear in real time in the conversation thread
+3. Present each transcript entry clearly as it arrives:
+
+```
+📞 Call in progress...
+
+🗣️ Assistant: "Hi, I'm calling on behalf of John to make a dinner reservation for tonight."
+👤 Caller: "Sure, what time would you like?"
+🗣️ Assistant: "We'd like a table for two at 7pm, please."
+👤 Caller: "Let me check... yes, we have availability at 7pm."
+🗣️ Assistant: "Wonderful! The reservation would be under John Smith."
+```
+
+4. Continue monitoring until the call completes or fails
+
+### Handling questions during a call
+
+The AI voice agent may encounter situations where it needs input from the user. When this happens:
+
+1. The call status changes to `waiting_on_user`
+2. A **pending question** appears in `call_status` output
+3. Present the question prominently to the user:
+
+```
+❓ The person on the call asked something the assistant needs your help with:
+   "They're asking if you'd prefer the smoking or non-smoking section?"
+```
+
+4. The user can reply directly in the chat — their response is automatically routed to the live call via the call bridge
+5. The AI voice agent receives the answer and continues the conversation naturally
+
+**Important:** Respond to pending questions quickly. There is a consultation timeout (default: 2 minutes). If no answer is provided in time, the AI voice agent will move on.
+
+### Call status values
+
+- **initiated** — Call is being placed
+- **ringing** — Phone is ringing on the other end
+- **in_progress** — Call is connected, conversation is active
+- **waiting_on_user** — AI agent needs input from the user (check pending question)
+- **completed** — Call ended successfully
+- **failed** — Call failed (check lastError for details)
+- **cancelled** — Call was manually cancelled
+
+### 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"
+```
+
+## Call Quality Tips
+
+When crafting tasks for the AI voice agent, follow these guidelines for the best call experience:
+
+### Writing good task descriptions
+
+- **Be specific about the objective**: "Make a dinner reservation for 2 at 7pm tonight" is better than "Call the restaurant"
+- **Include relevant context**: Names, account numbers, appointment details — anything the agent might need
+- **Specify what information to collect**: "Ask about their return policy and store hours" tells the agent what to gather
+- **Set clear completion criteria**: The agent knows to end the call when the task is fulfilled
+
+### Providing context
+
+The `context` field is powerful — use it to give the agent background that helps it sound natural:
+
+- User's name and identifying details (for making appointments, verifying accounts)
+- Preferences and constraints (dietary restrictions, budget limits, scheduling conflicts)
+- Previous interaction history ("I called last week and spoke with Sarah about...")
+- Special instructions ("If they put you on hold for more than 5 minutes, hang up and we'll try again later")
+
+### Things the AI voice agent handles well
+
+- Making reservations and appointments
+- Checking business hours, availability, or pricing
+- Confirming or rescheduling existing appointments
+- Gathering information (store policies, product availability)
+- Simple customer service interactions
+- Leaving voicemails (it will speak the message if voicemail picks up)
+
+### Things to be aware of
+
+- Calls have a maximum duration (configurable via `calls.maxDurationSeconds`, default: 1 hour)
+- The agent gives a 2-minute warning before the time limit
+- Emergency numbers (911, 112, 999, etc.) are blocked and cannot be called
+- The AI disclosure setting (`calls.disclosure.enabled`) controls whether the agent announces it's an AI at the start of the call
+
+## Configuration Reference
+
+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 | `"I should let you know that I'm an AI assistant calling on behalf of my user."` |
+
+### Adjusting settings
+
+```bash
+# Increase max call duration to 2 hours
+vellum config set calls.maxDurationSeconds 7200
+
+# Disable AI disclosure (check local regulations first)
+vellum config set calls.disclosure.enabled false
+
+# Custom disclosure message
+vellum config set calls.disclosure.text "Just so you know, this is an AI assistant calling for my user."
+
+# Give more time for user consultation
+vellum config set calls.userConsultTimeoutSeconds 300
+```
+
+## Troubleshooting
+
+### "Twilio credentials not configured"
+Run Step 3 to store your Account SID, Auth Token, and Phone Number via `credential_store`.
+
+### "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 on `http://127.0.0.1:${GATEWAY_PORT:-7830}`
+
+### "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.

package/src/config/system-prompt.ts

@@ -410,63 +410,8 @@ function buildAccessPreferenceSection(): string {
     'If yes to any of these, use that path instead of the browser.',
     ...(isMacOS() ? [
       '',
-      '### macOS App Automation',
-      '',
-      'When interacting with native macOS apps or performing system-level actions, prefer **osascript**',
-      'via host_bash over browser automation or computer-use.',
-      '',
-      'The following apps support AppleScript and should be automated via osascript:',
-      '',
-      '**Communication:** Messages, Mail, Microsoft Outlook, FaceTime',
-      '**Contacts & Calendar:** Contacts, Calendar, Reminders',
-      '**Notes & Writing:** Notes, TextEdit, Pages, BBEdit, CotEditor',
-      '**Files & Finder:** Finder, Path Finder',
-      '**Browsers:** Safari, Google Chrome',
-      '**Music & Media:** Music (iTunes), Spotify, VLC, Podcasts, TV',
-      '**Productivity:** OmniFocus, Things 3, OmniOutliner, OmniPlan, OmniGraffle',
-      '**Office:** Microsoft Word, Microsoft Excel, Numbers, Keynote',
-      '**Developer tools:** Xcode, Terminal, iTerm2, Script Editor',
-      '**System:** Finder, System Events (UI scripting for any app), System Settings',
-      '**Automation:** Keyboard Maestro, Alfred, Automator',
-      '**Creative:** Adobe Photoshop, Final Cut Pro',
-      '',
-      'For any other app, try osascript first — check scriptability with:',
-      '```bash',
-      'osascript -e \'tell application "AppName" to get name\'',
-      '```',
-      '',
-      'Common examples:',
-      '```bash',
-      '# Send an iMessage',
-      'osascript -e \'tell application "Messages" to send "Hello!" to buddy "user@example.com"\'',
-      '',
-      '# Look up a contact',
-      'osascript -e \'tell application "Contacts" to get {name, phones} of every person whose name contains "Marina"\'',
-      '',
-      '# Read upcoming calendar events',
-      'osascript -e \'tell application "Calendar" to get summary of every event of calendar "Home" whose start date > (current date)\'',
-      '',
-      '# Create a reminder',
-      'osascript -e \'tell application "Reminders" to make new reminder with properties {name:"Buy milk", due date:((current date) + 1 * hours)}\'',
-      '',
-      '# Send an email',
-      'osascript -e \'tell application "Mail" to send (make new outgoing message with properties {subject:"Hi", content:"Hello", visible:true})\'',
-      '',
-      '# Create a note',
-      'osascript -e \'tell application "Notes" to make new note at folder "Notes" with properties {body:"My note"}\'',
-      '',
-      '# Open a URL in Safari',
-      'osascript -e \'tell application "Safari" to open location "https://example.com"\'',
-      '',
-      '# Play/pause Music',
-      'osascript -e \'tell application "Music" to playpause\'',
-      '',
-      '# Display a system notification',
-      'osascript -e \'display notification "Done!" with title "Vellum"\'',
-      '```',
-      '',
-      'osascript (AppleScript/JXA) has direct, reliable access to macOS app APIs and system events.',
-      'Use it whenever the task involves a native macOS app or system-level interaction.',
+      'On macOS, also consider the `macos-automation` skill for interacting with native apps',
+      '(Messages, Contacts, Calendar, Mail, Reminders, Music, Finder, etc.) via osascript.',
     ] : []),
   ].join('\n');
 }
@@ -702,8 +647,13 @@ function escapeXml(str: string): string {
 }
 
 function formatSkillsCatalog(skills: SkillSummary[]): string {
-  // Filter out skills with disableModelInvocation
-  const visible = skills.filter(s => !s.disableModelInvocation);
+  // Filter out skills with disableModelInvocation or unsupported OS
+  const visible = skills.filter(s => {
+    if (s.disableModelInvocation) return false;
+    const os = s.metadata?.os;
+    if (os && os.length > 0 && !os.includes(process.platform)) return false;
+    return true;
+  });
   if (visible.length === 0) return '';
 
   const lines = ['<available_skills>'];