skill-library-mcp 1.0.0

package/src/search.ts

@@ -0,0 +1,83 @@
+import type { SearchIndex, SearchResult } from "./types.js";
+
+const STOP_WORDS = new Set([
+  "a", "an", "the", "build", "write", "create", "use", "using", "when",
+  "this", "for", "from", "with", "that", "are", "has", "its", "was",
+  "will", "your", "you", "is", "it", "in", "on", "of", "to", "be",
+  "by", "at", "as", "and", "help", "need", "want", "how", "do", "can",
+  "me", "i", "my", "show", "about", "what", "should", "please",
+]);
+
+function tokenize(text: string): string[] {
+  return text.toLowerCase().replace(/[^a-z0-9\-]/g, " ").split(/\s+/).filter(Boolean);
+}
+
+export function searchSkills(
+  index: SearchIndex,
+  query: string,
+  limit: number = 20,
+): SearchResult[] {
+  const rawTokens = tokenize(query);
+  if (rawTokens.length === 0) return [];
+
+  // Filter stop-words, but keep all if every token is a stop-word
+  const filtered = rawTokens.filter((t) => !STOP_WORDS.has(t));
+  const meaningful = filtered.length > 0 ? filtered : rawTokens;
+
+  // Deduplicate query tokens
+  const queryTokens = [...new Set(meaningful)];
+
+  const queryLower = query.toLowerCase();
+  const results: SearchResult[] = [];
+
+  // Default IDF for tokens not in the index (treat as very rare)
+  const defaultIdf = Math.log((index.totalDocs || 1) + 1);
+
+  for (const entry of index.entries) {
+    let score = 0;
+
+    let matchedTokens = 0;
+
+    for (const qt of queryTokens) {
+      const idfWeight = index.idfScores.get(qt) ?? defaultIdf;
+      let bestTokenScore = 0;
+
+      for (const st of entry.searchTokens) {
+        if (st === qt) {
+          bestTokenScore = Math.max(bestTokenScore, idfWeight);
+        } else if (qt.length >= 2 && st.length >= 2 && (st.includes(qt) || qt.includes(st))) {
+          bestTokenScore = Math.max(bestTokenScore, idfWeight * 0.5);
+        }
+      }
+
+      if (bestTokenScore > 0) matchedTokens++;
+      score += bestTokenScore;
+    }
+
+    // Bonus for exact substring match in name
+    if (entry.frontmatter.name.toLowerCase().includes(queryLower)) {
+      score += 2.0;
+    }
+
+    // Bonus for exact substring match in description
+    if (entry.frontmatter.description.toLowerCase().includes(queryLower)) {
+      score += 1.0;
+    }
+
+    // Normalize by matched token count (unmatched tokens don't dilute score)
+    score = score / Math.max(matchedTokens, 1);
+
+    if (score >= 0.5) {
+      results.push({
+        name: entry.frontmatter.name,
+        dirName: entry.dirName,
+        description: entry.frontmatter.description,
+        score: Math.round(score * 100) / 100,
+        hasResources: entry.hasResources,
+      });
+    }
+  }
+
+  results.sort((a, b) => b.score - a.score);
+  return results.slice(0, limit);
+}

package/src/server.ts

@@ -0,0 +1,83 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { SkillEntry, SearchIndex } from "./types.js";
+import { searchSkills } from "./search.js";
+import { loadSkill } from "./loader.js";
+
+export function createServer(index: SearchIndex, skillsDir: string): McpServer {
+  const server = new McpServer({
+    name: "skill-library",
+    version: "1.0.0",
+  });
+
+  // Build lookup map keyed by both dirName and frontmatter name
+  const lookupMap = new Map<string, SkillEntry>();
+  for (const entry of index.entries) {
+    lookupMap.set(entry.dirName.toLowerCase(), entry);
+    lookupMap.set(entry.frontmatter.name.toLowerCase(), entry);
+  }
+
+  server.tool(
+    "search_skill",
+    "Search for skills by keyword. Returns ranked list of matching skill names and descriptions.",
+    { query: z.string().describe("Keywords to search for (e.g. 'debugging', 'react patterns', 'terraform')") },
+    async ({ query }) => {
+      const results = searchSkills(index, query);
+
+      if (results.length === 0) {
+        return {
+          content: [{ type: "text", text: `No skills found matching "${query}".` }],
+        };
+      }
+
+      const lines = results.map(
+        (r) => `- **${r.name}** (${r.dirName})${r.hasResources ? " [+resources]" : ""} — ${r.description}`,
+      );
+
+      return {
+        content: [{
+          type: "text",
+          text: `Found ${results.length} skills matching "${query}":\n\n${lines.join("\n")}`,
+        }],
+      };
+    },
+  );
+
+  server.tool(
+    "load_skill",
+    "Load the full content of a skill by name. Returns the complete SKILL.md content and optionally resources.",
+    {
+      name: z.string().describe("Skill name or directory name (e.g. 'brainstorming', 'ai-engineer')"),
+      include_resources: z.boolean().default(false).describe("Whether to include resource files"),
+    },
+    async ({ name, include_resources }) => {
+      const entry = lookupMap.get(name.toLowerCase());
+
+      if (!entry) {
+        // Try fuzzy match
+        const results = searchSkills(index, name, 5);
+        if (results.length > 0) {
+          const suggestions = results.map((r) => r.name).join(", ");
+          return {
+            content: [{
+              type: "text",
+              text: `Skill "${name}" not found. Did you mean: ${suggestions}?`,
+            }],
+          };
+        }
+
+        return {
+          content: [{ type: "text", text: `Skill "${name}" not found.` }],
+        };
+      }
+
+      const content = await loadSkill(entry, skillsDir, include_resources);
+
+      return {
+        content: [{ type: "text", text: content }],
+      };
+    },
+  );
+
+  return server;
+}

