u-foo 2.3.18 → 2.3.20

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,
+};