@kaddo/mcp 3.20.0 → 3.21.0

package/README.md

@@ -49,7 +49,8 @@ directory set via the `KADDO_PROJECT_DIR` environment variable).
 | `kaddo://roadmap` | `knowledge/delivery/roadmap.md` | delivery roadmap |
 | `kaddo://capsules` | `.kaddo/external.yml` + `external/` | external Knowledge Capsules |
 | `kaddo://agents` | `knowledge/agents/` | installed agent prompts |
-| `kaddo://skills` | `knowledge/skills/` | installed skills (empty if none) |
+| `kaddo://skills` | `knowledge/skills/` | installed reusable skills (empty if none) |
+| `kaddo://skills/<id>` | `knowledge/skills/<id>/skill.md` | one reusable skill |
 
 ## Tools (read-only)
 
@@ -58,6 +59,7 @@ directory set via the `KADDO_PROJECT_DIR` environment variable).
 - `kaddo_get_work_item` — a Work Item by `id` (summary + full markdown).
 - `kaddo_list_capsules` / `kaddo_get_capsule` — external Knowledge Capsules.
 - `kaddo_list_agents` / `kaddo_get_agent_prompt` — installed agent prompts.
+- `kaddo_list_skills` / `kaddo_get_skill` — installed reusable skills.
 - `kaddo_list_graph_hints` — graph hints, filter by `artifact_type` / `severity` / `active_only`.
 
 ## Derived tools (write only under `.kaddo/`)

package/dist/index.js

@@ -207,8 +207,50 @@ function getAgentPrompt(root, name) {
   return { ...info, content };
 }
 
-// src/workitems.ts
+// src/skills.ts
 import matter2 from "gray-matter";