package/src/skill-index.ts

@@ -0,0 +1,105 @@
+import { readdir, readFile, access } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import type { SkillEntry, SkillFrontmatter, SearchIndex } from "./types.js";
+
+function parseFrontmatter(content: string): SkillFrontmatter | null {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  try {
+    const parsed = parseYaml(match[1]);
+    if (!parsed || typeof parsed.name !== "string") return null;
+    return {
+      name: parsed.name,
+      description: typeof parsed.description === "string" ? parsed.description.trim() : "",
+      metadata: parsed.metadata,
+      allowedTools: parsed.allowedTools,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function tokenize(text: string): Set<string> {
+  const words = text.toLowerCase().replace(/[^a-z0-9\-]/g, " ").split(/\s+/).filter(Boolean);
+  const tokens = new Set<string>();
+  for (const word of words) {
+    tokens.add(word);
+    // Split hyphenated tokens into sub-tokens
+    if (word.includes("-")) {
+      for (const part of word.split("-")) {
+        if (part) tokens.add(part);
+      }
+    }
+  }
+  return tokens;
+}
+
+export async function buildIndex(skillsDir: string): Promise<SearchIndex> {
+  const entries: SkillEntry[] = [];
+  let dirs: string[];
+
+  try {
+    dirs = await readdir(skillsDir);
+  } catch {
+    return { entries, idfScores: new Map(), totalDocs: 0 };
+  }
+
+  for (const dirName of dirs) {
+    const skillPath = join(skillsDir, dirName, "SKILL.md");
+
+    try {
+      await access(skillPath);
+    } catch {
+      continue;
+    }
+
+    const content = await readFile(skillPath, "utf-8");
+    const frontmatter = parseFrontmatter(content);
+    if (!frontmatter) continue;
+
+    // Check for resources
+    const resourceDir = join(skillsDir, dirName, "resources");
+    let hasResources = false;
+    let resourceFiles: string[] = [];
+
+    try {
+      const files = await readdir(resourceDir);
+      resourceFiles = files.filter((f) => f.endsWith(".md"));
+      hasResources = resourceFiles.length > 0;
+    } catch {
+      // No resources directory
+    }
+
+    const searchTokens = new Set([
+      ...tokenize(frontmatter.name),
+      ...tokenize(frontmatter.description),
+    ]);
+
+    entries.push({
+      dirName,
+      frontmatter,
+      searchTokens,
+      hasResources,
+      resourceFiles,
+    });
+  }
+
+  // Compute IDF scores
+  const totalDocs = entries.length;
+  const docFrequency = new Map<string, number>();
+
+  for (const entry of entries) {
+    for (const token of entry.searchTokens) {
+      docFrequency.set(token, (docFrequency.get(token) ?? 0) + 1);
+    }
+  }
+
+  const idfScores = new Map<string, number>();
+  for (const [token, df] of docFrequency) {
+    idfScores.set(token, Math.log(totalDocs / df));
+  }
+
+  return { entries, idfScores, totalDocs };
+}

package/src/types.ts

@@ -0,0 +1,28 @@
+export interface SkillFrontmatter {
+  name: string;
+  description: string;
+  metadata?: Record<string, unknown>;
+  allowedTools?: string[];
+}
+
+export interface SkillEntry {
+  dirName: string;
+  frontmatter: SkillFrontmatter;
+  searchTokens: Set<string>;
+  hasResources: boolean;
+  resourceFiles: string[];
+}
+
+export interface SearchIndex {
+  entries: SkillEntry[];
+  idfScores: Map<string, number>;
+  totalDocs: number;
+}
+
+export interface SearchResult {
+  name: string;
+  dirName: string;
+  description: string;
+  score: number;
+  hasResources: boolean;
+}

package/test/dedup.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findDuplicates } from "../src/dedup.js";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const skillsDir = join(__dirname, "..", "skills");
+
+describe("dedup: real skills/ directory", () => {
+  it("has zero exact duplicates", async () => {
+    const report = await findDuplicates(skillsDir);
+    if (report.exactDuplicates.length > 0) {
+      const details = report.exactDuplicates
+        .map((g) => `  "${g[0].name}": ${g.map((s) => s.dirName).join(", ")}`)
+        .join("\n");
+      expect.fail(`Found exact duplicates:\n${details}`);
+    }
+  });
+
+  it("reports near-duplicates without failing", async () => {
+    const report = await findDuplicates(skillsDir);
+    if (report.nearDuplicates.length > 0) {
+      console.warn(
+        `⚠️  ${report.nearDuplicates.length} near-duplicate pair(s) found:`,
+        report.nearDuplicates.map(
+          ({ pair, similarity }) => `${pair[0].dirName} ↔ ${pair[1].dirName} (${(similarity * 100).toFixed(0)}%)`,
+        ),
+      );
+    }
+    // This is a warning, not a failure
+    expect(true).toBe(true);
+  });
+});

package/test/fixtures/allowed-tools/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: allowed-tools
+description: A skill that specifies allowed tools
+allowedTools: [Bash, Read]
+---
+
+# Allowed Tools
+
+This skill declares which tools it is allowed to use.

package/test/fixtures/basic-skill/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: basic-skill
+description: A basic test skill for unit testing
+metadata:
+  category: testing
+  difficulty: easy
+---
+
+# Basic Skill
+
+This is a basic skill used for testing purposes.

package/test/fixtures/empty-description/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: empty-description
+---
+
+# Empty Description
+
+This skill has no description field in its frontmatter.

package/test/fixtures/invalid-frontmatter/SKILL.md

@@ -0,0 +1,7 @@
+---
+this is not: valid: yaml: [broken
+---
+
+# Invalid Frontmatter
+
+This skill has malformed YAML frontmatter.

package/test/fixtures/multiline-description/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: multiline-description
+description: >
+  This skill has a multiline description using
+  a YAML folded scalar to test frontmatter parsing
+  of long descriptions.
+---
+
+# Multiline Description
+
+This skill tests multiline YAML description parsing.

package/test/fixtures/no-frontmatter/SKILL.md

@@ -0,0 +1,3 @@
+# No Frontmatter
+
+This skill has no YAML frontmatter block at all.

package/test/fixtures/skill-with-hyphenated-resources/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: skill-with-hyphenated-resources
+description: A skill with hyphenated resource filenames
+---
+
+# Skill With Hyphenated Resources
+
+This skill has resource files with hyphens in their names.

package/test/fixtures/skill-with-hyphenated-resources/resources/implementation-playbook.md

@@ -0,0 +1,3 @@
+# Implementation Playbook
+
+Step-by-step implementation guide.

package/test/fixtures/skill-with-hyphenated-resources/resources/quick-start-guide.md

@@ -0,0 +1,3 @@
+# Quick Start Guide
+
+Get started quickly with this guide.

package/test/fixtures/skill-with-resources/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: skill-with-resources
+description: A skill that includes additional resource files
+---
+
+# Skill With Resources
+
+This skill has additional resource files in the resources directory.

package/test/fixtures/skill-with-resources/resources/examples.md

@@ -0,0 +1,3 @@
+# Examples
+
+Here are some usage examples for the skill.

package/test/fixtures/skill-with-resources/resources/guide.md

@@ -0,0 +1,3 @@
+# Guide
+
+This is a guide for using the skill effectively.

package/test/integration.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildIndex } from "../src/skill-index.js";
+import { searchSkills } from "../src/search.js";
+import { loadSkill } from "../src/loader.js";
+import type { SearchIndex } from "../src/types.js";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const skillsDir = join(__dirname, "..", "skills");
+
+let index: SearchIndex;
+
+beforeAll(async () => {
+  index = await buildIndex(skillsDir);
+});
+
+describe("integration: real skills/ directory", () => {
+  it("indexes all skills (expect ≥690)", () => {
+    expect(index.entries.length).toBeGreaterThanOrEqual(690);
+  });
+
+  it("every entry has non-empty name", () => {
+    for (const entry of index.entries) {
+      expect(entry.frontmatter.name).toBeTruthy();
+    }
+  });
+
+  it("every entry has searchTokens", () => {
+    for (const entry of index.entries) {
+      expect(entry.searchTokens.size).toBeGreaterThan(0);
+    }
+  });
+
+  it("IDF scores computed for real index", () => {
+    expect(index.idfScores.size).toBeGreaterThan(0);
+    expect(index.totalDocs).toBeGreaterThanOrEqual(690);
+  });
+
+  it("multiline description parsed correctly (brainstorming skill)", () => {
+    const brainstorming = index.entries.find((e) => e.dirName === "brainstorming");
+    expect(brainstorming).toBeDefined();
+    // Folded scalar should produce a single-line string
+    expect(brainstorming!.frontmatter.description).not.toContain("\n");
+    expect(brainstorming!.frontmatter.description).toContain("creative or constructive work");
+  });
+
+  it("skills with resources detected (expect ≥90)", () => {
+    const withResources = index.entries.filter((e) => e.hasResources);
+    expect(withResources.length).toBeGreaterThanOrEqual(90);
+  });
+
+  it("search returns relevant results for 'debugging'", () => {
+    const results = searchSkills(index, "debugging");
+    expect(results.length).toBeGreaterThan(0);
+    // At least one result should have "debug" in name or description
+    const hasDebug = results.some(
+      (r) => r.name.includes("debug") || r.description.toLowerCase().includes("debug"),
+    );
+    expect(hasDebug).toBe(true);
+  });
+
+  it("loadSkill loads a known skill (brainstorming)", async () => {
+    const entry = index.entries.find((e) => e.dirName === "brainstorming")!;
+    const content = await loadSkill(entry, skillsDir);
+    expect(content).toContain("**Skill directory**:");
+    expect(content).toContain("# Brainstorming");
+    expect(content).toContain("name: brainstorming");
+  });
+
+  it("loadSkill with resources loads hyphenated filenames (stride-analysis-patterns)", async () => {
+    const entry = index.entries.find((e) => e.dirName === "stride-analysis-patterns")!;
+    expect(entry.hasResources).toBe(true);
+    const content = await loadSkill(entry, skillsDir, true);
+    expect(content).toContain("# Resource: implementation-playbook.md");
+  });
+});
+
+describe("integration: search relevance", () => {
+  it("'react' returns React skills in top 5, not autonomous-agents first", () => {
+    const results = searchSkills(index, "react");
+    expect(results.length).toBeGreaterThan(0);
+    const top5 = results.slice(0, 5);
+    const hasReactSkill = top5.some(
+      (r) => r.dirName.includes("react") || r.name.toLowerCase().includes("react"),
+    );
+    expect(hasReactSkill).toBe(true);
+    // autonomous-agents should NOT be #1
+    expect(results[0].dirName).not.toBe("autonomous-agents");
+  });
+
+  it("'terraform' returns terraform skills in top 3", () => {
+    const results = searchSkills(index, "terraform");
+    expect(results.length).toBeGreaterThan(0);
+    const top3 = results.slice(0, 3);
+    const hasTerraform = top3.some(
+      (r) => r.dirName.includes("terraform") || r.name.toLowerCase().includes("terraform"),
+    );
+    expect(hasTerraform).toBe(true);
+  });
+
+  it("'build a REST API' returns backend/API skills in top 5", () => {
+    const results = searchSkills(index, "build a REST API");
+    expect(results.length).toBeGreaterThan(0);
+    const top5 = results.slice(0, 5);
+    const hasApiSkill = top5.some(
+      (r) => r.name.toLowerCase().includes("api") || r.description.toLowerCase().includes("api"),
+    );
+    expect(hasApiSkill).toBe(true);
+  });
+
+  it("'write tests' returns testing skills in top 5", () => {
+    const results = searchSkills(index, "write tests");
+    expect(results.length).toBeGreaterThan(0);
+    const top5 = results.slice(0, 5);
+    const hasTestSkill = top5.some(
+      (r) => r.name.toLowerCase().includes("test") || r.description.toLowerCase().includes("test"),
+    );
+    expect(hasTestSkill).toBe(true);
+  });
+
+  it("natural language query finds single-token skills (normalization fix)", () => {
+    // "help with brainstorming" should still find brainstorming
+    const results = searchSkills(index, "help with brainstorming");
+    const brainstorming = results.find((r) => r.dirName === "brainstorming");
+    expect(brainstorming).toBeDefined();
+  });
+
+  it("short acronym queries find matching skills (2-char substring)", () => {
+    // "ai" should find ai-engineer, ai-product, etc.
+    const results = searchSkills(index, "ai");
+    expect(results.length).toBeGreaterThan(0);
+    const hasAiSkill = results.some(
+      (r) => r.dirName.includes("ai-") || r.name.toLowerCase().includes("ai"),
+    );
+    expect(hasAiSkill).toBe(true);
+  });
+
+  it("every skill is findable by its own name", () => {
+    const unfindable: string[] = [];
+    for (const entry of index.entries) {
+      const results = searchSkills(index, entry.frontmatter.name);
+      const found = results.some((r) => r.dirName === entry.dirName);
+      if (!found) unfindable.push(entry.dirName);
+    }
+    expect(unfindable).toEqual([]);
+  });
+});

package/test/loader.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildIndex } from "../src/skill-index.js";
+import { loadSkill } from "../src/loader.js";
+import type { SearchIndex } from "../src/types.js";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const fixturesDir = join(__dirname, "fixtures");
+
+let index: SearchIndex;
+
+beforeAll(async () => {
+  index = await buildIndex(fixturesDir);
+});
+
+describe("loadSkill", () => {
+  it("loads SKILL.md content", async () => {
+    const entry = index.entries.find((e) => e.dirName === "basic-skill")!;
+    const content = await loadSkill(entry, fixturesDir);
+    expect(content).toContain("# Basic Skill");
+    expect(content).toContain("basic skill used for testing");
+  });
+
+  it("prepends absolute skill directory path", async () => {
+    const entry = index.entries.find((e) => e.dirName === "basic-skill")!;
+    const content = await loadSkill(entry, fixturesDir);
+    expect(content).toMatch(/^> \*\*Skill directory\*\*: .+basic-skill\n/);
+    expect(content).toContain("Resolve relative paths");
+  });
+
+  it("appends resources when includeResources=true", async () => {
+    const entry = index.entries.find((e) => e.dirName === "skill-with-resources")!;
+    const content = await loadSkill(entry, fixturesDir, true);
+    expect(content).toContain("# Skill With Resources");
+    expect(content).toContain("# Resource: examples.md");
+    expect(content).toContain("# Resource: guide.md");
+  });
+
+  it("resources sorted alphabetically", async () => {
+    const entry = index.entries.find((e) => e.dirName === "skill-with-resources")!;
+    const content = await loadSkill(entry, fixturesDir, true);
+    const examplesIdx = content.indexOf("# Resource: examples.md");
+    const guideIdx = content.indexOf("# Resource: guide.md");
+    // examples.md comes before guide.md alphabetically
+    expect(examplesIdx).toBeLessThan(guideIdx);
+  });
+
+  it("without resources flag, only SKILL.md returned", async () => {
+    const entry = index.entries.find((e) => e.dirName === "skill-with-resources")!;
+    const content = await loadSkill(entry, fixturesDir, false);
+    expect(content).toContain("# Skill With Resources");
+    expect(content).not.toContain("# Resource:");
+  });
+
+  it("resource sections have '# Resource: filename.md' headers", async () => {
+    const entry = index.entries.find((e) => e.dirName === "skill-with-resources")!;
+    const content = await loadSkill(entry, fixturesDir, true);
+    const resourceHeaders = content.match(/# Resource: [\w-]+\.md/g);
+    expect(resourceHeaders).toHaveLength(2);
+    expect(resourceHeaders).toContain("# Resource: examples.md");
+    expect(resourceHeaders).toContain("# Resource: guide.md");
+  });
+
+  it("loads hyphenated resource filenames correctly", async () => {
+    const entry = index.entries.find((e) => e.dirName === "skill-with-hyphenated-resources")!;
+    const content = await loadSkill(entry, fixturesDir, true);
+    expect(content).toContain("# Resource: implementation-playbook.md");
+    expect(content).toContain("# Resource: quick-start-guide.md");
+  });
+
+  it("resource sections separated by --- dividers", async () => {
+    const entry = index.entries.find((e) => e.dirName === "skill-with-hyphenated-resources")!;
+    const content = await loadSkill(entry, fixturesDir, true);
+    const dividers = content.match(/\n\n---\n\n# Resource:/g);
+    expect(dividers).toHaveLength(2);
+  });
+});