@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/engine/skills/index.mjs

@@ -0,0 +1,321 @@
+/**
+ * lib/engine/skills/index.mjs — skills: discovery, the listing, the Skill tool.
+ *
+ * A skill is a Markdown file with YAML frontmatter (the Agent Skills format):
+ *
+ *   ---
+ *   name: board-work
+ *   description: What it does and when to use it.
+ *   when_to_use: Extra triggers (optional).
+ *   allowed-tools: Read, Grep        (optional; recorded, not yet enforced)
+ *   ---
+ *   # Instructions …
+ *
+ * Where skills are found, in precedence order (the first skill with a name wins):
+ *   user      ~/.claude/skills/<dir>/SKILL.md
+ *   project   <cwd>/.claude/skills/<dir>/SKILL.md
+ *   plugins   each plugin root listed in settings `cohort.pluginDirs` or given
+ *             with --plugin-dir (a `dir/*` entry means every subdirectory):
+ *             <root>/skills/<dir>/SKILL.md and <root>/skills/<name>.md
+ *             (maestro's plugins/maestro-skills uses the flat form). Plugin
+ *             skills are named `<plugin>:<name>`, the plugin name coming from
+ *             <root>/plugin.json or the directory name.
+ *
+ * Progressive disclosure: the system prompt lists only each skill's name and
+ * description (plus when_to_use), cut to 1,536 characters. The Skill tool
+ * loads the full body when the model asks for it, with the skill's base
+ * directory so relative references in the body resolve.
+ *
+ * @module lib/engine/skills/index
+ */
+
+import path from "node:path";
+import yaml from "js-yaml";
+
+export const MAX_LISTED_DESCRIPTION = 1536;
+
+/**
+ * @typedef {Object} Skill
+ * @property {string} name          as listed and as passed to the Skill tool
+ * @property {string} description
+ * @property {string|null} whenToUse
+ * @property {string[]} allowedTools
+ * @property {string} file
+ * @property {string} baseDir
+ * @property {'user'|'project'|'plugin'} source
+ * @property {string[]} [aliases]   other spellings a plugin skill answers to (pluginIdentity), never listed
+ */
+
+/**
+ * @param {string} text
+ * @returns {{frontmatter: Record<string, unknown>, body: string}}
+ */
+export function parseSkillFile(text) {
+  const t = String(text).replace(/^/, "");
+  const m = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(t);
+  if (!m) return { frontmatter: {}, body: t };
+  const raw = m[1];
+  const body = t.slice(m[0].length);
+  try {
+    // js-yaml 4's load() uses the safe default schema: no tag constructs code.
+    const doc = yaml.load(raw);
+    if (doc && typeof doc === "object" && !Array.isArray(doc)) return { frontmatter: /** @type any */ (doc), body };
+  } catch {
+    // Frontmatter that is "YAML-ish" (an unquoted description containing
+    // ": ") is common in the wild; fall back to one key per line below.
+  }
+  /** @type {Record<string,string>} */
+  const fm = {};
+  for (const line of raw.split(/\r?\n/)) {
+    const kv = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line);
+    if (kv) fm[kv[1]] = kv[2].replace(/^["']|["']$/g, "");
+  }
+  return { frontmatter: fm, body };
+}
+
+/** @param {unknown} v */
+function toolList(v) {
+  if (Array.isArray(v)) return v.map(String).map((s) => s.trim()).filter(Boolean);
+  if (typeof v === "string") return v.split(/[,\s]+/).map((s) => s.trim()).filter(Boolean);
+  return [];
+}
+
+/**
+ * @param {{file:string, text:string, source:Skill['source'], fallbackName:string, namespace?:string|null}} p
+ * @returns {Skill}
+ */
+export function skillFromFile({ file, text, source, fallbackName, namespace = null }) {
+  const { frontmatter: fm, body } = parseSkillFile(text);
+  const base = typeof fm.name === "string" && fm.name.trim() !== "" ? fm.name.trim() : fallbackName;
+  let description = typeof fm.description === "string" ? fm.description.trim() : "";
+  if (description === "") description = (body.split(/\r?\n/).map((l) => l.replace(/^#+\s*/, "").trim()).find((l) => l !== "") ?? "").slice(0, 200);
+  const whenToUse = typeof fm.when_to_use === "string" ? fm.when_to_use.trim() : typeof fm["when-to-use"] === "string" ? String(fm["when-to-use"]).trim() : null;
+  return {
+    name: namespace ? `${namespace}:${base}` : base,
+    description,
+    whenToUse: whenToUse || null,
+    allowedTools: toolList(fm["allowed-tools"] ?? fm.allowed_tools),
+    file,
+    baseDir: path.dirname(file),
+    source,
+  };
+}
+
+/** @param {Skill} skill */
+export function listingDescription(skill) {
+  const full = skill.whenToUse ? `${skill.description} ${skill.whenToUse}` : skill.description;
+  return full.length <= MAX_LISTED_DESCRIPTION ? full : `${full.slice(0, MAX_LISTED_DESCRIPTION - 1)}…`;
+}
+
+/**
+ * @typedef {Object} SkillFs
+ * @property {(p:string)=>string} readFile
+ * @property {(p:string)=>string[]} readdir   names only
+ * @property {(p:string)=>boolean} isFile
+ * @property {(p:string)=>boolean} isDir
+ */
+
+/**
+ * @param {object} p
+ * @param {string|null} p.userDir          ~/.claude
+ * @param {string} p.cwd
+ * @param {Array<{dir:string, source?:string}>} [p.pluginDirs]
+ * @param {SkillFs} p.fs
+ * @returns {{skills: Skill[], errors: string[]}}
+ */
+export function discoverSkills({ userDir, cwd, pluginDirs = [], fs }) {
+  /** @type {Skill[]} */
+  const skills = [];
+  const errors = [];
+  const byName = new Map();
+  const sortedNames = (/** @type string */ dir) => {
+    try {
+      return fs.readdir(dir).sort();
+    } catch {
+      return [];
+    }
+  };
+  const add = (/** @type {Parameters<typeof skillFromFile>[0] extends infer P ? Omit<P,'text'> : never} */ p) => {
+    let text;
+    try {
+      text = fs.readFile(p.file);
+    } catch (e) {
+      errors.push(`skill ${p.file}: cannot read (${e instanceof Error ? e.message : e})`);
+      return;
+    }
+    const skill = skillFromFile({ ...p, text });
+    if (byName.has(skill.name)) {
+      errors.push(`skill "${skill.name}" at ${skill.file} is shadowed by ${byName.get(skill.name).file}`);
+      return;
+    }
+    byName.set(skill.name, skill);
+    skills.push(skill);
+  };
+  const dirSkills = (/** @type string */ skillsDir, /** @type {Skill['source']} */ source, /** @type {string|null} */ namespace, /** @type boolean */ flat) => {
+    if (!fs.isDir(skillsDir)) return;
+    for (const entry of sortedNames(skillsDir)) {
+      const full = path.join(skillsDir, entry);
+      if (fs.isDir(full)) {
+        const file = path.join(full, "SKILL.md");
+        if (fs.isFile(file)) add({ file, source, fallbackName: entry, namespace });
+      } else if (flat && entry.endsWith(".md") && fs.isFile(full)) {
+        add({ file: full, source, fallbackName: entry.slice(0, -3), namespace });
+      }
+    }
+  };
+
+  if (userDir) dirSkills(path.join(userDir, "skills"), "user", null, false);
+  dirSkills(path.join(cwd, ".claude", "skills"), "project", null, false);
+
+  for (const root of expandPluginRoots(pluginDirs, fs)) {
+    if (!fs.isDir(root)) {
+      errors.push(`plugin directory ${root} does not exist`);
+      continue;
+    }
+    const identity = pluginIdentity(root, fs);
+    errors.push(...identity.errors);
+    const before = skills.length;
+    dirSkills(path.join(root, "skills"), "plugin", identity.name, true);
+    for (const s of skills.slice(before)) s.aliases = identity.aliases.map((a) => `${a}:${s.name.slice(identity.name.length + 1)}`);
+  }
+  return { skills, errors };
+}
+
+/**
+ * Plugin roots from settings `cohort.pluginDirs` / --plugin-dir entries, a `dir/*` entry
+ * expanded to its subdirectories, duplicates removed, order kept.
+ * @param {Array<{dir:string}>} pluginDirs @param {{readdir:(p:string)=>string[], isDir:(p:string)=>boolean}} fs
+ */
+export function expandPluginRoots(pluginDirs, fs) {
+  const roots = [];
+  for (const { dir } of pluginDirs) {
+    if (dir.endsWith(`${path.sep}*`) || dir.endsWith("/*")) {
+      const parent = dir.slice(0, -2);
+      let names = [];
+      try {
+        names = fs.readdir(parent).sort();
+      } catch {
+        names = [];
+      }
+      for (const name of names) if (fs.isDir(path.join(parent, name))) roots.push(path.join(parent, name));
+    } else {
+      roots.push(dir);
+    }
+  }
+  return [...new Set(roots)];
+}
+
+const NAMESPACE_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+
+/**
+ * A plugin's namespace (W4-E2, CF-91). The name its manifest declares —
+ * `<root>/.claude-plugin/plugin.json`, then `<root>/plugin.json` — else the
+ * directory name. Aliases, accepted when invoking but never listed:
+ *   · the directory name, when the manifest declares another name;
+ *   · for a pack named `<stem>-skills`, the stem. maestro installs such a pack's
+ *     skills as `~/.claude/skills/<stem>-<name>` (lib/collective/global-skills.mjs)
+ *     and its bootstrap prompt invokes them as `/<stem>:<name>` (`/maestro:main-session`).
+ * @param {string} root @param {{readFile:(p:string)=>string, isFile:(p:string)=>boolean}} fs
+ * @returns {{name:string, aliases:string[], errors:string[]}}
+ */
+export function pluginIdentity(root, fs) {
+  const dirName = path.basename(root);
+  const errors = [];
+  let declared = null;
+  for (const manifest of [path.join(root, ".claude-plugin", "plugin.json"), path.join(root, "plugin.json")]) {
+    if (!fs.isFile(manifest)) continue;
+    try {
+      const doc = JSON.parse(fs.readFile(manifest));
+      if (typeof doc?.name === "string" && NAMESPACE_RE.test(doc.name.trim())) {
+        declared = doc.name.trim();
+        break;
+      }
+    } catch (e) {
+      errors.push(`plugin manifest ${manifest}: ${e instanceof Error ? e.message : e}`);
+    }
+  }
+  const name = declared ?? dirName;
+  const aliases = new Set();
+  if (dirName !== name && NAMESPACE_RE.test(dirName)) aliases.add(dirName);
+  const stem = /^(.+)-skills$/.exec(name)?.[1];
+  if (stem && NAMESPACE_RE.test(stem)) aliases.add(stem);
+  aliases.delete(name);
+  return { name, aliases: [...aliases], errors };
+}
+
+/** The system-prompt block listing skills (pure). Null when there are none. @param {Skill[]} skills */
+export function formatSkillListing(skills) {
+  if (skills.length === 0) return null;
+  const lines = skills.map((s) => `- ${s.name}: ${listingDescription(s)}`);
+  return `Skills are packaged instructions for particular kinds of work. When a task matches one, load it with the Skill tool before starting, and follow what it says.\n\nAvailable skills:\n${lines.join("\n")}`;
+}
+
+/**
+ * Find a skill by the name the model gave: exact, then without a leading "/",
+ * then a unique plugin skill whose unqualified name matches.
+ * @param {Skill[]} skills @param {string} requested
+ * @returns {{ok:true, skill:Skill} | {ok:false, error:string}}
+ */
+export function findSkill(skills, requested) {
+  const want = String(requested ?? "").trim().replace(/^\//, "");
+  const exact = skills.find((s) => s.name === want);
+  if (exact) return { ok: true, skill: exact };
+  // W4-E2 (CF-91): a plugin namespace alias (`maestro:main-session` for `maestro-skills:main-session`),
+  // then the flat installed form of a namespaced name (`maestro:main-session` → `maestro-main-session`).
+  const aliased = skills.find((s) => (s.aliases ?? []).includes(want));
+  if (aliased) return { ok: true, skill: aliased };
+  const colon = want.indexOf(":");
+  if (colon > 0 && want.indexOf(":", colon + 1) === -1) {
+    const flat = skills.find((s) => s.name === `${want.slice(0, colon)}-${want.slice(colon + 1)}`);
+    if (flat) return { ok: true, skill: flat };
+  }
+  if (!want.includes(":")) {
+    const suffix = skills.filter((s) => s.name.endsWith(`:${want}`));
+    if (suffix.length === 1) return { ok: true, skill: suffix[0] };
+    if (suffix.length > 1) return { ok: false, error: `"${want}" matches several skills: ${suffix.map((s) => s.name).join(", ")}. Use the full name.` };
+  }
+  const names = skills.map((s) => s.name);
+  return { ok: false, error: `There is no skill named "${want}".${names.length ? ` Available skills: ${names.join(", ")}.` : " No skills are installed."}` };
+}
+
+/**
+ * @param {Skill[]} skills
+ * @param {{readFile:(p:string)=>string}} fs
+ * @returns {import('../tools/index.mjs').Tool}
+ */
+export function createSkillTool(skills, fs) {
+  return {
+    name: "Skill",
+    readOnly: true,
+    description:
+      "Load the full instructions of one of the skills listed in the system prompt, so you can follow them. " +
+      "Pass the skill's name exactly as listed; `args` is optional text the skill should work with.",
+    input_schema: {
+      type: "object",
+      properties: {
+        skill: { type: "string", description: "The skill name, as listed." },
+        args: { type: "string", description: "Optional arguments for the skill." },
+      },
+      required: ["skill"],
+    },
+    async run(input) {
+      const found = findSkill(skills, input.skill);
+      if (!found.ok) return { ok: false, error: found.error };
+      const s = found.skill;
+      let text;
+      try {
+        text = fs.readFile(s.file);
+      } catch (e) {
+        return { ok: false, error: `The skill "${s.name}" could not be read from ${s.file}: ${e instanceof Error ? e.message : e}` };
+      }
+      let body = parseSkillFile(text).body.trim();
+      const args = typeof input.args === "string" ? input.args.trim() : "";
+      if (args && body.includes("$ARGUMENTS")) body = body.split("$ARGUMENTS").join(args);
+      else if (args) body = `${body}\n\nArguments: ${args}`;
+      return {
+        ok: true,
+        content: `Skill "${s.name}" is loaded. Its base directory is ${s.baseDir}; resolve relative paths in these instructions against it.\n\n${body}`,
+      };
+    },
+  };
+}