skillmesh-mcp 1.0.0 → 1.0.1

package/dist/index.js

@@ -6,6 +6,7 @@ import { z } from 'zod';
 import * as path from 'path';
 import * as os2 from 'os';
 import fs from 'fs-extra';
+import { spawnSync } from 'child_process';
 import * as yaml from 'js-yaml';
 
 var { existsSync } = fs;
@@ -308,93 +309,6 @@ async function createFolder(input) {
   }
 }
 
-// src/lib/tavily.ts
-async function searchTavily(query, maxResults = 10) {
-  const tavilyKey = process.env.TAVILY_API_KEY;
-  if (!tavilyKey) {
-    console.error("TAVILY_API_KEY not found in environment, trying Firecrawl fallback");
-    return searchFirecrawl(query, maxResults);
-  }
-  try {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), 15e3);
-    const response = await fetch("https://api.tavily.com/search", {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({
-        api_key: tavilyKey,
-        query,
-        max_results: maxResults,
-        search_depth: "basic",
-        include_answer: false,
-        include_images: false
-      }),
-      signal: controller.signal
-    });
-    clearTimeout(timeoutId);
-    if (!response.ok) {
-      console.error("Tavily API error:", response.status, response.statusText);
-      return [];
-    }
-    const data = await response.json();
-    if (!data.results || !Array.isArray(data.results)) {
-      return [];
-    }
-    return data.results.map((result) => ({
-      title: result.title || "",
-      url: result.url || "",
-      snippet: result.content || "",
-      score: result.score
-    }));
-  } catch (error) {
-    console.error("Tavily search failed:", error);
-    return [];
-  }
-}
-async function searchFirecrawl(query, maxResults = 10) {
-  const firecrawlKey = process.env.FIRECRAWL_API_KEY;
-  if (!firecrawlKey) {
-    console.error("Neither TAVILY_API_KEY nor FIRECRAWL_API_KEY found in environment");
-    return [];
-  }
-  try {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), 15e3);
-    const response = await fetch("https://api.firecrawl.dev/v1/search", {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${firecrawlKey}`
-      },
-      body: JSON.stringify({
-        query,
-        limit: maxResults
-      }),
-      signal: controller.signal
-    });
-    clearTimeout(timeoutId);
-    if (!response.ok) {
-      console.error("Firecrawl API error:", response.status, response.statusText);
-      return [];
-    }
-    const data = await response.json();
-    if (!data.data || !Array.isArray(data.data)) {
-      return [];
-    }
-    return data.data.map((result) => ({
-      title: result.title || "",
-      url: result.url || "",
-      snippet: result.description || result.content || "",
-      score: result.score
-    }));
-  } catch (error) {
-    console.error("Firecrawl search failed:", error);
-    return [];
-  }
-}
-
 // src/lib/github.ts
 async function fetchSkillFromGitHub(owner, repo, skillName, githubToken) {
   const baseUrl = `https://raw.githubusercontent.com/${owner}/${repo}/main`;
@@ -578,64 +492,43 @@ var SearchSkillsInputSchema = z.object({
 async function searchSkills(input) {
   try {
     const { keyword, minStars, maxAgeMonths, limit } = input;
-    const searchQuery = `site:skills.sh ${keyword}`;
-    const searchResults = await searchTavily(searchQuery, limit * 3);
-    const qualityResults = [];
     const githubToken = process.env.GITHUB_TOKEN;
-    for (const result of searchResults) {
-      const githubMatch = result.url.match(/github\.com\/([^\/]+)\/([^\/\?#]+)/);
-      if (!githubMatch) {
-        const pathMatch = result.url.match(/skills\.sh\/([^\/]+)\/([^\/\?#]+)/);
-        if (pathMatch) {
-          const [, owner2, repo2] = pathMatch;
-          try {
-            const stars = await getGitHubStars(owner2, repo2, githubToken);
-            const lastUpdated = await getLastUpdated(owner2, repo2, githubToken);
-            if (stars < minStars) continue;
-            if (lastUpdated) {
-              const ageMonths = (Date.now() - lastUpdated.getTime()) / (1e3 * 60 * 60 * 24 * 30);
-              if (ageMonths > maxAgeMonths) continue;
-            }
-            const recencyBonus = lastUpdated ? Math.max(0, 100 - (Date.now() - lastUpdated.getTime()) / (1e3 * 60 * 60 * 24 * 30)) : 0;
-            const score = stars + recencyBonus + (result.score || 0) * 10;
-            qualityResults.push({
-              name: repo2,
-              repo: repo2,
-              owner: owner2,
-              description: result.snippet,
-              stars,
-              lastUpdated: lastUpdated ? lastUpdated.toISOString() : "unknown",
-              url: result.url,
-              score
-            });
-          } catch (err) {
-            continue;
-          }
-        }
-        continue;
-      }
-      const [, owner, repo] = githubMatch;
+    let rawResults = await searchViaNpxSkillsFind(keyword);
+    if (rawResults.length === 0) {
+      rawResults = await searchViaSkillScout(keyword);
+    }
+    if (rawResults.length === 0) {
+      return {
+        success: true,
+        results: [],
+        query: keyword,
+        totalFound: 0
+      };
+    }
+    const qualityResults = [];
+    for (const result of rawResults) {
       try {
-        const stars = await getGitHubStars(owner, repo, githubToken);
-        const lastUpdated = await getLastUpdated(owner, repo, githubToken);
+        const stars = await getGitHubStars(result.owner, result.repo, githubToken);
+        const lastUpdated = await getLastUpdated(result.owner, result.repo, githubToken);
         if (stars < minStars) continue;
         if (lastUpdated) {
           const ageMonths = (Date.now() - lastUpdated.getTime()) / (1e3 * 60 * 60 * 24 * 30);
           if (ageMonths > maxAgeMonths) continue;
         }
         const recencyBonus = lastUpdated ? Math.max(0, 100 - (Date.now() - lastUpdated.getTime()) / (1e3 * 60 * 60 * 24 * 30)) : 0;
-        const score = stars + recencyBonus + (result.score || 0) * 10;
+        const score = stars + recencyBonus;
         qualityResults.push({
-          name: repo,
-          repo,
-          owner,
-          description: result.snippet,
+          name: result.skillName,
+          repo: result.repo,
+          owner: result.owner,
+          description: result.description || "",
           stars,
           lastUpdated: lastUpdated ? lastUpdated.toISOString() : "unknown",
-          url: result.url,
-          score
+          url: `https://github.com/${result.owner}/${result.repo}`,
+          score,
+          installRef: `${result.owner}/${result.repo}@${result.skillName}`
         });
-      } catch (err) {
+      } catch {
         continue;
       }
     }
@@ -658,6 +551,69 @@ async function searchSkills(input) {
     };
   }
 }
+async function searchViaNpxSkillsFind(keyword) {
+  try {
+    const result = spawnSync("npx", ["skills", "find", keyword], {
+      encoding: "utf-8",
+      timeout: 3e4,
+      // 30 second timeout
+      env: { ...process.env }
+    });
+    if (result.error || result.status !== 0) {
+      return [];
+    }
+    const output = result.stdout || "";
+    const results = [];
+    const lines = output.split("\n").filter((line) => line.trim());
+    for (const line of lines) {
+      const match = line.match(/^\s*([^\/\s]+)\/([^@\s]+)@([^\s-]+)(?:\s*-\s*(.*))?/);
+      if (match) {
+        const [, owner, repo, skillName, description] = match;
+        results.push({
+          owner,
+          repo,
+          skillName,
+          description: description?.trim()
+        });
+      }
+    }
+    return results;
+  } catch {
+    return [];
+  }
+}
+async function searchViaSkillScout(keyword) {
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 15e3);
+    const response = await fetch(
+      `https://api.skillscout.dev/v1/search?q=${encodeURIComponent(keyword)}`,
+      {
+        signal: controller.signal,
+        headers: {
+          "Accept": "application/json",
+          "User-Agent": "skillmesh-mcp/1.0.0"
+        }
+      }
+    );
+    clearTimeout(timeoutId);
+    if (!response.ok) {
+      return [];
+    }
+    const data = await response.json();
+    if (!data.results || !Array.isArray(data.results)) {
+      return [];
+    }
+    return data.results.filter((r) => r.owner && r.repo && (r.skill_name || r.name)).map((r) => ({
+      owner: r.owner,
+      repo: r.repo,
+      skillName: r.skill_name || r.name,
+      description: r.description
+    }));
+  } catch {
+    return [];
+  }
+}
 var SkillMetadataSchema = z.object({
   name: z.string().min(1, "Skill name is required"),
   description: z.string().min(1, "Description is required"),
@@ -783,15 +739,43 @@ function checkSkillQuality(parsed) {
 
 // src/tools/fetch-skill.ts
 var FetchSkillInputSchema = z.object({
-  owner: z.string().describe("GitHub repository owner"),
-  repo: z.string().describe("GitHub repository name"),
-  skillName: z.string().describe("Skill name to fetch"),
-  githubToken: z.string().optional().describe("Optional GitHub token for higher rate limits")
+  owner: z.string().optional().describe("GitHub repository owner"),
+  repo: z.string().optional().describe("GitHub repository name"),
+  skillName: z.string().optional().describe("Skill name to fetch"),
+  githubToken: z.string().optional().describe("Optional GitHub token for higher rate limits"),
+  /** Direct install reference in format owner/repo@skillname - if provided, parses owner/repo/skillName from it */
+  installRef: z.string().optional().describe("Install reference in format owner/repo@skillname")
 });
 async function fetchSkillContent(input) {
   try {
-    const { owner, repo, skillName, githubToken } = input;
+    let { owner, repo, skillName, githubToken, installRef } = input;
+    if (installRef) {
+      const match = installRef.match(/^([^\/]+)\/([^@]+)@(.+)$/);
+      if (match) {
+        owner = match[1];
+        repo = match[2];
+        skillName = match[3];
+      } else {
+        return {
+          success: false,
+          content: "",
+          sourceUrl: "",
+          found: false,
+          error: `Invalid installRef format: "${installRef}". Expected format: owner/repo@skillname`
+        };
+      }
+    }
+    if (!owner || !repo || !skillName) {
+      return {
+        success: false,
+        content: "",
+        sourceUrl: "",
+        found: false,
+        error: "Missing required fields: owner, repo, and skillName (or provide installRef)"
+      };
+    }
     const token = githubToken || process.env.GITHUB_TOKEN;
+    const resolvedInstallRef = `${owner}/${repo}@${skillName}`;
     const fetchResult = await fetchSkillFromGitHub(owner, repo, skillName, token);
     if (!fetchResult.found || !fetchResult.content) {
       return {
@@ -799,6 +783,7 @@ async function fetchSkillContent(input) {
         content: "",
         sourceUrl: fetchResult.url,
         found: false,
+        installRef: resolvedInstallRef,
         error: "SKILL.md not found in repository"
       };
     }
@@ -811,6 +796,7 @@ async function fetchSkillContent(input) {
           content: fetchResult.content,
           sourceUrl: fetchResult.url,
           found: true,
+          installRef: resolvedInstallRef,
           quality: {
             valid: false,
             issues: ["Failed to parse SKILL.md frontmatter"]
@@ -822,6 +808,7 @@ async function fetchSkillContent(input) {
         content: fetchResult.content,
         sourceUrl: fetchResult.url,
         found: true,
+        installRef: resolvedInstallRef,
         metadata: {
           name: parsed.metadata.name,
           description: parsed.metadata.description,
@@ -840,6 +827,7 @@ async function fetchSkillContent(input) {
         content: fetchResult.content,
         sourceUrl: fetchResult.url,
         found: true,
+        installRef: resolvedInstallRef,
         quality: {
           valid: false,
           issues: [`Failed to parse SKILL.md: ${parseMessage}`]
@@ -863,6 +851,93 @@ function sanitizeSkillName(name) {
   return name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
 }
 
+// src/lib/tavily.ts
+async function searchTavily(query, maxResults = 10) {
+  const tavilyKey = process.env.TAVILY_API_KEY;
+  if (!tavilyKey) {
+    console.error("TAVILY_API_KEY not found in environment, trying Firecrawl fallback");
+    return searchFirecrawl(query, maxResults);
+  }
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 15e3);
+    const response = await fetch("https://api.tavily.com/search", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        api_key: tavilyKey,
+        query,
+        max_results: maxResults,
+        search_depth: "basic",
+        include_answer: false,
+        include_images: false
+      }),
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (!response.ok) {
+      console.error("Tavily API error:", response.status, response.statusText);
+      return [];
+    }
+    const data = await response.json();
+    if (!data.results || !Array.isArray(data.results)) {
+      return [];
+    }
+    return data.results.map((result) => ({
+      title: result.title || "",
+      url: result.url || "",
+      snippet: result.content || "",
+      score: result.score
+    }));
+  } catch (error) {
+    console.error("Tavily search failed:", error);
+    return [];
+  }
+}
+async function searchFirecrawl(query, maxResults = 10) {
+  const firecrawlKey = process.env.FIRECRAWL_API_KEY;
+  if (!firecrawlKey) {
+    console.error("Neither TAVILY_API_KEY nor FIRECRAWL_API_KEY found in environment");
+    return [];
+  }
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 15e3);
+    const response = await fetch("https://api.firecrawl.dev/v1/search", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${firecrawlKey}`
+      },
+      body: JSON.stringify({
+        query,
+        limit: maxResults
+      }),
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (!response.ok) {
+      console.error("Firecrawl API error:", response.status, response.statusText);
+      return [];
+    }
+    const data = await response.json();
+    if (!data.data || !Array.isArray(data.data)) {
+      return [];
+    }
+    return data.data.map((result) => ({
+      title: result.title || "",
+      url: result.url || "",
+      snippet: result.description || result.content || "",
+      score: result.score
+    }));
+  } catch (error) {
+    console.error("Firecrawl search failed:", error);
+    return [];
+  }
+}
+
 // src/lib/llm.ts
 var PROVIDER_MODELS = {
   anthropic: "claude-sonnet-4-5-20250929",
@@ -1188,14 +1263,27 @@ var InstallSkillInputSchema = z.object({
     owner: z.string().optional().describe("GitHub owner (for type: github)"),
     repo: z.string().optional().describe("GitHub repo (for type: github)"),
     content: z.string().optional().describe("Direct SKILL.md content (for type: content)"),
-    stars: z.number().optional().describe("GitHub star count (for quality check)")
+    stars: z.number().optional().describe("GitHub star count (for quality check)"),
+    /** Direct install reference in format owner/repo@skillname - if provided, parses owner/repo from it */
+    installRef: z.string().optional().describe("Install reference in format owner/repo@skillname")
   }).describe("Skill source"),
   overwrite: z.boolean().optional().default(false).describe("Overwrite existing skill if present"),
-  global: z.boolean().optional().default(false).describe("Install to global scope")
+  global: z.boolean().optional().default(false).describe("Install to global scope"),
+  /** Rich project context for PATH C (LLM generation) - include framework versions, patterns, folder structure */
+  projectContext: z.string().optional().describe("Rich project context for skill generation (frameworks, versions, patterns, folder structure)")
 });
 async function installSkill(input) {
   try {
-    const { projectPath, skillName, agents, source, overwrite, global } = input;
+    const { projectPath, skillName, agents, source, overwrite, global, projectContext } = input;
+    let sourceOwner = source.owner;
+    let sourceRepo = source.repo;
+    if (source.installRef && source.type === "github") {
+      const match = source.installRef.match(/^([^\/]+)\/([^@]+)@(.+)$/);
+      if (match) {
+        sourceOwner = match[1];
+        sourceRepo = match[2];
+      }
+    }
     const sanitizedSkillName = sanitizeSkillName(skillName);
     if (!sanitizedSkillName || sanitizedSkillName.length === 0) {
       return {
@@ -1227,20 +1315,20 @@ async function installSkill(input) {
         };
       }
     }
-    if (source.type === "github" && source.owner && source.repo) {
+    if (source.type === "github" && sourceOwner && sourceRepo) {
       const stars = source.stars ?? 0;
       if (stars >= 50) {
-        return executePathA(source.owner, source.repo, sanitizedSkillName, agents, projectPath, global);
+        return executePathA(sourceOwner, sourceRepo, sanitizedSkillName, agents, projectPath, global);
       }
     }
     let skillContent = null;
     if (source.type === "content" && source.content) {
       skillContent = source.content;
-    } else if (source.type === "github" && source.owner && source.repo) {
+    } else if (source.type === "github" && sourceOwner && sourceRepo) {
       const githubToken = process.env.GITHUB_TOKEN;
       const fetchResult = await fetchSkillFromGitHub(
-        source.owner,
-        source.repo,
+        sourceOwner,
+        sourceRepo,
         sanitizedSkillName,
         githubToken
       );
@@ -1256,10 +1344,10 @@ async function installSkill(input) {
         projectPath,
         global,
         overwrite,
-        source.type === "github" ? `${source.owner}/${source.repo}` : "direct-content"
+        source.type === "github" ? `${sourceOwner}/${sourceRepo}` : "direct-content"
       );
     }
-    return await executePathC(skillName, sanitizedSkillName, agents, projectPath, global, overwrite);
+    return await executePathC(skillName, sanitizedSkillName, agents, projectPath, global, overwrite, projectContext);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return {
@@ -1273,8 +1361,7 @@ async function installSkill(input) {
 function executePathA(owner, repo, skillName, agents, projectPath, global) {
   const agentFlags = agents.map((agent) => `--agent ${agent}`).join(" ");
   const globalFlag = global ? "-g" : "";
-  const repoPath = `${owner}/${repo}`;
-  const command = `npx skills add ${repoPath} --skill ${skillName} ${agentFlags} ${globalFlag} -y`.trim().replace(/\s+/g, " ");
+  const command = `npx skills add ${owner}/${repo}@${skillName} ${agentFlags} ${globalFlag} -y`.trim().replace(/\s+/g, " ");
   const envNote = process.env.GITHUB_TOKEN ? "GITHUB_TOKEN is available in environment (higher rate limits)." : "Note: Set GITHUB_TOKEN environment variable for higher GitHub API rate limits.";
   const instruction = `Execute this command in your terminal now. The command will install the skill to all specified agents without any interactive prompts.
 
@@ -1358,9 +1445,9 @@ async function executePathB(content, skillName, agents, projectPath, global, ove
     error: allSucceeded ? void 0 : "Some installations failed. Check individual agent results."
   };
 }
-async function executePathC(originalSkillName, sanitizedSkillName, agents, projectPath, global, overwrite) {
+async function executePathC(originalSkillName, sanitizedSkillName, agents, projectPath, global, overwrite, providedContext) {
   try {
-    const projectContext = `Generating skill for: ${originalSkillName}
+    const projectContext = providedContext || `Generating skill for: ${originalSkillName}
 Project path: ${projectPath}
 Target agents: ${agents.join(", ")}`;
     const generateResult = await generateSkill({
@@ -1597,11 +1684,11 @@ A SKILL.md file that lives in your agent's skill directory. You read all SKILL.m
 
 2. create_skills_folder \u2014 Initializes skill directory structure for selected agents. Creates .claude/skills/, .cursor/skills/, etc. Also creates .skillmesh/skillmesh.config.json for tracking.
 
-3. search_skills \u2014 Searches skills.sh via Tavily for skills matching a keyword. Fetches GitHub star count and recency. Returns ranked list filtered by quality (stars >= 50, updated within 12 months).
+3. search_skills \u2014 Searches for skills using npx skills find (primary) with SkillScout.dev API fallback. Fetches GitHub star count and recency. Returns ranked list filtered by quality (stars >= 50, updated within 12 months). Each result includes an installRef field for direct use with install_skill.
 
-4. fetch_skill_content \u2014 Fetches full SKILL.md content from a GitHub repository using raw URL fallbacks. Validates YAML frontmatter. Returns content, source URL, and parsed metadata.
+4. fetch_skill_content \u2014 Fetches full SKILL.md content from a GitHub repository using raw URL fallbacks. Accepts either owner/repo/skillName OR installRef (format: owner/repo@skillname). Validates YAML frontmatter. Returns content, source URL, installRef, and parsed metadata.
 
-5. install_skill \u2014 Core installation tool. PATH A: returns npx skills add command string for you to execute via your bash tool. PATH B: writes SKILL.md directly to disk if npx fails. PATH C: calls generate_skill if both fail. Handles all selected agents simultaneously.
+5. install_skill \u2014 Core installation tool. Accepts source.installRef (format: owner/repo@skillname) OR source.owner/source.repo. Also accepts projectContext for PATH C generation. PATH A: returns npx skills add command string for you to execute via your bash tool. PATH B: writes SKILL.md directly to disk if npx fails. PATH C: calls generate_skill if both fail. Handles all selected agents simultaneously.
 
 6. generate_skill \u2014 LLM-powered skill generation. Searches web via Tavily for best practices, sends research + project context to LLM, generates a gold-standard SKILL.md. Only called when PATH A and B fail.
 
@@ -1666,8 +1753,9 @@ STEP 5: Install skills for each domain
 For each domain you identified:
 
 a. Call search_skills(domain)
-   - This searches skills.sh via Tavily
+   - This searches using npx skills find (primary) with SkillScout.dev fallback
    - Returns quality-filtered results (stars >= 50, updated within 12 months)
+   - Each result includes installRef field (format: owner/repo@skillname)
 
 b. If quality results found (stars >= 50):
    - Call fetch_skill_content for the top result
@@ -1675,7 +1763,7 @@ b. If quality results found (stars >= 50):
    - Call install_skill with source type 'github' and the owner/repo/stars data
    - install_skill returns a PATH A response: an npx command string
    - YOU MUST EXECUTE THIS COMMAND using your bash tool immediately
-   - Example command: npx skills add vercel-labs/next-skills --skill nextjs-patterns --agent claude-code --agent cursor -y
+   - Example command: npx skills add vercel-labs/next-skills@nextjs-patterns --agent claude-code --agent cursor -y
    - The command is fully non-interactive (no prompts) thanks to --agent flags and -y flag
 
 c. If no quality results OR PATH A fails:
@@ -1720,7 +1808,7 @@ PATH A (npx command \u2014 preferred):
 - Used for high-quality GitHub repos (stars >= 50)
 - install_skill returns an npx command string
 - YOU execute it using your bash tool
-- Command format: npx skills add <owner/repo> --skill <name> --agent <agent1> --agent <agent2> -y
+- Command format: npx skills add <owner/repo@skillname> --agent <agent1> --agent <agent2> -y
 - The npx CLI handles cloning, writing, and directory creation
 - Fully automated with zero interactive prompts
 
@@ -1747,10 +1835,10 @@ You:
 3. [Analyze project] \u2192 Next.js 15, App Router, TypeScript, Prisma, TailwindCSS
 4. [Derive domains] \u2192 nextjs-app-router-patterns, prisma-schema-design, tailwindcss-components
 5. For nextjs-app-router-patterns:
-   - [Call search_skills] \u2192 Found vercel-labs/next-skills (2,341 stars)
-   - [Call fetch_skill_content] \u2192 Retrieved SKILL.md
-   - [Call install_skill] \u2192 Returns npx command
-   - [Execute via bash] \u2192 npx skills add vercel-labs/next-skills --skill nextjs-app-router-patterns --agent claude-code --agent cursor -y
+   - [Call search_skills] \u2192 Found vercel-labs/next-skills (2,341 stars), installRef: vercel-labs/next-skills@nextjs-app-router-patterns
+   - [Call fetch_skill_content with installRef] \u2192 Retrieved SKILL.md
+   - [Call install_skill with source.installRef] \u2192 Returns npx command
+   - [Execute via bash] \u2192 npx skills add vercel-labs/next-skills@nextjs-app-router-patterns --agent claude-code --agent cursor -y
 6. [Repeat for other domains]
 7. [Call list_installed_skills] \u2192 Report summary table
 
@@ -1825,7 +1913,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "search_skills",
-        description: "Searches skills.sh via Tavily for skills matching a keyword. Fetches GitHub star count and recency. Returns ranked list filtered by quality (stars >= 50, updated within 12 months).",
+        description: "Searches for skills using npx skills find (primary) with SkillScout.dev API fallback. Fetches GitHub star count and recency. Returns ranked list filtered by quality (stars >= 50, updated within 12 months). Each result includes installRef field.",
         inputSchema: {
           type: "object",
           properties: {
@@ -1854,33 +1942,37 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "fetch_skill_content",
-        description: "Fetches full SKILL.md content from a GitHub repository using raw URL fallbacks. Validates YAML frontmatter. Returns content, source URL, and parsed metadata.",
+        description: "Fetches full SKILL.md content from a GitHub repository using raw URL fallbacks. Accepts either owner/repo/skillName OR installRef (format: owner/repo@skillname). Validates YAML frontmatter. Returns content, source URL, installRef, and parsed metadata.",
         inputSchema: {
           type: "object",
           properties: {
             owner: {
               type: "string",
-              description: "GitHub repository owner"
+              description: "GitHub repository owner (optional if installRef provided)"
             },
             repo: {
               type: "string",
-              description: "GitHub repository name"
+              description: "GitHub repository name (optional if installRef provided)"
             },
             skillName: {
               type: "string",
-              description: "Skill name to fetch"
+              description: "Skill name to fetch (optional if installRef provided)"
+            },
+            installRef: {
+              type: "string",
+              description: "Install reference in format owner/repo@skillname (alternative to owner/repo/skillName)"
             },
             githubToken: {
               type: "string",
               description: "Optional GitHub token for higher rate limits"
             }
           },
-          required: ["owner", "repo", "skillName"]
+          required: []
         }
       },
       {
         name: "install_skill",
-        description: "Core installation tool. PATH A: returns npx skills add command string for agent to execute. PATH B: writes SKILL.md directly to disk if npx fails. Handles all selected agents simultaneously.",
+        description: "Core installation tool. PATH A: returns npx skills add command string for agent to execute. PATH B: writes SKILL.md directly to disk if npx fails. PATH C: generates skill via LLM if both fail. Handles all selected agents simultaneously.",
         inputSchema: {
           type: "object",
           properties: {
@@ -1913,9 +2005,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                   type: "string",
                   description: "GitHub repo (for type: github)"
                 },
+                installRef: {
+                  type: "string",
+                  description: "Install reference in format owner/repo@skillname (alternative to owner/repo)"
+                },
                 content: {
                   type: "string",
                   description: "Direct SKILL.md content (for type: content)"
+                },
+                stars: {
+                  type: "number",
+                  description: "GitHub star count (for quality check, triggers PATH A if >= 50)"
                 }
               },
               required: ["type"],
@@ -1930,6 +2030,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: "boolean",
               description: "Install to global scope",
               default: false
+            },
+            projectContext: {
+              type: "string",
+              description: "Rich project context for PATH C skill generation (frameworks, versions, patterns, folder structure)"
             }
           },
           required: ["projectPath", "skillName", "agents", "source"]