feat(skills): workers discover skills on demand via read_skill tool

Previously workers received a single skill's full content injected into
their system prompt at spawn time. This had two problems:
- Workers were locked into one skill chosen by the channel upfront
- Workers couldn't access skills they turned out to need mid-task

New approach (aligned with the design docs):
- Workers see the full skills listing (name + description) in their
  system prompt, same as the channel
- Channel suggests relevant skills via suggested_skills=[...] on
  spawn_worker — these are flagged in the listing but not mandatory
- Workers call the new read_skill tool to fetch the full content of
  any skill they decide is relevant — including ones not suggested
- read_skill reads from the in-memory SkillSet (not the file tool),
  so the workspace boundary is never involved

Changes:
- src/tools/read_skill.rs: new ReadSkillTool, scoped to SkillSet
- src/tools.rs: register ReadSkillTool in create_worker_tool_server
- src/skills.rs: replace render_worker_prompt with render_worker_skills,
  takes suggested names and builds listing with suggested flag
- src/prompts/engine.rs: render_skills_worker now takes Vec<SkillInfo>
  with suggested field; SkillInfo gains suggested: bool
- src/agent/channel.rs: spawn_worker_from_state takes suggested_skills
  &[&str] instead of skill_name Option<&str>
- src/tools/spawn_worker.rs: skill: Option<String> ->
  suggested_skills: Vec<String>
- prompts/en/fragments/skills_worker.md.j2: rewritten — listing with
  suggestions flagged, instruction to call read_skill before starting
- prompts/en/fragments/skills_channel.md.j2: updated example to use
  suggested_skills=[...]

Author: Marenz

prompts/en/fragments/skills_channel.md.j2

@@ -1,15 +1,16 @@
 ## Available Skills
 
-You have access to the following skills. Skills contain specialized instructions for specific tasks. When a user's request matches a skill, spawn a worker to handle it and include the skill name in the task description so the worker knows which skill to follow.
+You have access to the following skills. When a user's request matches one or more skills, spawn a worker and pass the relevant skill names as `suggested_skills`. The worker will read the skills it needs automatically.
 
-To use a skill, spawn a worker with a task like: "Use the [skill-name] skill to [task]. Read the skill instructions at [path] first."
+Example: `spawn_worker(task="Generate a 30-second downtempo track.", suggested_skills=["generate_music"])`
+
+You may suggest multiple skills if the task spans more than one: `suggested_skills=["github", "coding-agent"]`
 
 <available_skills>
 {%- for skill in skills %}
   <skill>
     <name>{{ skill.name }}</name>
     <description>{{ skill.description }}</description>
-    <location>{{ skill.location }}</location>
   </skill>
 {%- endfor %}
 </available_skills>

prompts/en/fragments/skills_worker.md.j2

@@ -1,5 +1,14 @@
-## Skill Instructions
+## Available Skills
 
-You are executing the **{{ skill_name }}** skill. Follow these instructions:
+You have access to the following skills. Before starting your task, scan the list and call `read_skill` for any skill that is relevant — you may read more than one.
 
-{{ skill_content }}
+Skills marked as **suggested** were recommended by the channel for this specific task. Read those first, then decide if any others apply.
+
+<available_skills>
+{%- for skill in skills %}
+  <skill{% if skill.suggested %} suggested="true"{% endif %}>
+    <name>{{ skill.name }}</name>
+    <description>{{ skill.description }}</description>
+  </skill>
+{%- endfor %}
+</available_skills>

src/agent/channel.rs

