@vellumai/assistant 0.4.55 → 0.4.57

package/src/prompts/system-prompt.ts

@@ -1,7 +1,6 @@
 import { copyFileSync, existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { CLI_HELP_REFERENCE } from "../cli/reference.js";
 import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
 import { getBaseDataDir, getIsContainerized } from "../config/env-registry.js";
 import { getConfig } from "../config/loader.js";
@@ -10,24 +9,15 @@ import { loadSkillCatalog, type SkillSummary } from "../config/skills.js";
 import { listConnections } from "../oauth/oauth-store.js";
 import { resolveBundledDir } from "../util/bundled-asset.js";
 import { getLogger } from "../util/logger.js";
-import {
-  getWorkspaceDir,
-  getWorkspacePromptPath,
-  isMacOS,
-} from "../util/platform.js";
-import { resolveUserPronouns, resolveUserReference } from "./user-reference.js";
+import { getWorkspacePromptPath, isMacOS } from "../util/platform.js";
+import { SYSTEM_PROMPT_CACHE_BOUNDARY } from "./cache-boundary.js";
+
+export { SYSTEM_PROMPT_CACHE_BOUNDARY };
 
 const log = getLogger("system-prompt");
 
 const PROMPT_FILES = ["SOUL.md", "IDENTITY.md", "USER.md"] as const;
 
-let cachedCliHelp: string | undefined;
-
-/** @internal Reset the CLI help cache — exposed for testing only. */
-export function _resetCliHelpCache(): void {
-  cachedCliHelp = undefined;
-}
-
 /**
  * Copy template prompt files into the data directory if they don't already exist.
  * Called once during daemon startup so users always have discoverable files to edit.
@@ -90,15 +80,6 @@ export function ensurePromptFiles(): void {
   }
 }
 
-/**
- * Returns true when BOOTSTRAP.md has been deleted from the workspace,
- * signalling the first-run ritual is complete.
- */
-export function isOnboardingComplete(): boolean {
-  const bootstrapPath = getWorkspacePromptPath("BOOTSTRAP.md");
-  return !existsSync(bootstrapPath);
-}
-
 /**
  * Build the system prompt from ~/.vellum prompt files,
  * then append a generated skills catalog (if any skills are available).
@@ -111,14 +92,49 @@ export function isOnboardingComplete(): boolean {
  */
 export interface BuildSystemPromptOptions {
   hasNoClient?: boolean;
+  excludeBootstrap?: boolean;
 }
 
+/**
+ * Sentinel that separates the static instruction prefix (stable across turns)
+ * from the dynamic workspace suffix (changes when workspace files are edited).
+ *
+ * The Anthropic provider splits on this marker to create two system-prompt
+ * cache blocks so that static instructions stay cached even when workspace
+ * files change between turns.
+ */
 export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
+  const hasNoClient = options?.hasNoClient ?? false;
+
+  // ── Static instruction sections (stable across turns) ──
+  // These sections are deterministic within a process lifetime.  They form
+  // the first cache block so they remain cached even when workspace files
+  // (IDENTITY.md, SOUL.md, USER.md, etc.) are edited between turns.
+  const staticParts: string[] = [];
+  staticParts.push(buildParallelToolCallsSection());
+  if (getIsContainerized()) staticParts.push(buildContainerizedSection());
+  staticParts.push(buildCliReferenceSection());
+  // Tool Permissions section removed — guidance lives in tool descriptions.
+  // Tool Routing section removed — guidance lives in tool descriptions.
+  staticParts.push(buildAttachmentSection());
+  staticParts.push(buildInChatConfigurationSection());
+  // System Permissions section removed — guidance lives in request_system_permission tool description.
+  // Parallel Task Orchestration section removed — orchestration skill description + hints cover this.
+  staticParts.push(buildAccessPreferenceSection(hasNoClient));
+  // Memory Persistence, Memory Recall, Workspace Reflection, Learning from Mistakes
+  // sections removed — guidance lives in memory_manage/memory_recall tool descriptions
+  // and the Proactive Workspace Editing subsection in Configuration.
+
+  // ── Dynamic sections (may change between turns) ──
+  // Workspace files, config, external comms identity, connected services,
+  // and skills catalog are all re-read from disk/DB each turn.  They form
+  // the second cache block.
+  const dynamicParts: string[] = [];
+
   const soulPath = getWorkspacePromptPath("SOUL.md");
   const identityPath = getWorkspacePromptPath("IDENTITY.md");
   const userPath = getWorkspacePromptPath("USER.md");
   const bootstrapPath = getWorkspacePromptPath("BOOTSTRAP.md");
-
   const updatesPath = getWorkspacePromptPath("UPDATES.md");
 
   const soul = readPromptFile(soulPath);
@@ -127,23 +143,32 @@ export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
   const bootstrap = readPromptFile(bootstrapPath);
   const updates = readPromptFile(updatesPath);
 
-  // ── Core sections ──
-  const parts: string[] = [];
-  parts.push(
-    "IMPORTANT: Never use em dashes (—) in your messages. Use commas, periods, or just start a new sentence instead.",
-  );
-  if (identity) parts.push(identity);
-  if (soul) parts.push(soul);
-  if (user) parts.push(user);
-  if (bootstrap) {
-    parts.push(
+  const includeBootstrap = !!bootstrap && !options?.excludeBootstrap;
+
+  // Template prompt files contain placeholder fields and meta-instructions
+  // meant for the assistant to fill in during onboarding.  When included
+  // verbatim in the system prompt, the model can leak internal details and
+  // narrate its own setup process instead of following the BOOTSTRAP.md
+  // ritual.  Detect unmodified templates by comparing against the bundled
+  // source and skip them — SOUL.md provides sufficient personality defaults
+  // until onboarding completes.
+  const identityIsTemplate = isTemplateContent(identity, "IDENTITY.md");
+  const userIsTemplate = isTemplateContent(user, "USER.md");
+
+  if (identity && !identityIsTemplate) {
+    dynamicParts.push(identity);
+  }
+  if (soul) dynamicParts.push(soul);
+  if (user && !userIsTemplate) dynamicParts.push(user);
+  if (includeBootstrap) {
+    dynamicParts.push(
       "# First-Run Ritual\n\n" +
         "BOOTSTRAP.md is present — this is your first conversation. Follow its instructions.\n\n" +
         bootstrap,
     );
   }
   if (updates) {
-    parts.push(
+    dynamicParts.push(
       [
         "## Recent Updates",
         "",
@@ -159,181 +184,29 @@ export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
       ].join("\n"),
     );
   }
-  if (getIsContainerized()) parts.push(buildContainerizedSection());
-  const hasNoClient = options?.hasNoClient ?? false;
-  parts.push(buildConfigSection(hasNoClient));
-  parts.push(buildCliReferenceSection());
-  parts.push(buildPostToolResponseSection());
-  parts.push(buildExternalCommsIdentitySection());
-  parts.push(buildChannelAwarenessSection());
-  const config = getConfig();
-  if (!hasNoClient) parts.push(buildToolPermissionSection());
-  parts.push(buildTaskScheduleReminderRoutingSection());
-  if (
-    isAssistantFeatureFlagEnabled(
-      "feature_flags.guardian-verify-setup.enabled",
-      config,
-    )
-  ) {
-    parts.push(buildVerificationRoutingSection());
-  }
-  parts.push(buildAttachmentSection());
-  parts.push(buildInChatConfigurationSection());
-  parts.push(buildVoiceSetupRoutingSection());
-  parts.push(buildPhoneCallsRoutingSection());
-  parts.push(buildChannelCommandIntentSection());
-
-  if (!isOnboardingComplete()) {
-    parts.push(buildStarterTaskPlaybookSection());
-  }
-  if (!hasNoClient) parts.push(buildSystemPermissionSection());
-  parts.push(buildSwarmGuidanceSection());
-  parts.push(buildAccessPreferenceSection(hasNoClient));
-  parts.push(buildIntegrationSection());
-  parts.push(buildMemoryPersistenceSection());
-  parts.push(buildMemoryRecallSection());
-  parts.push(buildWorkspaceReflectionSection());
-  parts.push(buildLearningMemorySection());
+  // Configuration section removed — workspace files are self-describing,
+  // tool routing lives in tool descriptions.
+  // External Communications Identity removed — guidance lives in messaging
+  // and phone-calls skill SKILL.md files.
+  const integrationSection = buildIntegrationSection();
+  if (integrationSection) dynamicParts.push(integrationSection);
 
-  return appendSkillsCatalog(parts.join("\n\n"));
-}
+  const dynamicWithSkills = appendSkillsCatalog(dynamicParts.join("\n\n"));
 
-function buildTaskScheduleReminderRoutingSection(): string {
-  return [
-    "## Tool Routing: Tasks vs Schedules vs Notifications",
-    "",
-    'Three tools, each for a different purpose. Load the "Time-Based Actions" skill for the full decision framework.',
-    "",
-    "| Tool | Purpose |",
-    "|------|---------|",
-    '| `task_list_add` | Track work — no time trigger ("add to my tasks", "remind me to X" without a time) |',
-    '| `schedule_create` | Any time-based automation — recurring cron/RRULE ("every day at 9am") OR one-shot future alert with `fire_at` ("remind me at 3pm") |',
-    "| `send_notification` | **Immediate-only** — fires instantly, NO delay capability |",
-    "",
-    "### Critical: `send_notification` is immediate-only",
-    "NEVER use `send_notification` for future-time requests — it fires NOW. Use `schedule_create` with `fire_at` for any delayed alert.",
-    "",
-    "### Quick routing rules",
-    "- Future time, one-shot → `schedule_create` with `fire_at`",
-    "- Recurring pattern → `schedule_create`",
-    "- No time, track as work → `task_list_add`",
-    "- Instant alert → `send_notification`",
-    "- Modify existing task → `task_list_update` (NOT `task_list_add`)",
-    "- Remove task → `task_list_remove` (NOT `task_list_update`)",
-    "",
-    "### Entity type routing: work items vs task templates",
-    "",
-    "Two entity types with separate ID spaces — do NOT mix:",
-    "- **Work items** (task queue) — task_list_add, task_list_show, task_list_update, task_list_remove",
-    "- **Task templates** (reusable definitions) — task_save, task_list, task_run, task_delete",
-    "",
-    'If an error says "entity mismatch", read the corrective action and selector fields it provides to pick the right tool.',
-    "",
-  ].join("\n");
-}
-
-export function buildVerificationRoutingSection(): string {
-  return [
-    "## Routing: Guardian Verification",
-    "",
-    "When the user wants to verify their identity as the trusted guardian for a messaging channel, load the **Guardian Verify Setup** skill.",
-    'Interpret phrasing like "help me set myself up as your guardian" as the user asking to verify themselves as guardian (not asking the assistant to self-assign permissions).',
-    'Do not give conceptual "I cannot set myself as guardian" explanations unless the user explicitly asks a conceptual/security question.',
-    "",
-    "### Trigger phrases",
-    '- "verify guardian"',
-    '- "verify my Telegram account"',
-    '- "verify phone channel"',
-    '- "verify my phone number"',
-    '- "set up guardian verification"',
-    "",
-    "### What it does",
-    "The skill walks through outbound guardian verification for phone or Telegram:",
-    "1. Confirm channel (phone, telegram)",
-    "2. Collect destination (phone number or Telegram handle/chat ID)",
-    "3. Start outbound verification via runtime HTTP API",
-    "4. Guide the user through code entry, resend, or cancel",
-    "",
-    'Load with: `skill_load` using `skill: "guardian-verify-setup"`',
-    "",
-    "### Exclusivity rules",
-    "- Guardian verification intents must only be handled by `guardian-verify-setup` — load it exclusively.",
-    "- Do NOT load `phone-calls` for guardian verification intent routing. The phone-calls skill does not orchestrate verification flows.",
-    '- If the user asks to "load phone-calls and guardian verification", prioritize `guardian-verify-setup` and continue the verification flow. Only load `phone-calls` if the user also asks to configure or place regular calls.',
-    '- If the user has already explicitly specified a channel (e.g., "verify my phone for voice", "verify my Telegram"), do not re-ask which channel unless the input is contradictory.',
-  ].join("\n");
+  return (
+    staticParts.join("\n\n") + SYSTEM_PROMPT_CACHE_BOUNDARY + dynamicWithSkills
+  );
 }
 
 function buildAttachmentSection(): string {
   return [
     "## Sending Files to the User",
     "",
-    "To deliver any file you create or download (images, videos, PDFs, audio, etc.) to the user, you MUST include a self-closing XML tag in your response text:",
-    "",
-    "```",
-    '<vellum-attachment source="sandbox" path="scratch/output.png" />',
-    "```",
-    "",
-    "**CRITICAL:** This tag is the ONLY way files reach the user. If you save a file to disk but do not include the tag, the user will NOT see it. Always emit the tag after creating or downloading a file.",
+    'To deliver files to the user, include `<vellum-attachment source="sandbox" path="scratch/output.png" />` in your response text. This tag is the ONLY way files reach the user - omitting it means the user won\'t see the file.',
     "",
-    "- `source`: `sandbox` (default, files inside the sandbox working directory) or `host` (absolute paths on the host filesystem — requires user approval).",
-    "- `path`: Required. Relative path for sandbox, absolute path for host.",
-    "- `filename`: Optional override for the delivered filename (defaults to the basename of the path).",
-    "- `mime_type`: Optional MIME type override (inferred from the file extension if omitted).",
+    'Use `source="host"` with an absolute path for host filesystem files. Optional attributes: `filename` (display name override), `mime_type` (override auto-detection).',
     "",
-    'Example: `<vellum-attachment source="sandbox" path="scratch/chart.png" />`',
-    "",
-    "Limits: 20 MB per attachment. Tool outputs that produce image or file content blocks are also automatically converted into attachments.",
-    "",
-    "### Inline Images and GIFs",
-    "Embed images/GIFs inline using markdown: `![description](URL)`. Do NOT wrap in code fences.",
-  ].join("\n");
-}
-
-export function buildStarterTaskPlaybookSection(): string {
-  return [
-    "## Starter Task Playbooks",
-    "",
-    "When the user clicks a starter task card in the dashboard, you receive a deterministic kickoff message in the format `[STARTER_TASK:<task_id>]`. Follow the playbook for that task exactly.",
-    "",
-    "### Kickoff intent contract",
-    '- `[STARTER_TASK:make_it_yours]` — "Make it yours" color personalisation flow',
-    '- `[STARTER_TASK:research_topic]` — "Research something for me" flow',
-    '- `[STARTER_TASK:research_to_ui]` — "Turn it into a webpage or interactive UI" flow',
-    "",
-    "### Playbook: make_it_yours",
-    "Goal: Help the user choose an accent color preference for apps and interfaces.",
-    "",
-    "1. If the user's locale is missing or has `confidence: low` in USER.md, briefly confirm their location/language before proceeding.",
-    "2. Present a concise set of accent color options (e.g. 5-7 curated colors with names and hex codes). Keep it short and scannable.",
-    '3. Let the user pick one. Accept color names, hex values, or descriptions (e.g. "something warm").',
-    '4. Confirm the selection: "I\'ll set your accent color to **{label}** ({hex}). Sound good?"',
-    "5. On confirmation:",
-    '   - Use `app_file_edit` to update the `## Color Preference` section in USER.md with `label`, `hex`, and `source: "user_selected"`.',
-    "   - Use `app_file_edit` to update the `## Onboarding Tasks` section: set `make_it_yours` to `done`.",
-    "6. If the user declines or wants to skip, set `make_it_yours` to `skipped` in USER.md and move on.",
-    "",
-    "### Playbook: research_topic",
-    "Goal: Research a topic the user is interested in and summarise findings.",
-    "",
-    '1. Ask the user what topic they\'d like researched. Be specific: "What would you like me to look into?"',
-    "2. Once given a topic, use available tools (web search, browser, etc.) to gather information.",
-    "3. Synthesise the findings into a clear, well-structured summary.",
-    "4. Update the `## Onboarding Tasks` section in USER.md: set `research_topic` to `done`.",
-    "",
-    "### Playbook: research_to_ui",
-    "Goal: Transform research (from a prior research_topic task or current conversation context) into a visual webpage or interactive UI.",
-    "",
-    "1. Check the conversation history for prior research content. If none exists, ask the user what content they'd like visualised.",
-    "2. Synthesise the research into a polished, interactive HTML page using `app_create`.",
-    "3. Follow all Dynamic UI quality standards (anti-AI-slop rules, design tokens, hover states, etc.).",
-    "4. Update the `## Onboarding Tasks` section in USER.md: set `research_to_ui` to `done`.",
-    "",
-    "### General rules for all starter tasks",
-    "- Update the relevant task status in the `## Onboarding Tasks` section of USER.md as you progress (`in_progress` when starting, `done` when complete).",
-    "- Respect trust gating: do NOT ask for elevated permissions during any starter task flow. These are introductory experiences.",
-    "- Keep responses concise and action-oriented. Avoid lengthy explanations of what you're about to do.",
-    "- If the user deviates from the flow, adapt gracefully. Complete the task if possible, or mark it as `deferred_to_dashboard`.",
+    "Embed images/GIFs inline using markdown: `![description](URL)`.",
   ].join("\n");
 }
 
@@ -341,293 +214,27 @@ function buildInChatConfigurationSection(): string {
   return [
     "## In-Chat Configuration",
     "",
-    "When the user needs to configure a value (API keys, OAuth credentials, webhook URLs, or any setting that can be changed from the Settings page), **always collect it conversationally in the chat first** rather than directing them to the Settings page.",
-    "",
-    "**How to collect credentials and secrets:**",
-    '- Use `credential_store` with `action: "prompt"` to present a secure input field. The value never appears in the conversation.',
-    '- For OAuth flows, use `credential_store` with `action: "oauth2_connect"` to handle the authorization in-browser. Some services (e.g. Twitter/X) define their own auth flow via dedicated skill instructions — check the service\'s skill documentation for provider-specific setup steps.',
-    "- For non-secret config values (e.g. a public URL, a webhook URL), ask the user directly in the conversation and use the appropriate config tool to persist the value.",
-    "",
-    '**After saving a value**, confirm success with a message like: "Great, saved! You can always update this from the Settings page."',
-    "",
-    "**Never tell the user to go to Settings to enter a value.** The Settings page is for reviewing and updating existing configuration, not for initial setup. Always prefer the in-chat flow for first-time configuration.",
-    "",
-    "### Avatar Customisation",
-    "",
-    'You can change your avatar appearance using the `set_avatar` tool. When the user asks to change, update, or customise your avatar, use `set_avatar` with a `description` parameter describing the desired appearance (e.g. "a friendly purple cat with green eyes wearing a tiny hat"). The tool generates an avatar image and updates all connected clients automatically.',
-    "",
-    "**After generating a new avatar**, always update the `## Avatar` section in `IDENTITY.md` with a brief description of the current avatar appearance. This ensures you remember what you look like across sessions. Example:",
-    "```",
-    "## Avatar",
-    "A friendly purple cat with green eyes wearing a tiny hat",
-    "```",
-  ].join("\n");
-}
-
-export function buildVoiceSetupRoutingSection(): string {
-  return [
-    "## Routing: Voice Setup & Troubleshooting",
-    "",
-    "Voice features include push-to-talk (PTT) and text-to-speech.",
-    "",
-    "### Quick changes — use `voice_config_update` directly",
-    '- "Change my PTT key to ctrl" — call `voice_config_update` with `setting: "activation_key"`',
-    '- "Set conversation timeout to 30 seconds" — call `voice_config_update` with `setting: "conversation_timeout"`',
-    "",
-    "For simple setting changes, use the tool directly without loading the voice-setup skill.",
-    "",
-    "### Guided setup or troubleshooting — load the voice-setup skill",
-    'Load with: `skill_load` using `skill: "voice-setup"`',
-    "",
-    "**Trigger phrases:**",
-    '- "Help me set up voice"',
-    '- "Set up push-to-talk"',
-    '- "Configure voice / PTT"',
-    '- "PTT isn\'t working" / "push-to-talk not working"',
-    '- "Recording but no text"',
-    '- "Microphone not working"',
-    '- "Set up ElevenLabs" / "configure TTS"',
-    "",
-    "### Disambiguation",
-    "- Voice setup (this skill) = **local PTT, microphone permissions** on the Mac desktop app.",
-    "- Phone calls skill = **Twilio-powered voice calls** over the phone network. Completely separate.",
-    '- If the user says "voice" in the context of phone calls or Twilio, load `phone-calls` instead.',
-  ].join("\n");
-}
-
-export function buildPhoneCallsRoutingSection(): string {
-  return [
-    "## Routing: Phone Calls",
-    "",
-    "When the user asks to set up phone calling, place a call, configure Twilio for voice, or anything related to outbound/inbound phone calls, load the **Phone Calls** skill.",
-    "",
-    "### Trigger phrases",
-    '- "Set up phone calling" / "enable calls"',
-    '- "Make a call to..." / "call [number/business]"',
-    '- "Configure Twilio" (for voice calls)',
-    '- "Can you make phone calls?"',
-    '- "Set up my phone number"',
-    "",
-    "### What it does",
-    "The skill handles the full phone calling lifecycle:",
-    "1. Twilio credential setup (delegates to twilio-setup skill)",
-    "2. Public ingress configuration (delegates to public-ingress skill)",
-    "3. Enabling the calls feature",
-    "4. Placing outbound calls and receiving inbound calls",
-    "5. Voice quality configuration (standard Twilio TTS or ElevenLabs)",
-    "",
-    'Load with: `skill_load` using `skill: "phone-calls"`',
-    "",
-    "### Exclusivity rules",
-    "- Do NOT improvise Twilio setup instructions from general knowledge — always load the skill first.",
-    "- Do NOT confuse with voice-setup (local PTT/microphone) or guardian-verify-setup (channel verification).",
-    '- If the user says "voice" in the context of phone calls or Twilio, load phone-calls, not voice-setup.',
-    "- For guardian voice verification specifically, load guardian-verify-setup instead.",
-  ].join("\n");
-}
-
-function buildToolPermissionSection(): string {
-  return [
-    "## Tool Permissions",
-    "",
-    "Some tools (host_bash, host_file_write, host_file_edit, host_file_read) require your user's approval before they run. When you call one of these tools, your user sees **Allow / Don't Allow** buttons in the chat directly below your message.",
-    "",
-    "**CRITICAL RULE:** You MUST ALWAYS output a text message BEFORE calling any tool that requires approval. NEVER call a permission-gated tool without preceding text. Your user needs context to decide whether to allow.",
-    "",
-    '**IMPORTANT:** If your user has already granted broad approval for the current conversation (e.g. via "Allow for 10 minutes", "Allow for this thread", or "Always Allow"), do NOT ask for permission again. Instead, just briefly describe what you\'re about to do and proceed. Only ask "Can you allow?" on the FIRST tool call when you haven\'t been granted permission yet.',
-    "",
-    "Your text should follow this pattern:",
-    "1. **Acknowledge** the request conversationally.",
-    '2. **Explain what you need at a high level** (e.g. "I\'ll need to look through your Downloads folder"). Do NOT include raw terminal commands or backtick code. Keep it non-technical.',
-    "3. **State safety** in plain language. Is it read-only? Will it change anything?",
-    "4. **Ask for permission** only if this is the first time and you haven't been previously approved. If you have been approved, just say what you're doing.",
-    "",
-    "Style rules:",
-    '- NEVER use em dashes (the long dash). Use commas, periods, or "and" instead.',
-    "- NEVER show raw commands in backticks like `ls -lt ~/Downloads`. Describe the action in plain English.",
-    "- Keep it conversational, like you're talking to a friend.",
-    "",
-    'First time (no prior approval): "To show your recent downloads, I\'ll need to look through your Downloads folder. This is read-only. Can you allow this?"',
-    'Already approved: "Let me check your Downloads folder real quick."',
-    'Bad: "I\'ll run `ls -lt ~/Desktop/`" (raw command), or calling a tool with no preceding text.',
-    "",
-    "### Handling Permission Denials",
-    "",
-    'When your user denies a tool permission (clicks "Don\'t Allow"), you will receive an error indicating the denial. Follow these rules:',
-    "",
-    "1. **Do NOT immediately retry the tool call.** Retrying without waiting creates another permission prompt, which is annoying and disrespectful of the user's decision.",
-    "2. **Acknowledge the denial.** Tell the user that the action was not performed because they chose not to allow it.",
-    "3. **Ask before retrying.** Ask if they would like you to try again, or if they would prefer a different approach.",
-    "4. **Wait for an explicit response.** Only retry the tool call after the user explicitly confirms they want you to try again.",
-    "5. **Offer alternatives.** If possible, suggest alternative approaches that might not require the denied permission.",
-    "",
-    "Example:",
-    '- Tool denied → "No problem! I wasn\'t able to access your Downloads folder since you chose not to allow it. Would you like me to try again, or is there another way I can help?"',
-    "",
-    "### Always-Available Tools (No Approval Required)",
-    "",
-    "- **file_read** on your workspace directory — You can freely read any file under your `.vellum` workspace at any time. Use this proactively to check files, load context, and inform your responses without asking. **Always use `file_read` for workspace files, never `host_file_read`.** Note: your core prompt files (IDENTITY.md, SOUL.md, USER.md) are already loaded into your system prompt — no need to re-read them at the start of a conversation.",
-    "- **web_search** — You can search the web at any time without approval. Use this to look up documentation, current information, or anything you need.",
-  ].join("\n");
-}
-
-function buildSystemPermissionSection(): string {
-  return [
-    "## System Permissions",
-    "",
-    'When a tool execution fails with a permission/access error (e.g. "Operation not permitted", "EACCES", sandbox denial), use `request_system_permission` to ask your user to grant the required macOS permission through System Settings.',
-    "",
-    "Common cases:",
-    "- Reading files in ~/Documents, ~/Desktop, ~/Downloads → `full_disk_access`",
-    "- Screen capture / recording → `screen_recording`",
-    "- Accessibility / UI automation → `accessibility`",
-    "",
-    "Do NOT explain how to open System Settings manually — the tool handles it with a clickable button.",
-  ].join("\n");
-}
-
-export function buildChannelAwarenessSection(): string {
-  return [
-    "## Channel Awareness & Trust Gating",
-    "",
-    "Each turn may include a `<channel_capabilities>` block in the user message describing what the current channel supports. Use this to adapt your behaviour:",
-    "",
-    "### Channel-specific rules",
-    "- When `dashboard_capable` is `false`, never reference the dashboard UI, settings panels, dynamic pages, or visual pickers. Present data as formatted text.",
-    "- When `supports_dynamic_ui` is `false`, do not call `ui_show`, `ui_update`, or `app_create`.",
-    "- When `supports_voice_input` is `false`, do not ask the user to speak or use their microphone.",
-    "- Non-dashboard channels should defer dashboard-specific actions. Tell the user they can complete those steps later from the desktop app.",
-    "",
-    "### Permission ask trust gating",
-    "- Do NOT proactively ask for elevated permissions (microphone, computer control, file access) until the trust stage field `firstConversationComplete` in USER.md is `true`.",
-    "- Even after `firstConversationComplete`, only ask for permissions that are relevant to the current channel capabilities.",
-    "- Do not ask for microphone permissions on channels where `supports_voice_input` is `false`.",
-    "- Do not ask for computer-control permissions on non-dashboard channels.",
-    "- When you do request a permission, be transparent about what it enables and why you need it.",
-    "",
-    "### Push-to-talk awareness",
-    "- The `<channel_capabilities>` block may include `ptt_activation_key` and `ptt_enabled` fields indicating the user's push-to-talk configuration.",
-    '- You can change the push-to-talk activation key using the `voice_config_update` tool. The key is provided as a JSON PTTActivator payload (e.g. `{"kind":"modifierOnly","modifierFlags":8388608}` for Fn).',
-    "- When the user asks about voice input or push-to-talk settings, use the tool to apply changes directly rather than directing them to settings.",
-    "- When `microphone_permission_granted` is `false`, guide the user to grant microphone access in System Settings before using voice features.",
-    "",
-    "### Platform formatting",
-    "- **WhatsApp:** Do not use markdown tables — use bullet lists instead. No markdown headers — use **bold** or CAPS for emphasis.",
-  ].join("\n");
-}
-
-export function buildChannelCommandIntentSection(): string {
-  return [
-    "## Channel Command Intents",
-    "",
-    "Some channel turns include a `<channel_command_context>` block indicating the user triggered a bot command (e.g. Telegram `/start`).",
-    "",
-    "### `/start` command",
-    "When `command_type` is `start`:",
-    "- Generate a warm, friendly greeting as if the user just arrived for the first time.",
-    "- Keep it brief (1-3 sentences). Do not be verbose or list capabilities.",
-    '- If the user message is `/start` verbatim, treat the entire user intent as "I just started chatting with this bot, say hello."',
-    "- If a `payload` field is present (deep link), acknowledge what the payload references if you recognise it, but still greet warmly.",
-    '- Do NOT reset the conversation, clear history, or treat this as a "new conversation" command.',
-    "- Do NOT mention `/start` or any slash commands in your response.",
-    "- Respond in the same language as the user's locale if available from channel context, otherwise default to English.",
-  ].join("\n");
-}
-
-export function buildExternalCommsIdentitySection(): string {
-  const userRef = resolveUserReference();
-  const userPronouns = resolveUserPronouns();
-  const lines = [
-    "## External Communications Identity",
-    "",
-    "When communicating with people outside your user's household (phone calls, messages to non-guardian contacts, emails to third parties, etc.):",
-    "",
-    `- Refer to yourself as an **assistant**, not an "AI assistant" or "artificial intelligence". Keep identity framing simple and natural.`,
-    `- When introducing who you represent, say you are acting on behalf of **${userRef}**.`,
-  ];
-  if (userPronouns) {
-    lines.push(
-      `- Your user's pronouns are **${userPronouns}**. Use these when referring to your user in the third person.`,
-    );
-  }
-  lines.push(
-    "- Do not volunteer that you are an AI unless directly asked. If asked, answer honestly.",
-    "- This is guidance for natural, human-like communication — not a hard constraint. Occasional variations are acceptable.",
-  );
-  return lines.join("\n");
-}
-
-export function buildSwarmGuidanceSection(): string {
-  return [
-    "## Parallel Task Orchestration",
-    "",
-    'When a task has **multiple independent parts** that benefit from parallel execution (e.g. "research X, implement Y, and review Z"), load the `orchestration` skill using `skill_load` first, then use `swarm_delegate` to decompose and run them in parallel. For single-focus tasks, work directly — do not decompose them into a swarm.',
+    "When the user needs to configure a value, collect it conversationally in the chat. Never direct the user to the Settings page for initial setup - Settings is for reviewing and updating existing configuration.",
   ].join("\n");
 }
 
 function buildAccessPreferenceSection(hasNoClient: boolean): string {
   if (hasNoClient) {
     return [
-      "## External Service Access Preference",
-      "",
-      "When interacting with external services (GitHub, Slack, Linear, Jira, cloud providers, etc.),",
-      "follow this priority order:",
+      "## External Service Access",
       "",
-      "1. **Sandbox first (`bash`)** — Always try to do things in your own sandbox environment first.",
-      "   If a tool (git, curl, jq, etc.) is not installed, install it yourself using `bash`",
-      "   (e.g. `apt-get install -y git`). The sandbox is your own machine — you have full control.",
-      "2. **web_fetch** — For public endpoints or simple API calls that don't need auth.",
-      "3. **Browser automation as last resort** — Only when the task genuinely requires a browser",
-      "   (e.g., no API exists, visual interaction needed, or OAuth consent screen).",
+      "Priority: (1) sandbox `bash` — install tools yourself; (2) browser automation as last resort (no API, visual interaction, or OAuth consent).",
     ].join("\n");
   }
 
   return [
-    "## External Service Access Preference",
-    "",
-    "When interacting with external services (GitHub, Slack, Linear, Jira, cloud providers, etc.),",
-    "follow this priority order:",
-    "",
-    "1. **Sandbox first (`bash`)** — Always try to do things in your own sandbox environment first.",
-    "   If a tool (git, curl, jq, etc.) is not installed, install it yourself using `bash`",
-    "   (e.g. `apt-get install -y git`). The sandbox is your own machine — you have full control.",
-    "   Only fall back to host tools when you genuinely need access to the user's local files,",
-    "   environment, or host-specific resources (e.g. their local git repos, host-installed CLIs",
-    "   with existing auth, macOS-specific apps).",
-    "2. **CLI tools via host_bash** — If you need access to the user's host environment and a CLI",
-    "   is installed on their machine (gh, slack, linear, jira, aws, gcloud, etc.), use it.",
-    "   CLIs handle auth, pagination, and output formatting.",
-    "   Use --json or equivalent flags for structured output when available.",
-    "3. **Direct API calls via host_bash** — Use curl/httpie with API tokens from credential_store.",
-    "   Faster and more reliable than browser automation.",
-    "4. **web_fetch** — For public endpoints or simple API calls that don't need auth.",
-    "5. **Browser automation as last resort** — Only when the task genuinely requires a browser",
-    "   (e.g., no API exists, visual interaction needed, or OAuth consent screen).",
+    "## External Service Access",
     "",
-    "Before reaching for host tools or browser automation, ask yourself:",
-    "- Can I do this entirely in my sandbox? (install tools, clone repos, run commands)",
-    "- Do I actually need something from the user's host machine?",
-    "",
-    "If you can do it in your sandbox, do it there. Only use host tools when you need the user's",
-    "local files, credentials, or host-specific capabilities.",
+    "Priority: (1) sandbox `bash` - install tools yourself, only fall back to host when you need local files/auth; (2) `host_bash` with CLIs (gh, aws, etc.) using --json flags; (3) browser automation as last resort (no API, visual interaction, or OAuth consent).",
     ...(isMacOS()
       ? [
           "",
-          "On macOS, also consider the `macos-automation` skill for interacting with native apps",
-          "(Messages, Contacts, Calendar, Mail, Reminders, Music, Finder, etc.) via osascript.",
-          "",
-          "### Foreground Computer Use — Last Resort",
-          "",
-          "Computer use tools (clicking, typing, scrolling) take over the user's cursor and keyboard.",
-          "They are disruptive and should be your LAST resort. Prefer this hierarchy:",
-          "",
-          "1. **CLI tools / osascript** — Use `host_bash` with shell commands or `osascript` with",
-          "   AppleScript to accomplish tasks in the background without interrupting the user.",
-          "2. **Background computer use** — If you must interact with a GUI app, prefer AppleScript",
-          '   automation (e.g. `tell application "Safari" to set URL of current tab to ...`).',
-          "3. **Foreground computer use** — Only use computer use tools when the task genuinely",
-          "   cannot be done any other way (e.g. complex multi-step GUI interactions with no scripting",
-          "   support) or the user explicitly asks you to take control.",
+          "On macOS, prefer osascript/CLI via `host_bash` over computer use tools, which take over the user's cursor. Use foreground computer use only when no scripting alternative exists or the user explicitly asks.",
         ]
       : []),
   ].join("\n");
@@ -655,77 +262,10 @@ function buildIntegrationSection(): string {
   return lines.join("\n");
 }
 
-function buildMemoryPersistenceSection(): string {
-  return [
-    "## Memory Persistence",
-    "",
-    "Your memory does not survive session restarts. If you want to remember something, **save it**.",
-    "",
-    '- Use `memory_manage` with `op: "save"` for facts, preferences, learnings, and anything worth recalling later.',
-    "- Update workspace files (USER.md, SOUL.md) for profile and personality changes.",
-    '- When someone says "remember this," save it immediately — don\'t rely on keeping it in context.',
-    "- When you make a mistake, save the lesson so future-you doesn't repeat it.",
-    "",
-    "Saved > unsaved. Always.",
-  ].join("\n");
-}
-
-function buildMemoryRecallSection(): string {
-  return [
-    "## Memory Recall",
-    "",
-    "You have access to a `memory_recall` tool for deep memory retrieval. Use it when:",
-    "",
-    "- The user asks about past conversations, decisions, or context you don't have in the current window",
-    "- You need to recall specific facts, preferences, or project details",
-    "- The auto-injected memory context doesn't contain what you need",
-    "- The user references something from a previous session",
-    "",
-    "The tool uses hybrid search (dense and sparse vectors) supplemented by recency. Be specific in your query for best results.",
-  ].join("\n");
-}
-
-function buildWorkspaceReflectionSection(): string {
-  return [
-    "## Workspace Reflection",
-    "",
-    "Before you finish responding to a conversation, pause and consider: did you learn anything worth saving?",
-    "",
-    "- Did your user share personal facts (name, role, timezone, preferences)?",
-    "- Did they correct your behavior or express a preference about how you communicate?",
-    "- Did they mention a project, tool, or workflow you should remember?",
-    "- Did you adapt your style in a way that worked well and should persist?",
-    "",
-    "If yes, briefly explain what you're updating, then update the relevant workspace file (USER.md, SOUL.md, or IDENTITY.md) as part of your response.",
-  ].join("\n");
-}
-
-function buildLearningMemorySection(): string {
-  return [
-    "## Learning from Mistakes",
-    "",
-    "When you make a mistake, hit a dead end, or discover something non-obvious, save it to memory so you don't repeat it.",
-    "",
-    'Use `memory_manage` with `op: "save", kind: "constraint"` for:',
-    "- **Mistakes and corrections** — wrong assumptions, failed approaches, gotchas you ran into",
-    "- **Discoveries** — undocumented behaviors, surprising API quirks, things that weren't obvious",
-    "- **Working solutions** — the approach that actually worked after trial and error",
-    "- **Tool/service insights** — rate limits, auth flows, CLI flags that matter",
-    "",
-    "The statement should capture both what happened and the takeaway. Write it as advice to your future self.",
-    "",
-    "Examples:",
-    '- `memory_manage({ op: "save", kind: "constraint", subject: "macOS Shortcuts CLI", statement: "shortcuts CLI requires full disk access to export shortcuts — if permission is denied, guide the user to grant it in System Settings rather than retrying." })`',
-    '- `memory_manage({ op: "save", kind: "constraint", subject: "Gmail API pagination", statement: "Gmail search returns max 100 results per page. Always check nextPageToken and loop if the user asks for \'all\' messages." })`',
-    "",
-    "Don't overthink it. If you catch yourself thinking \"I'll remember that for next time,\" save it.",
-  ].join("\n");
-}
-
 function buildContainerizedSection(): string {
   const baseDataDir = getBaseDataDir() ?? "$BASE_DATA_DIR";
   return [
-    "## Running in a Container — Data Persistence",
+    "## Running in a Container - Data Persistence",
     "",
     `You are running inside a container. Only the directory \`${baseDataDir}\` is mounted to a persistent volume.`,
     "",
@@ -735,120 +275,25 @@ function buildContainerizedSection(): string {
     `- Always store new data, notes, memories, configs, and downloads under \`${baseDataDir}\``,
     "- Never write persistent data to system directories, `/tmp`, or paths outside the mounted volume",
     "- When in doubt, prefer paths nested under the data directory",
-    "- If you create a file that is only needed temporarily (scratch files, intermediate outputs, download staging), delete it when you are done — disk space on the persistent volume is finite and will grow unboundedly if temp files are not cleaned up",
+    "- If you create a file that is only needed temporarily (scratch files, intermediate outputs, download staging), delete it when you are done - disk space on the persistent volume is finite and will grow unboundedly if temp files are not cleaned up",
   ].join("\n");
 }
 
-function buildPostToolResponseSection(): string {
+function buildParallelToolCallsSection(): string {
   return [
-    "## Tool Call Timing",
-    "",
-    "**Call tools FIRST, explain AFTER:**",
-    "- When a user request requires a tool, call it immediately at the start of your response",
-    "- If the request needs multiple tool steps, stay silent while you work and respond once you have concrete results",
-    '- Do NOT narrate retries or internal process chatter (for example: "hmm", "that didn\'t work", "let me try...")',
-    "- Speak mid-workflow only when you need user input (permission, clarification, or blocker)",
-    "- Do NOT provide conversational preamble before calling tools",
-    "",
-    "Example (CORRECT):",
-    "  → Call document_create",
-    "  → Call document_update",
-    '  → Text: "Drafted and filled your blog post. Review and tell me what to change."',
-    "",
-    "Example (WRONG):",
-    '  → Text: "I\'ll try one approach... hmm not that... trying again..."',
-    "  → Call document_create",
-    "",
-    "For permission-gated tools, send one short context sentence immediately before the tool call so the user can make an informed allow/deny decision.",
-    "",
-    '**Reason field:** For every tool call, include a `reason` parameter — a brief, non-technical explanation of what you are doing and why. This is shown to the user as a live status update. Use simple language a non-technical person would understand (e.g. "Checking your project settings" not "file_read config.ts").',
-  ].join("\n");
-}
-
-function buildConfigSection(hasNoClient: boolean): string {
-  // Always use `file_edit` (not `host_file_edit`) for workspace files — file_edit
-  // handles sandbox path mapping internally, and host_file_edit is permission-gated
-  // which would trigger approval prompts for routine workspace updates.
-  const hostWorkspaceDir = getWorkspaceDir();
-
-  const config = getConfig();
-  const configPreamble = `Your configuration directory is \`${hostWorkspaceDir}/\`.`;
-
-  const fileToolGuidance = hasNoClient
-    ? `${configPreamble} **Always use \`file_read\` and \`file_edit\` for these files** — they are inside your sandbox working directory:`
-    : `${configPreamble} **Always use \`file_read\` and \`file_edit\` (not \`host_file_read\` / \`host_file_edit\`) for these files** — they are inside your sandbox working directory and do not require host access or user approval:`;
-
-  return [
-    "## Configuration",
-    `- **Active model**: \`${config.model}\` (provider: ${config.provider})`,
-    fileToolGuidance,
-    "",
-    "- `IDENTITY.md` — Your name, nature, personality, and emoji. Updated during the first-run ritual.",
-    "- `SOUL.md` — Core principles, personality, and evolution guidance. Your behavioral foundation.",
-    "- `USER.md` — Profile of your user. Update as you learn about them over time.",
-    "- `HEARTBEAT.md` — Checklist for periodic heartbeat runs. When heartbeat is enabled, the assistant runs this checklist on a timer and flags anything that needs attention. Edit this file to control what gets checked each run.",
-    "- `BOOTSTRAP.md` — First-run ritual script (only present during onboarding; you delete it when done).",
-    "- `UPDATES.md` — Release update notes (created automatically on new releases; delete when updates are actioned).",
-    "- `skills/` — Directory of installed skills (loaded automatically at startup).",
-    "",
-    "### Heartbeat",
-    "",
-    "The heartbeat feature runs your `HEARTBEAT.md` checklist periodically in a background thread. To enable it, set `heartbeat.enabled: true` and `heartbeat.intervalMs` (default: 3600000 = 1 hour) in `config.json`. You can also set `heartbeat.activeHoursStart` and `heartbeat.activeHoursEnd` (0-23) to restrict runs to certain hours. When asked to set up a heartbeat, edit both the config and `HEARTBEAT.md` directly — no restart is needed for checklist changes, but toggling `heartbeat.enabled` requires a daemon restart.",
-    "",
-    "### Proactive Workspace Editing",
-    "",
-    `You MUST actively update your workspace files as you learn. You don't need to ask your user whether it's okay — just briefly explain what you're updating, then use \`file_edit\` to make targeted edits.`,
-    "",
-    "**USER.md** — update when you learn:",
-    "- Their name or what they prefer to be called",
-    "- Projects they're working on, tools they use, languages they code in",
-    "- Communication preferences (concise vs detailed, formal vs casual)",
-    "- Interests, hobbies, or context that helps you assist them better",
-    "- Anything else about your user that will help you serve them better",
-    "",
-    "**SOUL.md** — update when you notice:",
-    "- They prefer a different tone or interaction style (add to Personality or User-Specific Behavior)",
-    '- A behavioral pattern worth codifying (e.g. "always explain before acting", "skip preamble")',
-    "- You've adapted in a way that's working well and should persist",
-    "- You decide to change your personality to better serve your user",
-    "",
-    "**IDENTITY.md** — update when:",
-    "- They rename you or change your role",
-    "- Your avatar appearance changes (update the `## Avatar` section with a description of the new look)",
-    "",
-    ...(hasNoClient
-      ? [
-          "When reading or updating workspace files, always use the sandbox tools (`file_read`, `file_edit`).",
-        ]
-      : [
-          "When reading or updating workspace files, always use the sandbox tools (`file_read`, `file_edit`). Never use `host_file_read` or `host_file_edit` for workspace files — those are for host-only resources outside your workspace.",
-        ]),
-    "",
-    "When updating, read the file first, then make a targeted edit. Include all useful information, but don't bloat the files over time",
+    "<use_parallel_tool_calls>",
+    "For maximum efficiency, whenever you perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. Prioritize calling tools in parallel whenever possible. For example, when reading 3 files, run 3 tool calls in parallel to read all 3 files into context at the same time. When running multiple read-only commands like `ls` or `list_dir`, always run all of the commands in parallel. Err on the side of maximizing parallel tool calls rather than running too many tools sequentially.",
+    "</use_parallel_tool_calls>",
   ].join("\n");
 }
 
 export function buildCliReferenceSection(): string {
-  if (cachedCliHelp === undefined) {
-    cachedCliHelp = CLI_HELP_REFERENCE.trim();
-  }
-
   return [
     "## Assistant CLI",
     "",
-    "The `assistant` CLI is available in the sandbox. Always use the `bash` tool (never `host_bash`) when running `assistant` commands.",
-    "For account and authentication work, prefer real `assistant` CLI workflows over any legacy account-record abstraction.",
-    "- Use `assistant credentials ...` for stored secrets and credential metadata.",
-    "- Use `assistant oauth connections token <provider-key>` for connected integration tokens.",
-    "- Use `assistant mcp auth <name>` when an MCP server needs OAuth login.",
-    "- Use `assistant platform status` for platform-linked deployment and auth context.",
-    "- If a bundled skill documents a service-specific `assistant <service>` auth or session flow, follow that CLI exactly.",
-    "",
-    "```",
-    cachedCliHelp,
-    "```",
+    "The `assistant` CLI is available in the sandbox for managing assistant settings, integrations, and services. Always use the `bash` tool (never `host_bash`) when running `assistant` commands.",
     "",
-    "Run `assistant <command> --help` for detailed help on any subcommand.",
+    "Run `assistant --help` to see all available commands, or `assistant <command> --help` for detailed help on any subcommand.",
   ].join("\n");
 }
 
@@ -881,6 +326,34 @@ export function stripCommentLines(content: string): string {
     .trim();
 }
 
+/**
+ * Returns true when the prompt file content is still the unmodified template
+ * shipped with the daemon.  Compares the stripped workspace content against
+ * the stripped bundled template source so the check stays accurate even if
+ * templates are edited in future releases.
+ */
+export function isTemplateContent(
+  content: string | null,
+  templateFileName: string,
+): boolean {
+  if (content == null) return false;
+  const templatesDir = resolveBundledDir(
+    import.meta.dirname ?? __dirname,
+    "templates",
+    "templates",
+  );
+  const templatePath = join(templatesDir, templateFileName);
+  if (!existsSync(templatePath)) return false;
+  try {
+    const templateContent = stripCommentLines(
+      readFileSync(templatePath, "utf-8"),
+    );
+    return content === templateContent;
+  } catch {
+    return false;
+  }
+}
+
 function readPromptFile(path: string): string | null {
   if (!existsSync(path)) return null;
 
@@ -895,6 +368,27 @@ function readPromptFile(path: string): string | null {
   }
 }
 
+/**
+ * Reads the core identity/personality prompt files (SOUL.md, IDENTITY.md, USER.md)
+ * and concatenates whichever exist. Returns null if none are present.
+ *
+ * This is useful for injecting identity context into subsystems (e.g. memory
+ * extraction) that run outside the main system prompt pipeline.
+ */
+export function buildCoreIdentityContext(): string | null {
+  const parts: string[] = [];
+  for (const file of PROMPT_FILES) {
+    const content = readPromptFile(getWorkspacePromptPath(file));
+    if (!content) continue;
+    // SOUL.md is always included — it provides personality defaults even
+    // before onboarding completes.  Only skip IDENTITY.md and USER.md when
+    // they are still unmodified templates (matching buildSystemPrompt).
+    if (file !== "SOUL.md" && isTemplateContent(content, file)) continue;
+    parts.push(content);
+  }
+  return parts.length > 0 ? parts.join("\n\n") : null;
+}
+
 function appendSkillsCatalog(basePrompt: string): string {
   const skills = loadSkillCatalog();
   const config = getConfig();
@@ -910,75 +404,9 @@ function appendSkillsCatalog(basePrompt: string): string {
   const catalog = formatSkillsCatalog(flagFiltered);
   if (catalog) sections.push(catalog);
 
-  sections.push(buildDynamicSkillWorkflowSection(config, flagFiltered));
-
   return sections.join("\n\n");
 }
 
-function buildDynamicSkillWorkflowSection(
-  _config: import("../config/schema.js").AssistantConfig,
-  activeSkills: SkillSummary[],
-): string {
-  const lines = [
-    "## Dynamic Skill Authoring Workflow",
-    "",
-    "When no existing tool or skill can satisfy a request:",
-    "1. Validate the gap — confirm no existing tool/skill covers it.",
-    "2. Draft a TypeScript snippet exporting a `default` or `run` function (`(input: unknown) => unknown | Promise<unknown>`).",
-    '3. Test the snippet by writing it to a temp file with `bash` (e.g., `bash command="mkdir -p /tmp/vellum-eval && cat > /tmp/vellum-eval/snippet.ts << \'SNIPPET_EOF\'\\n...\\nSNIPPET_EOF"`) and running it with `bash command="bun run /tmp/vellum-eval/snippet.ts"`. Do not use `file_write` for temp files outside the working directory. Iterate until it passes (max 3 attempts, then ask the user). Clean up temp files after.',
-    "4. Persist with `scaffold_managed_skill` only after user consent.",
-    "5. Load with `skill_load` before use.",
-    "",
-    "**Never persist or delete skills without explicit user confirmation.** To remove: `delete_managed_skill`.",
-    "After a skill is written or deleted, the next turn may run in a recreated session due to file-watcher eviction. Continue normally.",
-  ];
-
-  const activeSkillIds = new Set(activeSkills.map((s) => s.id));
-
-  if (activeSkillIds.has("browser")) {
-    lines.push(
-      "",
-      "### Browser Skill Prerequisite",
-      'If you need browser capabilities (navigating web pages, clicking elements, extracting content) and `browser_*` tools are not available, load the "browser" skill first using `skill_load`.',
-    );
-  }
-
-  if (activeSkillIds.has("messaging")) {
-    lines.push(
-      "",
-      "### Messaging Skill",
-      'When the user asks about email, messaging, inbox management, or wants to read/send/search messages on any platform (Gmail, Slack, Telegram), load the "messaging" skill using `skill_load`. The messaging skill handles connection setup, credential flows, and all messaging operations — do not improvise setup instructions from general knowledge.',
-    );
-  }
-
-  lines.push(
-    "",
-    "### Community Skills Discovery",
-    "",
-    "When no built-in skill satisfies a request, search the community skills.sh registry:",
-    "1. Run `assistant skills search <query>` to find community skills. Results include install counts and security audit badges (ATH, Socket, Snyk).",
-    "2. Present the search results to the user, highlighting the security audit status. ATH is Gen Agent Trust Hub. Audits show PASS (safe/low risk), WARN (medium risk), or FAIL (high/critical risk) for each provider.",
-    "3. Check the skill's **source owner** to determine the trust level:",
-    "   - **Vellum-owned** (source starts with `vellum-ai/`): These are first-party skills published by the Vellum team. Install them directly without prompting — they are vetted and trusted.",
-    "   - **Third-party** (any other owner): Ask the user for permission before installing. Say something like: \"I found a community skill that could help with this, but it's published by a third party — we haven't vetted it. Want to install it anyway?\" Share the skill name, source, audit results, and install count.",
-    "4. Install with `assistant skills add <owner>/<repo>@<skill-name>` (e.g., `assistant skills add vercel-labs/skills@find-skills`).",
-    "5. After installation, load the skill with `skill_load` as usual.",
-    "",
-    "**Never install third-party community skills without explicit user confirmation.** Vellum-owned skills (`vellum-ai/*`) can be installed automatically.",
-  );
-
-  return lines.join("\n");
-}
-
-function escapeXml(str: string): string {
-  return str
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&apos;");
-}
-
 /**
  * Build a dynamic description for the mcp-setup skill that includes
  * configured MCP server names, so the model knows which servers exist.
@@ -987,47 +415,31 @@ function getMcpSetupDescription(): string {
   const config = getConfig();
   const servers = config.mcp?.servers;
   if (!servers || Object.keys(servers).length === 0) {
-    return "Add, authenticate, list, and remove MCP (Model Context Protocol) servers";
+    return "Add, authenticate, list, and remove MCP servers";
   }
 
-  const serverNames = Object.keys(servers);
-  return `Manage MCP servers. Configured: ${serverNames.join(", ")}. Load this skill to check status, authenticate, or add/remove servers.`;
+  const serverNames = Object.keys(servers).sort();
+  return `Manage MCP servers. Configured: ${serverNames.join(", ")}. Load to check status, authenticate, or add/remove servers.`;
 }
 
 function formatSkillsCatalog(skills: SkillSummary[]): string {
-  // 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 "";
+  if (skills.length === 0) return "";
 
-  const lines = ["<available_skills>"];
-  for (const skill of visible) {
-    const idAttr = escapeXml(skill.id);
-    const nameAttr = escapeXml(skill.displayName);
-    const descAttr =
-      skill.id === "mcp-setup"
-        ? escapeXml(getMcpSetupDescription())
-        : escapeXml(skill.description);
-    const locAttr = escapeXml(skill.directoryPath);
-    const credAttr = skill.credentialSetupFor
-      ? ` credential-setup-for="${escapeXml(skill.credentialSetupFor)}"`
-      : "";
-    lines.push(
-      `<skill id="${idAttr}" name="${nameAttr}" description="${descAttr}" location="${locAttr}"${credAttr} />`,
-    );
+  const lines = ["## Available Skills", ""];
+  for (const skill of skills) {
+    const desc =
+      skill.id === "mcp-setup" ? getMcpSetupDescription() : skill.description;
+
+    // Build a single line: - **id**: description. Hints. Avoid: ...
+    const parts = [desc.replace(/\.\s*$/, "")];
+    if (skill.activationHints && skill.activationHints.length > 0) {
+      parts.push(skill.activationHints.join(". "));
+    }
+    if (skill.avoidWhen && skill.avoidWhen.length > 0) {
+      parts.push(`Avoid: ${skill.avoidWhen.join(". ")}`);
+    }
+    lines.push(`- **${skill.id}**: ${parts.join(". ")}`);
   }
-  lines.push("</available_skills>");
 
-  return [
-    "## Available Skills",
-    "The following skills are available. Before executing one, call `skill_load` to load the full instructions, then use `skill_execute` to invoke the skill's tools.",
-    "When a credential is missing, check if any skill declares `credential-setup-for` matching that service — if so, load that skill.",
-    "",
-    lines.join("\n"),
-    "",
-  ].join("\n");
+  return lines.join("\n");
 }