u-foo 2.3.19 → 2.3.20

package/README.md

@@ -143,7 +143,9 @@ ufoo resume <ucode|uclaude|ucodex|nickname>
 ufoo recover list
 ```
 
-Common chat commands include `/status`, `/bus list`, `/bus status`, `/settings`, `/project list`, `/project switch <index|path>`, `/open <path>`, `/resume list`, `/group status`, and `@nickname <message>`.
+Common chat commands include `/status`, `/bus list`, `/bus status`, `/settings`, `/project list`, `/project switch <index|path>`, `/open <path>`, `/resume list`, `/group status`, `/skills`, and `@nickname <message>`.
+
+In `ufoo chat`, `/skills` lists ufoo's built-in available skills and preset workflow capabilities so users can discover and choose them. It does not execute a task by itself, and it is not a private capability list for any one agent.
 
 ### Event Bus
 
@@ -197,7 +199,7 @@ Use decisions sparingly for plan-level constraints. Durable project facts belong
 | Online | `ufoo online server|token|room|channel|connect|send|inbox` |
 | History | `ufoo history build|show|prompt` |
 | Skills | `ufoo skills list|install` |
-| Chat settings | `/settings`, `/settings agent`, `/settings router`, `/settings ucode` |
+| Chat commands | `/skills`, `/settings`, `/settings agent`, `/settings router`, `/settings ucode` |
 
 ### Groups
 
@@ -246,8 +248,12 @@ Use the low-level queue runtime:
 ucode-core submit --tool read --args-json '{"path":"README.md"}' --json
 ucode-core run-once --json
 ucode-core list --json
+ucode-core skills list --json
+ucode-core skills show <name>
 ```
 
+`ucode-core skills list` discovers ufoo/ucode built-in and local `SKILL.md` preset workflow capabilities for selection. It lists metadata only; full skill bodies are loaded by ucode only when the user explicitly references a skill such as `$demo` or a direct `SKILL.md` link.
+
 ## Configuration
 
 Project configuration is stored in `.ufoo/config.json`. `ucode` provider credentials are stored globally in `~/.ufoo/config.json` and merged into project config at load time.

package/README.zh-CN.md

@@ -133,7 +133,9 @@ ufoo resume <ucode|uclaude|ucodex|nickname>
 ufoo recover list
 ```
 
-常见 chat 命令包括 `/status`、`/bus list`、`/bus status`、`/settings`、`/project list`、`/project switch <index|path>`、`/open <path>`、`/resume list`、`/group status` 和 `@nickname <message>`。
+常见 chat 命令包括 `/status`、`/bus list`、`/bus status`、`/settings`、`/project list`、`/project switch <index|path>`、`/open <path>`、`/resume list`、`/group status`、`/skills` 和 `@nickname <message>`。
+
+在 `ufoo chat` 中，`/skills` 用于列出 ufoo 内置的可用 skills 和预设工作流能力，方便用户发现和选择。它本身不等于执行任务，也不表示某个 agent 的私有能力列表。
 
 ### 事件总线
 
@@ -211,8 +213,12 @@ ufoo ucode build
 ucode-core submit --tool read --args-json '{"path":"README.md"}' --json
 ucode-core run-once --json
 ucode-core list --json
+ucode-core skills list --json
+ucode-core skills show <name>
 ```
 
+`ucode-core skills list` 用于发现 ufoo/ucode 内置和本地 `SKILL.md` 预设工作流能力，输出的是供选择的元数据；完整 skill 内容只会在用户显式引用 `$demo` 或直接链接某个 `SKILL.md` 时由 ucode 加载。
+
 ## 命令参考
 
 | 范围 | 命令 |
@@ -228,7 +234,7 @@ ucode-core list --json
 | Online | `ufoo online server|token|room|channel|connect|send|inbox` |
 | History | `ufoo history build|show|prompt` |
 | Skills | `ufoo skills list|install` |
-| Chat 设置 | `/settings`, `/settings agent`, `/settings router`, `/settings ucode` |
+| Chat 命令 | `/skills`, `/settings`, `/settings agent`, `/settings router`, `/settings ucode` |
 
 ## 配置
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-foo",
-  "version": "2.3.19",
+  "version": "2.3.20",
   "description": "Multi-Agent Workspace Protocol. Just add u. claude → uclaude, codex → ucodex.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://ufoo.dev",

package/src/chat/agentViewController.js