@@ -282,10 +282,10 @@ impl Channel {
                 _ = tokio::time::sleep(sleep_duration), if next_deadline.is_some() => {
                     let now = tokio::time::Instant::now();
                     // Check coalesce deadline
-                    if self.coalesce_deadline.is_some_and(|d| d <= now) {
-                        if let Err(error) = self.flush_coalesce_buffer().await {
-                            tracing::error!(%error, channel_id = %self.id, "error flushing coalesce buffer on deadline");
-                        }
+                    if self.coalesce_deadline.is_some_and(|d| d <= now)
+                        && let Err(error) = self.flush_coalesce_buffer().await
+                    {
+                        tracing::error!(%error, channel_id = %self.id, "error flushing coalesce buffer on deadline");
                     }
                     // Check retrigger deadline
                     if self.retrigger_deadline.is_some_and(|d| d <= now) {
@@ -391,7 +391,10 @@ impl Channel {
 
         if messages.len() == 1 {
             // Single message - process normally
-            let message = messages.into_iter().next().ok_or_else(|| anyhow::anyhow!("empty iterator after length check"))?;
+            let message = messages
+                .into_iter()
+                .next()
+                .ok_or_else(|| anyhow::anyhow!("empty iterator after length check"))?;
             self.handle_message(message).await
         } else {
             // Multiple messages - batch them
@@ -462,10 +465,11 @@ impl Channel {
                         .get("telegram_chat_type")
                         .and_then(|v| v.as_str())
                 });
-            self.conversation_context = Some(
-                prompt_engine
-                    .render_conversation_context(&first.source, server_name, channel_name)?,
-            );
+            self.conversation_context = Some(prompt_engine.render_conversation_context(
+                &first.source,
+                server_name,
+                channel_name,
+            )?);
         }
 
         // Persist each message to conversation log (individual audit trail)
@@ -605,8 +609,11 @@ impl Channel {
         let browser_enabled = rc.browser_config.load().enabled;
         let web_search_enabled = rc.brave_search_key.load().is_some();
         let opencode_enabled = rc.opencode.load().enabled;
-        let worker_capabilities =
-            prompt_engine.render_worker_capabilities(browser_enabled, web_search_enabled, opencode_enabled)?;
+        let worker_capabilities = prompt_engine.render_worker_capabilities(
+            browser_enabled,
+            web_search_enabled,
+            opencode_enabled,
+        )?;
 
         let status_text = {
             let status = self.state.status_block.read().await;
@@ -712,10 +719,11 @@ impl Channel {
                         .get("telegram_chat_type")
                         .and_then(|v| v.as_str())
                 });
-            self.conversation_context = Some(
-                prompt_engine
-                    .render_conversation_context(&message.source, server_name, channel_name)?,
-            );
+            self.conversation_context = Some(prompt_engine.render_conversation_context(
+                &message.source,
+                server_name,
+                channel_name,
+            )?);
         }
 
         let system_prompt = self.build_system_prompt().await?;
@@ -802,8 +810,11 @@ impl Channel {
         let browser_enabled = rc.browser_config.load().enabled;
         let web_search_enabled = rc.brave_search_key.load().is_some();
         let opencode_enabled = rc.opencode.load().enabled;
-        let worker_capabilities = prompt_engine
-            .render_worker_capabilities(browser_enabled, web_search_enabled, opencode_enabled)?;
+        let worker_capabilities = prompt_engine.render_worker_capabilities(
+            browser_enabled,
+            web_search_enabled,
+            opencode_enabled,
+        )?;
 
         let status_text = {
             let status = self.state.status_block.read().await;
@@ -814,17 +825,16 @@ impl Channel {
 
         let empty_to_none = |s: String| if s.is_empty() { None } else { Some(s) };
 
-        prompt_engine
-            .render_channel_prompt(
-                empty_to_none(identity_context),
-                empty_to_none(memory_bulletin.to_string()),
-                empty_to_none(skills_prompt),
-                worker_capabilities,
-                self.conversation_context.clone(),
-                empty_to_none(status_text),
-                None, // coalesce_hint - only set for batched messages
-                available_channels,
-            )
+        prompt_engine.render_channel_prompt(
+            empty_to_none(identity_context),
+            empty_to_none(memory_bulletin.to_string()),
+            empty_to_none(skills_prompt),
+            worker_capabilities,
+            self.conversation_context.clone(),
+            empty_to_none(status_text),
+            None, // coalesce_hint - only set for batched messages
+            available_channels,
+        )
     }
 
     /// Register per-turn tools, run the LLM agentic loop, and clean up.
@@ -1147,8 +1157,10 @@ impl Channel {
                 for (key, value) in retrigger_metadata {
                     self.pending_retrigger_metadata.insert(key, value);
                 }
-                self.retrigger_deadline =
-                    Some(tokio::time::Instant::now() + std::time::Duration::from_millis(RETRIGGER_DEBOUNCE_MS));
+                self.retrigger_deadline = Some(
+                    tokio::time::Instant::now()
+                        + std::time::Duration::from_millis(RETRIGGER_DEBOUNCE_MS),
+                );
             }
         }
 
@@ -1413,7 +1425,7 @@ pub async fn spawn_worker_from_state(
     state: &ChannelState,
     task: impl Into<String>,
     interactive: bool,
-    skill_name: Option<&str>,
+    suggested_skills: &[&str],
 ) -> std::result::Result<WorkerId, AgentError> {
     check_worker_limit(state).await?;
     let task = task.into();
@@ -1430,16 +1442,18 @@ pub async fn spawn_worker_from_state(
     let browser_config = (**rc.browser_config.load()).clone();
     let brave_search_key = (**rc.brave_search_key.load()).clone();
 
-    // Build the worker system prompt, optionally prepending skill instructions
-    let system_prompt = if let Some(name) = skill_name {
-        if let Some(skill_prompt) = skills.render_worker_prompt(name, &prompt_engine) {
-            format!("{}\n\n{}", worker_system_prompt, skill_prompt)
-        } else {
-            tracing::warn!(skill = %name, "skill not found, spawning worker without skill context");
+    // Append skills listing to worker system prompt. Suggested skills are
+    // flagged so the worker knows the channel's intent, but it can read any
+    // skill it decides is relevant via the read_skill tool.
+    let system_prompt = match skills.render_worker_skills(suggested_skills, &prompt_engine) {
+        Ok(skills_prompt) if !skills_prompt.is_empty() => {
+            format!("{worker_system_prompt}\n\n{skills_prompt}")
+        }
+        Ok(_) => worker_system_prompt,
+        Err(error) => {
+            tracing::warn!(%error, "failed to render worker skills listing, spawning without skills context");
             worker_system_prompt
         }
-    } else {
-        worker_system_prompt
     };
 
     let worker = if interactive {

src/agent/cortex_chat.rs

@@ -75,7 +75,8 @@ impl<M: CompletionModel> PromptHook<M> for CortexChatHook {
     ) -> ToolCallHookAction {
         self.send(CortexChatEvent::ToolStarted {
             tool: tool_name.to_string(),
-        }).await;
+        })
+        .await;
         ToolCallHookAction::Continue
     }
 
@@ -95,7 +96,8 @@ impl<M: CompletionModel> PromptHook<M> for CortexChatHook {
         self.send(CortexChatEvent::ToolCompleted {
             tool: tool_name.to_string(),
             result_preview: preview,
-        }).await;
+        })
+        .await;
         HookAction::Continue
     }
 
@@ -295,26 +297,33 @@ impl CortexChatSession {
                     let _ = store
                         .save_message(&thread_id, "assistant", &response, channel_ref)
                         .await;
-                    let _ = event_tx.send(CortexChatEvent::Done {
-                        full_text: response,
-                    }).await;
+                    let _ = event_tx
+                        .send(CortexChatEvent::Done {
+                            full_text: response,
+                        })
+                        .await;
                 }
                 Err(error) => {
                     let error_text = format!("Cortex chat error: {error}");
                     let _ = store
                         .save_message(&thread_id, "assistant", &error_text, channel_ref)
                         .await;
-                    let _ = event_tx.send(CortexChatEvent::Error {
-                        message: error_text,
-                    }).await;
+                    let _ = event_tx
+                        .send(CortexChatEvent::Error {
+                            message: error_text,
+                        })
+                        .await;
                 }
             }
         });
 
         Ok(event_rx)
     }
 
-    async fn build_system_prompt(&self, channel_context_id: Option<&str>) -> crate::error::Result<String> {
+    async fn build_system_prompt(
+        &self,
+        channel_context_id: Option<&str>,
+    ) -> crate::error::Result<String> {
         let runtime_config = &self.deps.runtime_config;
         let prompt_engine = runtime_config.prompts.load();
 
@@ -324,8 +333,11 @@ impl CortexChatSession {
         let browser_enabled = runtime_config.browser_config.load().enabled;
         let web_search_enabled = runtime_config.brave_search_key.load().is_some();
         let opencode_enabled = runtime_config.opencode.load().enabled;
-        let worker_capabilities =
-            prompt_engine.render_worker_capabilities(browser_enabled, web_search_enabled, opencode_enabled)?;
+        let worker_capabilities = prompt_engine.render_worker_capabilities(
+            browser_enabled,
+            web_search_enabled,
+            opencode_enabled,
+        )?;
 
         // Load channel transcript if a channel context is active
         let channel_transcript = if let Some(channel_id) = channel_context_id {

src/agent/worker.rs

@@ -204,6 +204,7 @@ impl Worker {
             self.deps.runtime_config.workspace_dir.clone(),
             self.deps.runtime_config.instance_dir.clone(),
             mcp_tools,
+            self.deps.runtime_config.clone(),
         );
 
         let routing = self.deps.runtime_config.routing.load();
@@ -264,7 +265,10 @@ impl Worker {
                                     None
                                 }
                             })
-                            .unwrap_or_else(|| "Worker reached maximum segments without a final response.".to_string());
+                            .unwrap_or_else(|| {
+                                "Worker reached maximum segments without a final response."
+                                    .to_string()
+                            });
                     }
 
                     self.maybe_compact_history(&mut history).await;
@@ -358,8 +362,7 @@ impl Worker {
                             self.hook.send_status("compacting (overflow recovery)");
                             self.force_compact_history(&mut history).await;
                             let prompt_engine = self.deps.runtime_config.prompts.load();
-                            let overflow_msg =
-                                prompt_engine.render_system_worker_overflow()?;
+                            let overflow_msg = prompt_engine.render_system_worker_overflow()?;
                             follow_up_prompt = format!("{follow_up}\n\n{overflow_msg}");
                         }
                         Err(error) => {

src/api/bindings.rs

@@ -377,12 +377,10 @@ pub(super) async fn create_binding(
                         Some(existing) => existing.clone(),
                         None => {
                             drop(perms_guard);
-                            let Some(discord_config) = new_config
-                                .messaging
-                                .discord
-                                .as_ref()
-                            else {
-                                tracing::error!("discord config missing despite token being provided");
+                            let Some(discord_config) = new_config.messaging.discord.as_ref() else {
+                                tracing::error!(
+                                    "discord config missing despite token being provided"
+                                );
                                 return Err(StatusCode::INTERNAL_SERVER_ERROR);
                             };
                             let perms = crate::config::DiscordPermissions::from_config(
@@ -409,12 +407,10 @@ pub(super) async fn create_binding(
                         Some(existing) => existing.clone(),
                         None => {
                             drop(perms_guard);
-                            let Some(slack_config) = new_config
-                                .messaging
-                                .slack
-                                .as_ref()
-                            else {
-                                tracing::error!("slack config missing despite tokens being provided");
+                            let Some(slack_config) = new_config.messaging.slack.as_ref() else {
+                                tracing::error!(
+                                    "slack config missing despite tokens being provided"
+                                );
                                 return Err(StatusCode::INTERNAL_SERVER_ERROR);
                             };
                             let perms = crate::config::SlackPermissions::from_config(
@@ -453,11 +449,7 @@ pub(super) async fn create_binding(
 
             if let Some(token) = new_telegram_token {
                 let telegram_perms = {
-                    let Some(telegram_config) = new_config
-                        .messaging
-                        .telegram
-                        .as_ref()
-                    else {
+                    let Some(telegram_config) = new_config.messaging.telegram.as_ref() else {
                         tracing::error!("telegram config missing despite token being provided");
                         return Err(StatusCode::INTERNAL_SERVER_ERROR);
                     };
@@ -475,11 +467,7 @@ pub(super) async fn create_binding(
             }
 
             if let Some((username, oauth_token)) = new_twitch_creds {
-                let Some(twitch_config) = new_config
-                    .messaging
-                    .twitch
-                    .as_ref()
-                else {
+                let Some(twitch_config) = new_config.messaging.twitch.as_ref() else {
                     tracing::error!("twitch config missing despite credentials being provided");
                     return Err(StatusCode::INTERNAL_SERVER_ERROR);
                 };

src/api/server.rs

@@ -15,8 +15,8 @@ use axum::middleware::{self, Next};
 use axum::response::{Html, IntoResponse, Response};
 use axum::routing::{delete, get, post, put};
 use rust_embed::Embed;
-use tower_http::cors::CorsLayer;
 use serde_json::json;
+use tower_http::cors::CorsLayer;
 
 use std::net::SocketAddr;
 use std::sync::Arc;
@@ -45,11 +45,7 @@ pub async fn start_http_server(
             axum::http::Method::DELETE,
             axum::http::Method::OPTIONS,
         ])
-        .allow_headers([
-            header::CONTENT_TYPE,
-            header::AUTHORIZATION,
-            header::ACCEPT,
-        ]);
+        .allow_headers([header::CONTENT_TYPE, header::AUTHORIZATION, header::ACCEPT]);
 
     let api_routes = Router::new()
         .route("/health", get(system::health))