@vellumai/assistant 0.4.56 → 0.5.0

package/src/prompts/system-prompt.ts

@@ -1,34 +1,23 @@
 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";
 import { skillFlagKey } from "../config/skill-state.js";
 import { loadSkillCatalog, type SkillSummary } from "../config/skills.js";
-import { isPlatformManaged } from "../inbound/platform-callback-registration.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.
@@ -91,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).
@@ -123,9 +103,6 @@ export interface BuildSystemPromptOptions {
  * cache blocks so that static instructions stay cached even when workspace
  * files change between turns.
  */
-export const SYSTEM_PROMPT_CACHE_BOUNDARY =
-  "\n<!-- SYSTEM_PROMPT_CACHE_BOUNDARY -->\n";
-
 export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
   const hasNoClient = options?.hasNoClient ?? false;
 
@@ -134,27 +111,19 @@ export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
   // 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(
-    "IMPORTANT: Never use em dashes (—) in your messages. Use commas, periods, or just start a new sentence instead.",
-  );
+  staticParts.push(buildParallelToolCallsSection());
   if (getIsContainerized()) staticParts.push(buildContainerizedSection());
   staticParts.push(buildCliReferenceSection());
-  staticParts.push(buildPostToolResponseSection());
-  staticParts.push(buildChannelAwarenessSection());
-  if (!hasNoClient) staticParts.push(buildToolPermissionSection());
-  staticParts.push(buildTaskScheduleReminderRoutingSection());
+  // Tool Permissions section removed — guidance lives in tool descriptions.
+  // Tool Routing section removed — guidance lives in tool descriptions.
   staticParts.push(buildAttachmentSection());
   staticParts.push(buildInChatConfigurationSection());
-  if (!isOnboardingComplete()) {
-    staticParts.push(buildStarterTaskPlaybookSection());
-  }
-  if (!hasNoClient) staticParts.push(buildSystemPermissionSection());
-  staticParts.push(buildSwarmGuidanceSection());
+  // 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));
-  staticParts.push(buildMemoryPersistenceSection());
-  staticParts.push(buildMemoryRecallSection());
-  staticParts.push(buildWorkspaceReflectionSection());
-  staticParts.push(buildLearningMemorySection());
+  // 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,
@@ -174,10 +143,24 @@ export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
   const bootstrap = readPromptFile(bootstrapPath);
   const updates = readPromptFile(updatesPath);
 
-  if (identity) dynamicParts.push(identity);
+  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) dynamicParts.push(user);
-  if (bootstrap && !options?.excludeBootstrap) {
+  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" +
@@ -201,9 +184,12 @@ export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
       ].join("\n"),
     );
   }
-  dynamicParts.push(buildConfigSection(hasNoClient));
-  dynamicParts.push(buildExternalCommsIdentitySection());
-  dynamicParts.push(buildIntegrationSection());
+  // 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);
 
   const dynamicWithSkills = appendSkillsCatalog(dynamicParts.join("\n\n"));
 
@@ -212,63 +198,15 @@ export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
   );
 }
 
-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");
-}
-
 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:",
+    '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.',
     "",
-    "```",
-    '<vellum-attachment source="sandbox" path="scratch/output.png" />',
-    "```",
+    'Use `source="host"` with an absolute path for host filesystem files. Optional attributes: `filename` (display name override), `mime_type` (override auto-detection).',
     "",
-    "**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.",
-    "",
-    "- `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).",
-    "",
-    'Example: `<vellum-attachment source="sandbox" path="scratch/chart.png" />`',
-    "",
-    "Limits: 50 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.",
+    "Embed images/GIFs inline using markdown: `![description](URL)`.",
   ].join("\n");
 }
 