@@ -42,6 +42,7 @@ function createAgentViewController(options = {}) {
     sendBusMessage = () => {},
     sendResize = () => {},
     requestScreenSnapshot = () => {},
+    sendBusWatch = () => {},
   } = options;
 
   if (!screen || typeof screen.render !== "function") {
@@ -69,10 +70,14 @@ function createAgentViewController(options = {}) {
   };
 
   function getRows() {
+    if (Number.isFinite(screen.height) && screen.height > 0) return screen.height;
+    if (Number.isFinite(screen.rows) && screen.rows > 0) return screen.rows;
     return processStdout.rows || 24;
   }
 
   function getCols() {
+    if (Number.isFinite(screen.width) && screen.width > 0) return screen.width;
+    if (Number.isFinite(screen.cols) && screen.cols > 0) return screen.cols;
     return processStdout.columns || 80;
   }
 
@@ -257,11 +262,14 @@ function createAgentViewController(options = {}) {
   function forceScreenRepaint() {
     if (typeof screen.realloc === "function") {
       screen.realloc();
-      return;
-    }
-    if (typeof screen.alloc === "function") {
+    } else if (typeof screen.alloc === "function") {
       screen.alloc(true);
     }
+    try {
+      originalRender();
+    } catch {
+      // Ignore repaint failures while restoring from raw agent view.
+    }
   }
 
   function compactProjectPath(projectRoot = "") {
@@ -297,13 +305,15 @@ function createAgentViewController(options = {}) {
     const projectPath = compactProjectPath(getProjectRoot());
     const product = "ClaudeCode";
     const detail = label ? `${label} · managed headless` : "managed headless";
-    const iconTop = `${CLAUDE_ORANGE}▐▛███▜▌${ANSI_RESET}`;
-    const iconMiddle = `${CLAUDE_ORANGE}▝▜█████▛▘${ANSI_RESET}`;
-    const iconBottom = `${CLAUDE_ORANGE}▘▘▝▝${ANSI_RESET}`;
+    const iconWidth = 9;
+    const iconLine = (icon = "", text = "") => {
+      const pad = " ".repeat(Math.max(0, iconWidth - displayWidth(icon)));
+      return `${CLAUDE_ORANGE}${icon}${ANSI_RESET}${pad}${text}`;
+    };
     const lines = [
-      ` ${iconTop} ${product}v${packageVersion}`,
-      `${iconMiddle}${detail}`,
-      ` ${iconBottom}    ${projectPath}`,
+      iconLine("▐▛███▜▌", `${product}v${packageVersion}`),
+      iconLine("▝▜█████▛▘", detail),
+      iconLine(" ▘▘▝▝", projectPath),
       "",
     ];
     if (width < 44) return lines;
@@ -464,6 +474,7 @@ function createAgentViewController(options = {}) {
   function enterAgentView(agentId, options = {}) {
     if (currentView === "agent" && viewingAgent === agentId) return;
     if (currentView === "agent") {
+      if (agentViewUsesBus && viewingAgent) sendBusWatch(viewingAgent, false);
       disconnectAgentOutput();
       disconnectAgentInput();
     }
@@ -488,6 +499,7 @@ function createAgentViewController(options = {}) {
     agentInputSuppressUntil = now() + 300;
     agentViewUsesBus = Boolean(options.useBus);
     if (agentViewUsesBus) {
+      sendBusWatch(agentId, true);
       resetBusView(agentId);
       renderBusView();
     } else {
@@ -511,6 +523,7 @@ function createAgentViewController(options = {}) {
 
     disconnectAgentOutput();
     disconnectAgentInput();
+    if (agentViewUsesBus && viewingAgent) sendBusWatch(viewingAgent, false);
     agentViewUsesBus = false;
     agentOutputSuppressed = false;
     agentBarVisible = false;
@@ -536,11 +549,11 @@ function createAgentViewController(options = {}) {
     setDashboardView("agents");
     setSelectedAgentIndex(-1);
     setScreenGrabKeys(false);
-    forceScreenRepaint();
     clearTargetAgent();
     renderDashboard();
     focusInput();
     resizeInput();
+    forceScreenRepaint();
     try {
       if (screen.program && typeof screen.program.showCursor === "function") {
         screen.program.showCursor();

package/src/chat/commandExecutor.js

@@ -448,12 +448,12 @@ function createCommandExecutor(options = {}) {
         try {
           const skills = createSkills(projectRoot);
 
-          if (subcommand === "list") {
+          if (!subcommand || subcommand === "list") {
             const skillList = skills.list();
             if (skillList.length === 0) {
-              logMessage("system", "{white-fg}No skills found{/white-fg}");
+              logMessage("system", "{white-fg}No built-in ufoo skills found{/white-fg}");
             } else {
-              logMessage("system", `{cyan-fg}Available skills:{/cyan-fg} ${skillList.length}`);
+              logMessage("system", `{cyan-fg}Available built-in ufoo skills:{/cyan-fg} ${skillList.length}`);
               for (const skill of skillList) {
                 logMessage("system", `  • ${skill}`);
               }

package/src/chat/commands.js

@@ -129,10 +129,10 @@ const COMMAND_TREE = {
     },
   },
   "/skills": {
-    desc: "Skills management",
+    desc: "List ufoo built-in skills and preset workflows",
     children: {
-      install: { desc: "Install skills (use: all or name)" },
-      list: { desc: "List available skills" },
+      install: { desc: "Install built-in skills (use: all or name)" },
+      list: { desc: "List built-in skills for discovery" },
     },
   },
   "/status": { desc: "Status display" },

package/src/chat/daemonMessageRouter.js

@@ -19,6 +19,8 @@ function createDaemonMessageRouter(options = {}) {
     getCurrentView = () => "main",
     isAgentViewUsesBus = () => false,
     getViewingAgent = () => "",
+    isAgentEventForViewingAgent = (data, viewingAgent, publisher) =>
+      Boolean(viewingAgent && (publisher === viewingAgent || data?.target === viewingAgent)),
     writeToAgentTerm = () => {},
     consumePendingDelivery = () => false,
     getPendingState = () => null,
@@ -352,6 +354,19 @@ function createDaemonMessageRouter(options = {}) {
   function handleBusMessage(msg) {
     const data = msg.data || {};
     if (data.event === "activity_state_changed") {
+      const publisher = data.publisher && data.publisher !== "unknown"
+        ? data.publisher
+        : (data.subscriber || "bus");
+      const viewingAgent = getViewingAgent();
+      if (
+        getCurrentView() === "agent" &&
+        isAgentViewUsesBus() &&
+        viewingAgent &&
+        isAgentEventForViewingAgent(data, viewingAgent, publisher)
+      ) {
+        const state = data.state || (data.data && data.data.state) || "";
+        if (state) writeToAgentTerm(`[state] ${state}\r\n`);
+      }
       requestStatus();
       return true;
     }
@@ -375,11 +390,12 @@ function createDaemonMessageRouter(options = {}) {
     if (data.silent && !streamPayload) return true;
     if (!displayMessage && !streamPayload) return true;
 
+    const viewingAgent = getViewingAgent();
     const isAgentViewTarget =
       getCurrentView() === "agent" &&
       isAgentViewUsesBus() &&
-      getViewingAgent() &&
-      publisher === getViewingAgent();
+      viewingAgent &&
+      isAgentEventForViewingAgent(data, viewingAgent, publisher);
 
     const displayName = resolveAgentDisplayName(publisher);
 

package/src/chat/index.js

@@ -1581,6 +1581,14 @@ async function runChat(projectRoot, options = {}) {
         source: "chat-internal-agent-view",
       });
     },
+    sendBusWatch: (agentId, enabled) => {
+      if (!agentId) return;
+      send({
+        type: IPC_REQUEST_TYPES.BUS_WATCH,
+        agent_id: agentId,
+        enabled: enabled !== false,
+      });
+    },
     sendResize: (cols, rows) => {
       sendResizeWithCapabilities(cols, rows);
     },
@@ -1612,6 +1620,21 @@ async function runChat(projectRoot, options = {}) {
     getCurrentView: () => getCurrentView(),
     isAgentViewUsesBus: () => isAgentViewUsesBus(),
     getViewingAgent: () => getViewingAgent(),
+    isAgentEventForViewingAgent: (data, viewingAgent, publisher) => {
+      if (!viewingAgent) return false;
+      const label = getAgentLabel(viewingAgent);
+      const candidates = [
+        publisher,
+        data && data.publisher,
+        data && data.target,
+        data && data.subscriber,
+      ].filter(Boolean);
+      return candidates.some((value) => (
+        value === viewingAgent ||
+        value === label ||
+        resolveAgentId(value) === viewingAgent
+      ));
+    },
     writeToAgentTerm,
     consumePendingDelivery,
     getPendingState,

package/src/code/agent.js

@@ -25,6 +25,12 @@ const {
   loadSessionSnapshot,
 } = require("./sessionStore");
 const { buildPromptContext } = require("./prompts");
+const {
+  buildSkillInjections,
+  formatSkillsList,
+  listUcodeSkills,
+  showSkill,
+} = require("./skills");
 
 function printPrompt() {
   process.stdout.write("> ");
@@ -243,6 +249,61 @@ function createToolLogCollector(logs = [], onToolLog = null) {
   };
 }
 
+function pushSkillWarning(logs = [], onToolLog = null, warning = "") {
+  const text = String(warning || "").trim();
+  if (!text) return null;
+  const entry = {
+    type: "skills",
+    phase: "warning",
+    message: text,
+    error: text,
+  };
+  if (Array.isArray(logs)) logs.push(entry);
+  if (typeof onToolLog === "function") {
+    try {
+      onToolLog(entry);
+    } catch {
+      // ignore callback failures
+    }
+  }
+  return entry;
+}
+
+function stripSkillBlocksFromText(value = "") {
+  return String(value || "")
+    .replace(/<skill>\s*[\s\S]*?<\/skill>\s*/g, "")
+    .trim();
+}
+
+function stripSkillBlocksFromMessages(messages = []) {
+  if (!Array.isArray(messages)) return [];
+  return messages.map((message) => {
+    if (!message || typeof message !== "object" || Array.isArray(message)) return message;
+    if (typeof message.content === "string") {
+      return {
+        ...message,
+        content: stripSkillBlocksFromText(message.content),
+      };
+    }
+    if (Array.isArray(message.content)) {
+      return {
+        ...message,
+        content: message.content.map((item) => {
+          if (!item || typeof item !== "object" || Array.isArray(item)) return item;
+          if (typeof item.text === "string") {
+            return {
+              ...item,
+              text: stripSkillBlocksFromText(item.text),
+            };
+          }
+          return item;
+        }),
+      };
+    }
+    return message;
+  });
+}
+
 function isProjectAnalysisTask(task = "") {
   const text = String(task || "").trim().toLowerCase();
   if (!text) return false;
@@ -398,6 +459,16 @@ async function runNaturalLanguageTask(task = "", state = {}, options = {}) {
   const taskPrompt = analysisTask
     ? `${taskText}\n\nAnalysis requirements:\n- Inspect repository evidence before concluding.\n- Cite concrete file observations.\n- Keep findings concise and actionable.`
     : taskText;
+  const skillInjections = buildSkillInjections({
+    prompt: taskPrompt,
+    workspaceRoot,
+  });
+  for (const warning of skillInjections.warnings || []) {
+    pushSkillWarning(logs, onToolLog, warning);
+  }
+  const effectiveTaskPrompt = Array.isArray(skillInjections.blocks) && skillInjections.blocks.length > 0
+    ? `${skillInjections.blocks.join("\n\n")}\n\n${taskPrompt}`
+    : taskPrompt;
   const systemContext = [String(state.context || "").trim(), preflightContext]
     .filter(Boolean)
     .join("\n\n");
@@ -422,7 +493,7 @@ async function runNaturalLanguageTask(task = "", state = {}, options = {}) {
     workspaceRoot,
     provider,
     model,
-    prompt: taskPrompt,
+    prompt: effectiveTaskPrompt,
     systemPrompt: systemContext,
     messages: Array.isArray(state.nlMessages) ? state.nlMessages : [],
     sessionId: String(sessionIdValue || ""),
@@ -440,7 +511,7 @@ async function runNaturalLanguageTask(task = "", state = {}, options = {}) {
     // Use decomposed runner for bug fix tasks
     if (useDecomposition) {
       const decomposedResult = await runDecomposedTask({
-        task: taskText,
+        task: effectiveTaskPrompt,
         state,
         onProgress: options.onProgress,
         onToolEvent: pushToolLog,
@@ -497,7 +568,7 @@ async function runNaturalLanguageTask(task = "", state = {}, options = {}) {
       state.sessionId = cliRes.sessionId.trim();
     }
     if (cliRes && Array.isArray(cliRes.messages)) {
-      state.nlMessages = cliRes.messages;
+      state.nlMessages = stripSkillBlocksFromMessages(cliRes.messages);
     }
     const normalized = String(cliRes.output || "").trim();
     const summary = extractJsonSummary(normalized);
@@ -1235,6 +1306,8 @@ function runSingleCommand(line = "", workspaceRoot = process.cwd()) {
         "  help",
         "  exit|quit",
         "  ubus|/ubus",
+        "  skills [list]",
+        "  skills show <name>",
         "  bg|/bg <task>",
         "  resume <session-id>",
         "  tool <read|write|edit|bash> <args-json>",
@@ -1254,6 +1327,45 @@ function runSingleCommand(line = "", workspaceRoot = process.cwd()) {
       kind: "ubus",
     };
   }
+  const skillsMatch = text.match(/^(?:\/skills|skills)(?:\s+(.*))?$/i);
+  if (skillsMatch) {
+    const args = String(skillsMatch[1] || "").trim().split(/\s+/).filter(Boolean);
+    const action = String(args[0] || "list").toLowerCase();
+    if (action === "list" || action === "ls") {
+      const outcome = listUcodeSkills({ workspaceRoot });
+      return {
+        kind: "skills",
+        output: formatSkillsList(outcome),
+        skills: outcome.skills,
+        errors: outcome.errors,
+      };
+    }
+    if (action === "show") {
+      const name = String(args[1] || "").trim();
+      if (!name) {
+        return {
+          kind: "error",
+          output: "usage: skills show <name>",
+        };
+      }
+      const result = showSkill({ name, workspaceRoot });
+      if (!result.ok) {
+        return {
+          kind: "error",
+          output: result.error,
+        };
+      }
+      return {
+        kind: "skills",
+        output: result.output,
+        skill: result.skill,
+      };
+    }
+    return {
+      kind: "error",
+      output: "usage: skills [list] | skills show <name>",
+    };
+  }
   if (text === "bg" || text === "/bg") {
     return {
       kind: "error",
@@ -1498,7 +1610,7 @@ async function runUcodeCoreAgent({
       if (result.kind === "probe") {
         return;
       }
-      if (result.kind === "help" || result.kind === "tool" || result.kind === "error") {
+      if (result.kind === "help" || result.kind === "tool" || result.kind === "skills" || result.kind === "error") {
         stdout.write(`${result.output}\n`);
       }
       if (result.kind === "ubus") {
@@ -1701,6 +1813,8 @@ module.exports = {
   normalizeToolLogEvent,
   isProjectAnalysisTask,
   buildNlFallbackSummary,
+  buildNlContext,
+  stripSkillBlocksFromMessages,
   resolvePlannerProvider,
   extractJsonSummary,
   enrichNativeError,

package/src/code/cli.js

@@ -4,6 +4,11 @@ const {
   listResults,
 } = require("./runtime");
 const { runUcodeCoreAgent } = require("./agent");
+const {
+  formatSkillsList,
+  listUcodeSkills,
+  showSkill,
+} = require("./skills");
 
 function parseArgs(argv = []) {
   const args = Array.isArray(argv) ? argv.slice() : [];
@@ -16,11 +21,21 @@ function parseArgs(argv = []) {
     max: 1,
     num: 20,
     taskId: "",
+    skillsAction: "",
+    skillsName: "",
   };
 
   for (let i = 1; i < args.length; i += 1) {
     const item = String(args[i] || "").trim();
     if (!item) continue;
+    if (out.command === "skills" && !item.startsWith("-")) {
+      if (!out.skillsAction) {
+        out.skillsAction = item.toLowerCase();
+      } else if (!out.skillsName) {
+        out.skillsName = item;
+      }
+      continue;
+    }
     if (item === "--json") {
       out.json = true;
       continue;
@@ -69,6 +84,8 @@ function usage() {
     "  submit --tool <read|write|edit|bash> --args-json <json> [--workspace <path>] [--task-id <id>]",
     "  run-once [--max <n>] [--workspace <path>]",
     "  list [--num <n>]",
+    "  skills list [--workspace <path>]",
+    "  skills show <name> [--workspace <path>]",
     "",
     "Flags:",
     "  --json    Output JSON",
@@ -147,6 +164,36 @@ async function runUcodeCoreCli({
     return { exitCode: 0, output: `${lines.join("\n")}${lines.length ? "\n" : ""}` };
   }
 
+  if (cmd === "skills") {
+    const action = options.skillsAction || "list";
+    const workspaceRoot = options.workspace || projectRoot;
+    if (action === "list" || action === "ls") {
+      const outcome = listUcodeSkills({ workspaceRoot });
+      if (options.json) {
+        return { exitCode: 0, output: `${JSON.stringify({ ok: true, ...outcome })}\n` };
+      }
+      return { exitCode: 0, output: `${formatSkillsList(outcome)}\n` };
+    }
+    if (action === "show") {
+      if (!options.skillsName) {
+        return { exitCode: 1, output: "skills show requires <name>\n" };
+      }
+      const result = showSkill({
+        name: options.skillsName,
+        workspaceRoot,
+        asJson: options.json,
+      });
+      if (!result.ok) {
+        return { exitCode: 1, output: `${options.json ? JSON.stringify({ ok: false, error: result.error }) : result.error}\n` };
+      }
+      if (options.json) {
+        return { exitCode: 0, output: `${JSON.stringify(result)}\n` };
+      }
+      return { exitCode: 0, output: `${result.output}\n` };
+    }
+    return { exitCode: 1, output: "unknown skills command: use list or show\n" };
+  }
+
   return { exitCode: 1, output: `unknown command: ${cmd}\n` };
 }
 

package/src/code/prompts/index.js

@@ -8,8 +8,13 @@ const { getSafetySection } = require("./safety");
 const { getOutputEfficiencySection } = require("./efficiency");
 const { getUfooIntegrationSection } = require("./ufoo");
 const { getEnvironmentSection } = require("./environment");
+const {
+  listUcodeSkills,
+  renderSkillsSection,
+} = require("../skills");
 const {
   systemPromptSection,
+  uncachedSection,
   resolveSections,
   clearSectionCache,
 } = require("./sections");
@@ -68,6 +73,10 @@ function getSystemPrompt({
     systemPromptSection("environment", () =>
       getEnvironmentSection({ workspaceRoot, model, provider }),
     ),
+    uncachedSection("skills", () => {
+      const outcome = listUcodeSkills({ workspaceRoot: workspaceRoot || process.cwd() });
+      return renderSkillsSection(outcome.skills);
+    }),
   ];
   const dynamicSections = resolveSections(dynamicSectionDefs);
 

package/src/code/skills/index.js

@@ -0,0 +1,74 @@
+const {
+  listUcodeSkills,
+  findSkillsByName,
+} = require("./loader");
+const {
+  renderSkillsSection,
+  formatSkillsList,
+} = require("./render");
+const {
+  buildSkillInjections,
+} = require("./injection");
+
+function showSkill({ name = "", workspaceRoot = process.cwd(), asJson = false } = {}) {
+  const outcome = listUcodeSkills({ workspaceRoot });
+  const matches = findSkillsByName(outcome.skills, name);
+  if (matches.length === 0) {
+    return {
+      ok: false,
+      error: `skill not found: ${name}`,
+      outcome,
+    };
+  }
+  if (matches.length > 1) {
+    return {
+      ok: false,
+      error: `skill is ambiguous: ${name}`,
+      outcome,
+      matches,
+    };
+  }
+  const skill = matches[0];
+  let content = "";
+  try {
+    content = require("fs").readFileSync(skill.path, "utf8");
+  } catch (err) {
+    return {
+      ok: false,
+      error: err && err.message ? err.message : "failed to read skill",
+      outcome,
+      skill,
+    };
+  }
+  if (asJson) {
+    return {
+      ok: true,
+      skill,
+      content,
+      errors: outcome.errors,
+    };
+  }
+  return {
+    ok: true,
+    output: [
+      `# ${skill.name}`,
+      "",
+      `Description: ${skill.description}`,
+      `Path: ${skill.path}`,
+      "",
+      content.trim(),
+    ].join("\n"),
+    skill,
+    content,
+    errors: outcome.errors,
+  };
+}
+
+module.exports = {
+  listUcodeSkills,
+  findSkillsByName,
+  renderSkillsSection,
+  formatSkillsList,
+  buildSkillInjections,
+  showSkill,
+};

package/src/code/skills/injection.js

@@ -0,0 +1,120 @@
+const fs = require("fs");
+const path = require("path");
+const {
+  canonicalPath,
+  findSkillsByName,
+  listUcodeSkills,
+} = require("./loader");
+
+function markdownSkillLinks(prompt = "") {
+  const text = String(prompt || "");
+  const links = [];
+  const re = /\[([^\]]+)]\(([^)]+)\)/g;
+  let match;
+  while ((match = re.exec(text))) {
+    const label = String(match[1] || "").trim();
+    const target = String(match[2] || "").trim();
+    if (!target) continue;
+    if (target.startsWith("skill://") || /(?:^|[/\\])SKILL\.md(?:[#?].*)?$/i.test(target)) {
+      links.push({ label, target });
+    }
+  }
+  return links;
+}
+
+function mentionedSkillNames(prompt = "") {
+  const text = String(prompt || "");
+  const names = new Set();
+  const re = /(^|[^\w-])\$([A-Za-z0-9][A-Za-z0-9_-]{0,63})\b/g;
+  let match;
+  while ((match = re.exec(text))) {
+    names.add(String(match[2] || "").trim());
+  }
+  return Array.from(names).filter(Boolean);
+}
+
+function resolveSkillLinkTarget(target = "", workspaceRoot = process.cwd()) {
+  const raw = String(target || "").trim().replace(/[#?].*$/, "");
+  if (!raw) return "";
+  let value = raw;
+  if (value.startsWith("skill://")) {
+    value = value.slice("skill://".length);
+    try {
+      value = decodeURIComponent(value);
+    } catch {
+      // keep raw value
+    }
+  }
+  if (!value) return "";
+  if (path.isAbsolute(value)) return canonicalPath(value);
+  return canonicalPath(path.resolve(workspaceRoot || process.cwd(), value));
+}
+
+function findSkillByPath(skills = [], targetPath = "") {
+  const target = canonicalPath(targetPath);
+  return (Array.isArray(skills) ? skills : []).find((skill) => canonicalPath(skill.path) === target) || null;
+}
+
+function readSkillBlock(skill) {
+  const content = fs.readFileSync(skill.path, "utf8");
+  return `<skill>\n<name>${skill.name}</name>\n<path>${String(skill.path).replace(/\\/g, "/")}</path>\n${content}\n</skill>`;
+}
+
+function buildSkillInjections({
+  prompt = "",
+  workspaceRoot = process.cwd(),
+  skillsOutcome = null,
+  loadSkills = listUcodeSkills,
+} = {}) {
+  const outcome = skillsOutcome || loadSkills({ workspaceRoot });
+  const skills = Array.isArray(outcome.skills) ? outcome.skills : [];
+  const warnings = Array.isArray(outcome.errors)
+    ? outcome.errors.map((err) => `failed to load skill ${err.path}: ${err.message}`)
+    : [];
+  const selected = new Map();
+
+  for (const name of mentionedSkillNames(prompt)) {
+    const matches = findSkillsByName(skills, name);
+    if (matches.length === 1) {
+      selected.set(canonicalPath(matches[0].path), matches[0]);
+    } else if (matches.length > 1) {
+      warnings.push(`skill $${name} is ambiguous; link to a specific SKILL.md path`);
+    } else {
+      warnings.push(`skill $${name} was not found`);
+    }
+  }
+
+  for (const link of markdownSkillLinks(prompt)) {
+    const targetPath = resolveSkillLinkTarget(link.target, workspaceRoot);
+    const skill = findSkillByPath(skills, targetPath);
+    if (skill) {
+      selected.set(canonicalPath(skill.path), skill);
+    } else {
+      warnings.push(`skill link ${link.target} did not resolve to an enabled skill`);
+    }
+  }
+
+  const blocks = [];
+  for (const skill of selected.values()) {
+    try {
+      blocks.push(readSkillBlock(skill));
+    } catch (err) {
+      warnings.push(`failed to read skill ${skill.path}: ${err && err.message ? err.message : "read failed"}`);
+    }
+  }
+
+  return {
+    blocks,
+    warnings,
+    skills,
+    errors: Array.isArray(outcome.errors) ? outcome.errors : [],
+  };
+}
+
+module.exports = {
+  mentionedSkillNames,
+  markdownSkillLinks,
+  resolveSkillLinkTarget,
+  findSkillByPath,
+  buildSkillInjections,
+};

package/src/code/skills/loader.js

@@ -0,0 +1,218 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const matter = require("gray-matter");
+
+const SKILL_FILE = "SKILL.md";
+const DEFAULT_MAX_DEPTH = 6;
+
+function repoRootFromHere() {
+  return path.resolve(__dirname, "..", "..", "..");
+}
+
+function canonicalPath(filePath = "") {
+  const resolved = path.resolve(String(filePath || ""));
+  try {
+    return fs.realpathSync.native ? fs.realpathSync.native(resolved) : fs.realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+function isDirectory(filePath = "") {
+  try {
+    return fs.statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(filePath = "") {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function homeDir(env = process.env) {
+  return String((env && env.HOME) || os.homedir() || "").trim();
+}
+
+function defaultSkillRoots({
+  workspaceRoot = process.cwd(),
+  env = process.env,
+  repoRoot = repoRootFromHere(),
+} = {}) {
+  const workspace = path.resolve(String(workspaceRoot || process.cwd()));
+  const home = homeDir(env);
+  const codexHome = String((env && env.CODEX_HOME) || "").trim()
+    || (home ? path.join(home, ".codex") : "");
+  const roots = [
+    { path: path.join(workspace, ".agents", "skills"), scope: "repo", source: "workspace-agents" },
+    { path: path.join(workspace, ".codex", "skills"), scope: "repo", source: "workspace-codex" },
+  ];
+
+  if (home) {
+    roots.push({ path: path.join(home, ".agents", "skills"), scope: "user", source: "user-agents" });
+  }
+  if (codexHome) {
+    roots.push({ path: path.join(codexHome, "skills"), scope: "user", source: "user-codex" });
+    roots.push({ path: path.join(codexHome, "skills", ".system"), scope: "system", source: "codex-system" });
+  }
+
+  const root = path.resolve(String(repoRoot || repoRootFromHere()));
+  roots.push({ path: path.join(root, "SKILLS"), scope: "builtin", source: "ufoo" });
+  const modulesDir = path.join(root, "modules");
+  try {
+    for (const entry of fs.readdirSync(modulesDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+      roots.push({
+        path: path.join(modulesDir, entry.name, "SKILLS"),
+        scope: "builtin",
+        source: `ufoo-module:${entry.name}`,
+      });
+    }
+  } catch {
+    // Modules are optional in tests and local installs.
+  }
+
+  const seen = new Set();
+  return roots
+    .map((rootInfo) => ({ ...rootInfo, path: path.resolve(rootInfo.path) }))
+    .filter((rootInfo) => {
+      if (seen.has(rootInfo.path)) return false;
+      seen.add(rootInfo.path);
+      return true;
+    });
+}
+
+function parseSkillFile(filePath, rootInfo = {}) {
+  const skillPath = canonicalPath(filePath);
+  const dir = path.dirname(skillPath);
+  let parsed;
+  try {
+    parsed = matter(fs.readFileSync(skillPath, "utf8"));
+  } catch (err) {
+    throw new Error(err && err.message ? err.message : "failed to read skill");
+  }
+
+  const data = parsed && parsed.data && typeof parsed.data === "object" ? parsed.data : {};
+  const name = String(data.name || "").trim();
+  const description = String(data.description || "").trim();
+  if (!name) throw new Error("missing required frontmatter field: name");
+  if (!description) throw new Error("missing required frontmatter field: description");
+
+  const metadata = data.metadata && typeof data.metadata === "object" ? data.metadata : {};
+  const shortDescription = String(
+    metadata["short-description"]
+      || metadata.shortDescription
+      || data["short-description"]
+      || data.shortDescription
+      || ""
+  ).trim();
+
+  return {
+    name,
+    description,
+    shortDescription,
+    path: skillPath,
+    dir,
+    scope: rootInfo.scope || "repo",
+    source: rootInfo.source || "",
+    enabled: true,
+  };
+}
+
+function discoverSkillsUnderRoot(rootInfo = {}, options = {}) {
+  const root = path.resolve(String(rootInfo.path || ""));
+  const maxDepth = Number.isFinite(options.maxDepth) ? options.maxDepth : DEFAULT_MAX_DEPTH;
+  const skills = [];
+  const errors = [];
+  if (!root || !isDirectory(root)) return { skills, errors };
+
+  const walk = (dir, depth) => {
+    if (depth > maxDepth) return;
+    const skillFile = path.join(dir, SKILL_FILE);
+    if (isFile(skillFile)) {
+      try {
+        skills.push(parseSkillFile(skillFile, rootInfo));
+      } catch (err) {
+        errors.push({
+          path: canonicalPath(skillFile),
+          message: err && err.message ? err.message : "invalid skill",
+        });
+      }
+      return;
+    }
+
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (err) {
+      errors.push({
+        path: canonicalPath(dir),
+        message: err && err.message ? err.message : "failed to read directory",
+      });
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith(".")) continue;
+      walk(path.join(dir, entry.name), depth + 1);
+    }
+  };
+
+  walk(root, 0);
+  return { skills, errors };
+}
+
+function listUcodeSkills(options = {}) {
+  const roots = Array.isArray(options.roots)
+    ? options.roots
+    : defaultSkillRoots(options);
+  const seenPaths = new Set();
+  const skills = [];
+  const errors = [];
+
+  for (const rootInfo of roots) {
+    const discovered = discoverSkillsUnderRoot(rootInfo, options);
+    for (const err of discovered.errors) errors.push(err);
+    for (const skill of discovered.skills) {
+      const key = canonicalPath(skill.path);
+      if (seenPaths.has(key)) continue;
+      seenPaths.add(key);
+      skills.push(skill);
+    }
+  }
+
+  const scopeRank = { repo: 0, user: 1, builtin: 2, system: 3, admin: 4 };
+  skills.sort((a, b) => {
+    const rankA = scopeRank[a.scope] == null ? 9 : scopeRank[a.scope];
+    const rankB = scopeRank[b.scope] == null ? 9 : scopeRank[b.scope];
+    if (rankA !== rankB) return rankA - rankB;
+    if (a.name !== b.name) return a.name.localeCompare(b.name);
+    return a.path.localeCompare(b.path);
+  });
+
+  return { skills, errors };
+}
+
+function findSkillsByName(skills = [], name = "") {
+  const target = String(name || "").trim().toLowerCase();
+  if (!target) return [];
+  return (Array.isArray(skills) ? skills : [])
+    .filter((skill) => skill && skill.enabled !== false && String(skill.name || "").trim().toLowerCase() === target);
+}
+
+module.exports = {
+  SKILL_FILE,
+  DEFAULT_MAX_DEPTH,
+  canonicalPath,
+  defaultSkillRoots,
+  parseSkillFile,
+  discoverSkillsUnderRoot,
+  listUcodeSkills,
+  findSkillsByName,
+};

package/src/code/skills/render.js

@@ -0,0 +1,46 @@
+function renderSkillsSection(skills = []) {
+  const list = (Array.isArray(skills) ? skills : []).filter((skill) => skill && skill.enabled !== false);
+  if (list.length === 0) return "";
+
+  const lines = [];
+  lines.push("## Skills");
+  lines.push("ufoo/ucode skills are built-in or local preset workflow capabilities discovered from SKILL.md files. The list below is for discovery and selection; it is not a private capability list for one agent, and the full skill body is loaded only when a user explicitly requests a skill.");
+  lines.push("### Available skills");
+
+  for (const skill of list) {
+    const pathText = String(skill.path || "").replace(/\\/g, "/");
+    const desc = String(skill.description || skill.shortDescription || "").trim();
+    lines.push(`- ${skill.name}: ${desc} (file: ${pathText})`);
+  }
+
+  lines.push("### How to use skills");
+  lines.push("- If the user names a skill with `$SkillName` or links directly to a `SKILL.md`, use that skill for this turn.");
+  lines.push("- Do not assume a skill applies just because it exists; match the user request to the listed skill descriptions.");
+  lines.push("- When a skill is selected, read only the specific skill body and nearby referenced files needed for the task.");
+  lines.push("- If a skill is ambiguous, missing, or unreadable, say so briefly and continue with the best fallback.");
+
+  return lines.join("\n");
+}
+
+function formatSkillsList({ skills = [], errors = [] } = {}) {
+  const lines = [];
+  const list = (Array.isArray(skills) ? skills : []).filter((skill) => skill && skill.enabled !== false);
+  lines.push(`Available ufoo/ucode skills and preset workflows: ${list.length}`);
+  for (const skill of list) {
+    lines.push(`- ${skill.name}: ${skill.description} (${skill.scope}, ${skill.path})`);
+  }
+  const errs = Array.isArray(errors) ? errors : [];
+  if (errs.length > 0) {
+    lines.push("");
+    lines.push(`Skill load warnings: ${errs.length}`);
+    for (const err of errs) {
+      lines.push(`- ${err.path}: ${err.message}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  renderSkillsSection,
+  formatSkillsList,
+};

package/src/daemon/index.js

@@ -739,6 +739,10 @@ function startBusBridge(projectRoot, provider, onEvent, onStatus, shouldDrain) {
     subscriber: null,
     queueFile: null,
     pending: new Set(),
+    watchedAgents: new Set(),
+    lastEventSeq: 0,
+    emittedEventKeys: [],
+    emittedEventKeySet: new Set(),
   };
   const eventBus = new EventBus(projectRoot);
   let joinInProgress = false;
@@ -758,6 +762,169 @@ function startBusBridge(projectRoot, provider, onEvent, onStatus, shouldDrain) {
     return agentId;
   }
 
+  function getEventDedupeKey(evt) {
+    if (!evt || typeof evt !== "object") return "";
+    const seq = Number(evt.seq);
+    if (Number.isFinite(seq) && seq > 0) return `seq:${seq}`;
+    return [
+      "event",
+      evt.timestamp || evt.ts || "",
+      evt.event || "",
+      evt.publisher || "",
+      evt.target || "",
+      JSON.stringify(evt.data || {}),
+    ].join(":");
+  }
+
+  function rememberEmittedEvent(evt) {
+    const key = getEventDedupeKey(evt);
+    if (!key) return false;
+    if (state.emittedEventKeySet.has(key)) return true;
+    state.emittedEventKeySet.add(key);
+    state.emittedEventKeys.push(key);
+    if (state.emittedEventKeys.length > 500) {
+      const removed = state.emittedEventKeys.splice(0, state.emittedEventKeys.length - 500);
+      for (const item of removed) state.emittedEventKeySet.delete(item);
+    }
+    return false;
+  }
+
+  function hasPositiveSeq(seq) {
+    const value = Number(seq);
+    return Number.isFinite(value) && value > 0;
+  }
+
+  function toBridgeEvent(evt) {
+    const data = evt.data && typeof evt.data === "object" ? evt.data : {};
+    return {
+      seq: evt.seq,
+      event: evt.event,
+      publisher: evt.publisher,
+      target: evt.target,
+      data,
+      message: data.message || "",
+      state: data.state || "",
+      previous: data.previous || "",
+      subscriber: data.subscriber || "",
+      source: data.source || "",
+      injection_mode: data.injection_mode || "",
+      ts: evt.timestamp || evt.ts,
+    };
+  }
+
+  function emitBusEvent(evt) {
+    if (!evt || !onEvent) return;
+    if (rememberEmittedEvent(evt)) return;
+    onEvent(toBridgeEvent(evt));
+  }
+
+  function readAgentsData() {
+    try {
+      const busPath = getUfooPaths(projectRoot).agentsFile;
+      return JSON.parse(fs.readFileSync(busPath, "utf8"));
+    } catch {
+      return {};
+    }
+  }
+
+  function buildWatchedAliases() {
+    const aliases = new Set();
+    const bus = readAgentsData();
+    for (const agentId of state.watchedAgents) {
+      aliases.add(agentId);
+      const meta = bus.agents && bus.agents[agentId];
+      if (!meta) continue;
+      if (meta.nickname) aliases.add(meta.nickname);
+      if (meta.scoped_nickname) aliases.add(meta.scoped_nickname);
+      if (meta.display_nickname) aliases.add(meta.display_nickname);
+    }
+    return aliases;
+  }
+
+  function isWatchedEvent(evt, aliases = buildWatchedAliases()) {
+    if (!evt || (evt.event !== "message" && evt.event !== "activity_state_changed")) return false;
+    const publisher = String(evt.publisher || "");
+    const target = String(evt.target || "");
+    const subscriber = evt.data && evt.data.subscriber ? String(evt.data.subscriber) : "";
+    return aliases.has(publisher) || aliases.has(target) || aliases.has(subscriber);
+  }
+
+  function getEventFiles() {
+    try {
+      const dir = getUfooPaths(projectRoot).busEventsDir;
+      return fs.readdirSync(dir)
+        .filter((name) => name.endsWith(".jsonl"))
+        .sort()
+        .map((name) => path.join(dir, name));
+    } catch {
+      return [];
+    }
+  }
+
+  function readCurrentSeq() {
+    try {
+      const raw = fs.readFileSync(path.join(getUfooPaths(projectRoot).busDir, "seq.counter"), "utf8").trim();
+      const seq = Number(raw);
+      return Number.isFinite(seq) ? seq : 0;
+    } catch {
+      return 0;
+    }
+  }
+
+  function readEventFile(file) {
+    try {
+      return fs.readFileSync(file, "utf8")
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map((line) => {
+          try {
+            return JSON.parse(line);
+          } catch {
+            return null;
+          }
+        })
+        .filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+
+  function emitRecentWatchedEvents(agentId, limit = 80) {
+    if (!agentId) return;
+    const previous = new Set(state.watchedAgents);
+    state.watchedAgents.add(agentId);
+    const aliases = buildWatchedAliases();
+    state.watchedAgents = previous;
+    const matches = [];
+    const files = getEventFiles().slice(-3);
+    for (const file of files) {
+      for (const evt of readEventFile(file)) {
+        if (isWatchedEvent(evt, aliases)) matches.push(evt);
+      }
+    }
+    for (const evt of matches.slice(-limit)) emitBusEvent(evt);
+  }
+
+  function pollWatchedEvents() {
+    if (state.watchedAgents.size === 0) {
+      state.lastEventSeq = readCurrentSeq();
+      return;
+    }
+    const aliases = buildWatchedAliases();
+    let maxSeq = state.lastEventSeq;
+    for (const file of getEventFiles().slice(-2)) {
+      for (const evt of readEventFile(file)) {
+        const seq = Number(evt.seq);
+        if (hasPositiveSeq(seq)) {
+          if (seq <= state.lastEventSeq) continue;
+          if (seq > maxSeq) maxSeq = seq;
+        }
+        if (isWatchedEvent(evt, aliases)) emitBusEvent(evt);
+      }
+    }
+    state.lastEventSeq = Math.max(state.lastEventSeq, maxSeq);
+  }
+
   function ensureSubscriber() {
     if (state.subscriber || joinInProgress) return;
     const debugFile = path.join(getUfooPaths(projectRoot).runDir, "bus-join-debug.txt");
@@ -785,9 +952,7 @@ function startBusBridge(projectRoot, provider, onEvent, onStatus, shouldDrain) {
     })();
   }
 
-  function poll() {
-    ensureSubscriber();
-    if (typeof shouldDrain === "function" && !shouldDrain()) return;
+  function pollQueue() {
     if (!state.queueFile) return;
     if (!fs.existsSync(state.queueFile)) return;
     let content = "";
@@ -828,15 +993,7 @@ function startBusBridge(projectRoot, provider, onEvent, onStatus, shouldDrain) {
         continue;
       }
       if (!evt) continue;
-      if (onEvent) {
-        onEvent({
-          event: evt.event,
-          publisher: evt.publisher,
-          target: evt.target,
-          message: evt.data?.message || "",
-          ts: evt.timestamp || evt.ts,
-        });
-      }
+      emitBusEvent(evt);
       if (evt.publisher && state.pending.has(evt.publisher)) {
         state.pending.delete(evt.publisher);
         if (onStatus) {
@@ -847,6 +1004,13 @@ function startBusBridge(projectRoot, provider, onEvent, onStatus, shouldDrain) {
     }
   }
 
+  function poll() {
+    ensureSubscriber();
+    if (typeof shouldDrain === "function" && !shouldDrain()) return;
+    pollQueue();
+    pollWatchedEvents();
+  }
+
   const interval = setInterval(poll, 1000);
   return {
     markPending(target) {
@@ -865,6 +1029,19 @@ function startBusBridge(projectRoot, provider, onEvent, onStatus, shouldDrain) {
       } catch {}
       return state.subscriber;
     },
+    watchAgent(agentId, enabled = true) {
+      if (!agentId) return;
+      if (enabled) {
+        emitRecentWatchedEvents(agentId);
+        state.watchedAgents.add(agentId);
+        state.lastEventSeq = Math.max(state.lastEventSeq, readCurrentSeq());
+      } else {
+        state.watchedAgents.delete(agentId);
+        if (state.watchedAgents.size === 0) {
+          state.lastEventSeq = readCurrentSeq();
+        }
+      }
+    },
     stop() {
       clearInterval(interval);
     },
@@ -1187,6 +1364,13 @@ function startDaemon({ projectRoot, provider, model, resumeMode = "auto" }) {
       }
       return;
     }
+    if (req.type === IPC_REQUEST_TYPES.BUS_WATCH) {
+      const agentId = String(req.agent_id || "").trim();
+      if (agentId) {
+        busBridge.watchAgent(agentId, req.enabled !== false);
+      }
+      return;
+    }
     if (req.type === IPC_REQUEST_TYPES.CRON) {
       if (!daemonCronController) {
         socket.write(

package/src/shared/eventContract.js

@@ -5,6 +5,7 @@ const IPC_REQUEST_TYPES = {
   PROMPT: "prompt",
   CRON: "cron",
   BUS_SEND: "bus_send",
+  BUS_WATCH: "bus_watch",
   CLOSE_AGENT: "close_agent",
   LAUNCH_AGENT: "launch_agent",
   LAUNCH_GROUP: "launch_group",