+function firstHeadingOrLine2(md) {
+  for (const line of md.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith("#") || t.startsWith("---")) continue;
+    return t.replace(/\s+/g, " ").slice(0, 200);
+  }
+  return "";
+}
+function listSkills(root) {
+  const files = listFiles(root, "knowledge/skills", "skill.md");
+  const out = [];
+  for (const rel of files) {
+    const raw = readText(root, rel);
+    if (raw === null) continue;
+    let data = {};
+    try {
+      data = matter2(raw).data;
+    } catch {
+    }
+    if (data.type && String(data.type) !== "skill") continue;
+    const folder = rel.split("/").slice(-2)[0];
+    out.push({
+      id: String(data.id ?? folder),
+      title: String(data.title ?? folder),
+      group: String(data.group ?? "unknown"),
+      applies_to: Array.isArray(data.applies_to) ? data.applies_to.map(String).filter(Boolean) : [],
+      path: rel
+    });
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+function getSkill(root, id) {
+  const want = id.replace(/\.md$/, "");
+  const info = listSkills(root).find((s) => s.id === want);
+  if (!info) return null;
+  const content = readText(root, info.path);
+  if (content === null) return null;
+  return { ...info, content, description: firstHeadingOrLine2(content) || info.title };
+}
+
+// src/workitems.ts
+import matter3 from "gray-matter";
 var ACTIVE_STATES = /* @__PURE__ */ new Set(["draft", "ready", "in-progress", "blocked"]);
 function strArray(v) {
   return Array.isArray(v) ? v.map((x) => String(x)).filter(Boolean) : [];
@@ -235,7 +277,7 @@ function listWorkItems(root) {
     if (raw === null) continue;
     let parsed;
     try {
-      parsed = matter2(raw);
+      parsed = matter3(raw);
     } catch {
       continue;
     }
@@ -396,18 +438,15 @@ var RESOURCES = [
   {
     uri: "kaddo://skills",
     name: "Kaddo skills",
-    description: "Installed skills from knowledge/skills/ (empty if none).",
+    description: "Installed reusable skills from knowledge/skills/ (empty if none).",
     mimeType: "application/json",
-    read: (root) => {
-      const files = listFiles(root, "knowledge/skills", ".md");
-      return [
-        {
-          uri: "kaddo://skills",
-          text: JSON.stringify({ skills: files }, null, 2),
-          mimeType: "application/json"
-        }
-      ];
-    }
+    read: (root) => [
+      {
+        uri: "kaddo://skills",
+        text: JSON.stringify({ skills: listSkills(root) }, null, 2),
+        mimeType: "application/json"
+      }
+    ]
   }
 ];
 
@@ -499,6 +538,14 @@ function getAgentPromptTool(root, name) {
   if (!agent) return fail(`Agent "${name}" is not installed. Run \`kaddo add agents\` first.`);
   return ok(agent);
 }
+function listSkillsTool(root) {
+  return ok(listSkills(root));
+}
+function getSkillTool(root, id) {
+  const skill = getSkill(root, id);
+  if (!skill) return fail(`Skill "${id}" is not installed. Run \`kaddo add skills\` first.`);
+  return ok(skill);
+}
 function listGraphHints(root, filter = {}) {
   const report = readJson(root, ".kaddo/graph-hints.json");
   if (!report) return fail("Graph hints not found. Run `kaddo graph export` first.");
@@ -528,6 +575,9 @@ function readDir(dirPath) {
 function isFile(p) {
   return exists(p) && fs2.statSync(p).isFile();
 }
+function isDir(p) {
+  return exists(p) && fs2.statSync(p).isDirectory();
+}
 function join(...parts) {
   return path2.join(...parts);
 }
@@ -619,13 +669,13 @@ ${issues}`);
 }
 
 // ../cli/src/core/context-pack.ts
-import matter5 from "gray-matter";
+import matter7 from "gray-matter";
 
 // ../cli/src/services/artifact-reader.ts
-import matter3 from "gray-matter";
+import matter4 from "gray-matter";
 function parseArtifact(filePath, raw) {
   try {
-    const { data } = matter3(raw);
+    const { data } = matter4(raw);
     const globs = Array.isArray(data.code) ? data.code.filter(Boolean) : [];
     return {
       filePath,
@@ -1283,7 +1333,7 @@ function assessPhase(input) {
 }
 
 // ../cli/src/core/capsule.ts
-import matter4 from "gray-matter";
+import matter5 from "gray-matter";
 import { parse as parseYaml5, stringify as stringifyYaml } from "yaml";
 
 // ../cli/src/services/owners.ts
@@ -1436,7 +1486,7 @@ function sectionParagraph2(md, title) {
   return "";
 }
 function parseCapsule(id, path3, md) {
-  const { data } = matter4(md);
+  const { data } = matter5(md);
   const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
   let ageDays = null;
   if (updatedAt) {
@@ -1877,6 +1927,38 @@ function loadGraphHints(dir) {
   }
 }
 
+// ../cli/src/services/installed-skills.ts
+import matter6 from "gray-matter";
+var SKILLS_DIR = join("knowledge", "skills");
+function discoverInstalledSkills(dir) {
+  const base = join(dir, SKILLS_DIR);
+  if (!exists(base) || !isDir(base)) return [];
+  const out = [];
+  for (const entry of readDir(base)) {
+    const skillFile = join(base, entry, "skill.md");
+    if (!isFile(skillFile)) continue;
+    try {
+      const { data } = matter6(readFile(skillFile));
+      if (data.type && String(data.type) !== "skill") continue;
+      const id = String(data.id ?? entry);
+      out.push({
+        id,
+        title: String(data.title ?? id),
+        group: String(data.group ?? "unknown"),
+        appliesTo: Array.isArray(data.applies_to) ? data.applies_to.map(String).filter(Boolean) : [],
+        relPath: `${SKILLS_DIR.replace(/\\/g, "/")}/${entry}/skill.md`
+      });
+    } catch {
+    }
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+function skillGroupCounts(skills) {
+  const counts = {};
+  for (const s of skills) counts[s.group] = (counts[s.group] ?? 0) + 1;
+  return counts;
+}
+
 // ../cli/src/core/context-pack.ts
 var CONTEXT_PACK_VERSION = "1";
 var ARCH_DIR2 = "knowledge";
@@ -1890,7 +1972,7 @@ function readScanJson(dir) {
   }
 }
 function firstParagraph3(markdown) {
-  const body = matter5(markdown).content.trim();
+  const body = matter7(markdown).content.trim();
   const para = body.split("\n\n").map((p) => p.trim()).find((p) => p && !p.startsWith("#"));
   return para ?? "";
 }
@@ -2063,6 +2145,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     external: loadExternalCapsules(dir),
     graph: loadGraphSummary(dir),
     graphHints: loadGraphHints(dir),
+    skills: discoverInstalledSkills(dir).map((s) => s.id),
     mappedModules,
     missing,
     // VS-052: the handoff is driven by the REAL phase, not project.state, so the pack never
@@ -2256,6 +2339,12 @@ function renderContextPack(pack) {
 `);
     }
   }
+  if (pack.skills.length > 0) {
+    parts.push("## Skills\n");
+    parts.push("Available reusable skills (agents apply these; content is not inlined):\n");
+    parts.push(pack.skills.map((s) => `- ${s}`).join("\n") + "\n");
+    parts.push("Read full skill definitions in `knowledge/skills/` or via the Kaddo MCP server (`kaddo://skills`).\n");
+  }
   parts.push("## Missing Context\n");
   if (missing.length > 0) {
     parts.push(missing.map((m) => `- ${m}`).join("\n") + "\n");
@@ -2475,6 +2564,10 @@ function buildProjectExplanation(dir) {
     externalCapsules: loadExternalCapsules(dir),
     graph: loadGraphSummary(dir),
     graphHints: loadGraphHints(dir),
+    skills: (() => {
+      const installed = discoverInstalledSkills(dir);
+      return { total: installed.length, byGroup: skillGroupCounts(installed) };
+    })(),
     layers,
     roadmap,
     mappedModules,
@@ -2625,6 +2718,15 @@ function renderExplanationHuman(exp) {
     if (exp.graph.generatedAt) lines.push(`- Last exported: ${exp.graph.generatedAt}`);
     lines.push("");
   }
+  if (exp.skills.total > 0) {
+    lines.push(`## Skills installed: ${exp.skills.total}`);
+    const groups = Object.entries(exp.skills.byGroup).sort((a, b) => a[0].localeCompare(b[0]));
+    if (groups.length > 0) {
+      lines.push("Groups:");
+      for (const [g, n] of groups) lines.push(`- ${g}: ${n}`);
+    }
+    lines.push("");
+  }
   if (exp.missingKnowledge.length > 0) {
     lines.push("## Missing Knowledge");
     for (const m of exp.missingKnowledge) lines.push(`- ${m}`);
@@ -3021,6 +3123,38 @@ function createServer(root) {
     },
     async (args) => toolText(guarded(root, () => listGraphHints(root, args)))
   );
+  server.registerTool(
+    "kaddo_list_skills",
+    { title: "List skills", description: "List installed reusable skills.", inputSchema: {} },
+    async () => toolText(guarded(root, () => listSkillsTool(root)))
+  );
+  server.registerTool(
+    "kaddo_get_skill",
+    { title: "Get skill", description: "Get an installed reusable skill by id.", inputSchema: { id: z2.string() } },
+    async (args) => toolText(guarded(root, () => getSkillTool(root, args.id)))
+  );
+  let installedSkills = [];
+  try {
+    assertKaddoProject(root);
+    installedSkills = listSkills(root);
+  } catch {
+    installedSkills = [];
+  }
+  for (const s of installedSkills) {
+    server.registerResource(
+      `skill: ${s.id}`,
+      `kaddo://skills/${s.id}`,
+      { title: s.title, description: `Reusable skill "${s.id}" (${s.group}).`, mimeType: "text/markdown" },
+      async (uri) => {
+        const full = getSkill(root, s.id);
+        return {
+          contents: [
+            { uri: uri.href, text: full?.content ?? `Skill "${s.id}" not found.`, mimeType: "text/markdown" }
+          ]
+        };
+      }
+    );
+  }
   server.registerTool(
     "kaddo_generate_context",
     { title: "Generate context pack", description: `Regenerate .kaddo/context-pack.md + .json. ${DERIVED_NOTE}`, inputSchema: {} },
@@ -3064,6 +3198,17 @@ function createServer(root) {
       }
     );
   }
+  for (const s of installedSkills) {
+    server.registerPrompt(
+      `skill-${s.id}`,
+      { title: s.title, description: `Reusable skill "${s.id}" (${s.group}).` },
+      async () => {
+        const full = getSkill(root, s.id);
+        const content = full?.content ?? `Skill "${s.id}" is not installed.`;
+        return { messages: [{ role: "user", content: { type: "text", text: content } }] };
+      }
+    );
+  }
   return server;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/mcp",
-  "version": "3.20.0",
+  "version": "3.21.0",
   "description": "MCP server for Kaddo project knowledge: read-only resources/tools/prompts plus safe derived generation under .kaddo/.",
   "license": "MIT",
   "repository": {