@@ -276,276 +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:**",
-    ...(isPlatformManaged()
-      ? [
-          "- Secrets and API keys are managed through the platform's credential system. Users connect credentials via OAuth or platform-managed secrets — the `credential_store` prompt flow for API keys is not available in managed deployments.",
-          "- For OAuth flows, guide the user to connect through the platform. After connecting, run `assistant oauth connections list` to find the connection ID, and use the `platform_oauth:<connectionId>` handle with CES tools (`make_authenticated_request`, `run_authenticated_command`) for authenticated work.",
-          "- 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.",
-        ]
-      : [
-          '- Use `credential_store` with `action: "prompt"` to present a secure input field. The value never appears in the conversation. Once stored, run `assistant credentials list` to find the service:field identifiers, construct the CES handle as `local_static:<service>/<field>`, and use CES tools (`make_authenticated_request`, `run_authenticated_command`) for authenticated work.',
-          '- 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. After connecting, run `assistant oauth connections list` to find the provider key, construct the CES handle, and use CES tools.',
-          "- 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",
-    "",
-    "When the user asks to change, update, or customise your avatar, load the **vellum-avatar** skill using `skill_load`. The skill covers building a native character from traits, uploading an image, or generating one with AI.",
-    "",
-    "**After any avatar change**, 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 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`.",
-  ].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 conversation", 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.",
-    "",
-    "### Channel command handling",
-    "Some channel turns include a `<channel_command_context>` block indicating the user triggered a bot command (e.g. Telegram `/start`).",
-    "When `command_type` is `start`: generate a warm, brief greeting (1-3 sentences). Treat `/start` verbatim as a hello. Do NOT reset conversation or mention slash commands. If a `payload` is present, acknowledge it warmly. 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",
+    "## External Service Access",
     "",
-    "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. **CES tools for authenticated work** — When a task requires credentials (API keys, OAuth tokens),",
-    "   discover available handles with `assistant credentials list` or `assistant oauth connections list`,",
-    "   then use CES tools (`make_authenticated_request`, `run_authenticated_command`). CES injects",
-    "   credentials securely without exposing raw secrets to the assistant.",
-    "3. **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.",
-    "   Note: `host_bash` is approval-gated and outside the CES secrecy boundary.",
-    "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).",
-    "",
-    "Before reaching for host tools or browser automation, ask yourself:",
-    "- Can I do this entirely in my sandbox? (install tools, clone repos, run commands)",
-    "- Can I use CES tools for authenticated requests instead of extracting raw tokens?",
-    "- Do I actually need something from the user's host machine?",
-    "",
-    "If you can do it in your sandbox or through CES, do it there. Only use host tools when you need the user's",
-    "local files 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");
@@ -573,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.`,
     "",
@@ -653,148 +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.services.inference.model}\` (provider: ${config.services.inference.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 conversation. 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.",
-    "",
-    "### Credential Discovery and Authenticated Work",
-    "",
-    "When you need to make authenticated requests or run commands that require credentials, follow this workflow:",
-    "",
-    "1. **Discover available credentials** by running:",
-    "   - `assistant credentials list` — lists local credentials with their service:field identifiers",
-    "   - `assistant oauth connections list` — lists OAuth connections with provider keys",
-    "   - `assistant credentials list --search <query>` — filter by service, field, or description",
-    ...(isPlatformManaged()
-      ? [
-          "   In managed deployments, credential handles use the `platform_oauth:<connectionId>` format (shown in the `handle` field of `assistant oauth connections list`). Local credential handles (`local_static`, `local_oauth`) are not available in managed mode.",
-        ]
-      : [
-          "   For local credentials, construct the CES handle as `local_static:<service>/<field>` from the listed identifiers. For local OAuth connections, the handle is `local_oauth:<providerKey>/<connectionId>` (shown in the `handle` field of `assistant oauth connections list`). Platform-managed entries use `platform_oauth:<connectionId>` handles, also shown in their `handle` field.",
-        ]),
-    "",
-    "2. **Use CES tools** with the handle to perform authenticated work:",
-    "   - `make_authenticated_request` — authenticated HTTP requests (API calls, webhooks). CES injects the credential and returns the response; the assistant never sees raw secrets.",
-    "   - `run_authenticated_command` — run a command with credential environment variables injected by CES. The command runs inside the CES sandbox.",
-    "   - `manage_secure_command_tool` — install, update, or remove secure command tool bundles. Accepts only bundle metadata for guardian review.",
-    "",
-    "3. **Never reveal raw secrets.** Do not use `assistant credentials reveal` or `assistant oauth connections token` to extract raw token values and pass them to `bash` or `host_bash`. Always route authenticated work through CES tools.",
-    "",
-    "For account setup and credential management (not execution), use:",
-    "- `assistant credentials set ...` — store a new credential",
-    "- `assistant oauth connections connect <provider>` — initiate an OAuth flow",
-    "- `assistant mcp auth <name>` — when an MCP server needs OAuth login",
-    "- `assistant platform status` — platform-linked deployment and auth context",
-    "- If a bundled skill documents a service-specific `assistant <service>` auth or session flow, follow that CLI exactly.",
-    "",
-    "### host_bash and Credentials",
+    "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.",
     "",
-    "`host_bash` is approval-gated and runs on the user's host machine. It is outside the CES secrecy boundary. Do not use `host_bash` to run commands with injected credentials or tokens. If you need authenticated command execution, use `run_authenticated_command` (CES tool) instead.",
-    "",
-    "```",
-    cachedCliHelp,
-    "```",
-    "",
-    "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");
 }
 
@@ -827,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;
 
@@ -852,7 +379,12 @@ export function buildCoreIdentityContext(): string | null {
   const parts: string[] = [];
   for (const file of PROMPT_FILES) {
     const content = readPromptFile(getWorkspacePromptPath(file));
-    if (content) parts.push(content);
+    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;
 }
@@ -872,57 +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.",
-  ];
-
-  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.
@@ -931,44 +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).sort();
-  return `Manage MCP servers. Configured: ${serverNames.join(", ")}. Load this skill to check status, authenticate, or add/remove servers.`;
+  return `Manage MCP servers. Configured: ${serverNames.join(", ")}. Load to check status, authenticate, or add/remove servers.`;
 }
 
 function formatSkillsCatalog(skills: SkillSummary[]): string {
-  const visible = skills;
-  if (visible.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 hintsAttr =
-      skill.activationHints && skill.activationHints.length > 0
-        ? ` hints="${escapeXml(skill.activationHints.join("; "))}"`
-        : "";
-    const avoidAttr =
-      skill.avoidWhen && skill.avoidWhen.length > 0
-        ? ` avoid-when="${escapeXml(skill.avoidWhen.join("; "))}"`
-        : "";
-    lines.push(
-      `<skill id="${idAttr}" name="${nameAttr}" description="${descAttr}"${hintsAttr}${avoidAttr} />`,
-    );
+  if (skills.length === 0) return "";
+
+  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.",
-    "",
-    lines.join("\n"),
-    "",
-  ].join("\n");
+  return lines.join("\n");
 }