skillsmp-mcp-lite 1.0.1 → 1.0.2

package/README.md

@@ -102,6 +102,17 @@ AI semantic search for skills using natural language.
 |-----------|------|----------|-------------|
 | `query` | string | Yes | Natural language description |
 
+### `skillsmp_install_and_read_skill`
+
+Install a skill from GitHub and immediately read its content.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `repo` | string | Yes | GitHub repository in 'owner/repo' format |
+| `skillName` | string | Yes | Name of the skill to read after installation |
+| `global` | boolean | No | Install globally to ~/.claude/skills/ (default: false) |
+| `universal` | boolean | No | Install to .agent/skills/ for universal usage (default: false) |
+
 ## Usage Examples
 
 Ask your AI assistant:
@@ -109,6 +120,24 @@ Ask your AI assistant:
 - "Search for PDF manipulation skills"
 - "Find skills for building a web scraper"
 - "What skills can help me with SEO optimization?"
+- "Install and load the python-code-review skill from existential-birds/beagle"
+
+## AGENTS.md Integration
+
+To enable automatic skill discovery, copy the content from [`AGENTS.example.md`](./AGENTS.example.md) and paste it at the top of your `AGENTS.md` file.
+
+### How It Works
+
+1. AI receives a complex task
+2. AI searches SkillsMP for relevant skills using `skillsmp_search_skills`
+3. If keyword search is insufficient, AI tries `skillsmp_ai_search_skills`
+4. If a relevant skill is found, AI installs and reads it with `skillsmp_install_and_read_skill`
+5. AI follows the skill's instructions to complete the task
+
+### Search Tips
+
+- **Keyword search**: Keep queries short (1-3 words). Example: `"code review"`, `"typescript"`, `"pdf"`
+- **Semantic search**: Use natural language. Example: `"how to build a landing page with React"`
 
 ## License
 

package/dist/schemas.d.ts

@@ -31,3 +31,20 @@ export declare const AISearchSchema: z.ZodObject<{
     query: string;
 }>;
 export type AISearchInput = z.infer<typeof AISearchSchema>;
+export declare const InstallAndReadSchema: z.ZodObject<{
+    repo: z.ZodString;
+    skillName: z.ZodString;
+    global: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    universal: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strict", z.ZodTypeAny, {
+    repo: string;
+    skillName: string;
+    global: boolean;
+    universal: boolean;
+}, {
+    repo: string;
+    skillName: string;
+    global?: boolean | undefined;
+    universal?: boolean | undefined;
+}>;
+export type InstallAndReadInput = z.infer<typeof InstallAndReadSchema>;

package/dist/schemas.js

@@ -36,3 +36,21 @@ export const AISearchSchema = z.object({
         .max(500, "Query must not exceed 500 characters")
         .describe("Natural language description of what you want to accomplish")
 }).strict();
+// Install and Read Skill Schema
+export const InstallAndReadSchema = z.object({
+    repo: z.string()
+        .min(1, "Repository is required")
+        .regex(/^[^/]+\/[^/]+$/, "Repository must be in 'owner/repo' format")
+        .describe("GitHub repository in 'owner/repo' format (e.g., 'existential-birds/beagle')"),
+    skillName: z.string()
+        .min(1, "Skill name is required")
+        .describe("Name of the skill to read after installation"),
+    global: z.boolean()
+        .optional()
+        .default(false)
+        .describe("Install globally to ~/.claude/skills/ (default: false, installs to project)"),
+    universal: z.boolean()
+        .optional()
+        .default(false)
+        .describe("Install to .agent/skills/ for universal AGENTS.md usage (default: false)")
+}).strict();

package/dist/tools/skills.js

@@ -1,5 +1,8 @@
+import { exec } from "child_process";
+import { promisify } from "util";
 import { makeApiRequest, handleApiError, validateSearchResponse, validateAISearchResponse } from "../api.js";
-import { KeywordSearchSchema, AISearchSchema } from "../schemas.js";
+import { KeywordSearchSchema, AISearchSchema, InstallAndReadSchema } from "../schemas.js";
+const execAsync = promisify(exec);
 /**
  * Register SkillsMP tools on the MCP server
  */
@@ -144,6 +147,115 @@ Examples:
             };
         }
     });
+    // Tool 3: Install and Read Skill
+    server.registerTool("skillsmp_install_and_read_skill", {
+        title: "Install and Read Skill",
+        description: `Install a skill from GitHub and immediately read its content.
+
+This tool first checks if the skill is already installed locally. If found, it skips installation and directly reads the content (faster). If not found, it installs from GitHub first.
+
+**IMPORTANT**: Use this to quickly load skill instructions without manual steps.
+
+Args:
+  - repo (string, required): GitHub repository in 'owner/repo' format
+  - skillName (string, required): Name of the skill to read after installation
+  - global (boolean, optional): Install globally to ~/.claude/skills/ (default: false)
+  - universal (boolean, optional): Install to .agent/skills/ for universal usage (default: false)
+
+Returns:
+  The full content of the skill's instructions (SKILL.md).
+
+Examples:
+  - repo: "existential-birds/beagle", skillName: "python-code-review"
+  - repo: "LA3D/skillhelper", skillName: "code-reviewer"`,
+        inputSchema: InstallAndReadSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true
+        }
+    }, async (params) => {
+        try {
+            const readCmd = `npx -y openskills read ${params.skillName}`;
+            // Step 1: Check if skill already exists locally
+            let skillExists = false;
+            try {
+                const { stdout } = await execAsync(readCmd, { timeout: 30000 });
+                if (stdout && !stdout.includes("not found") && !stdout.includes("Error")) {
+                    skillExists = true;
+                    const output = formatInstallAndReadResponse(params.repo, params.skillName, stdout, true);
+                    return {
+                        content: [{ type: "text", text: output }],
+                        structuredContent: {
+                            repo: params.repo,
+                            skillName: params.skillName,
+                            skillContent: stdout,
+                            wasAlreadyInstalled: true
+                        }
+                    };
+                }
+            }
+            catch {
+                // Skill not found locally, proceed with installation
+                skillExists = false;
+            }
+            // Step 2: Install if not exists
+            const installFlags = ["-y"];
+            if (params.global)
+                installFlags.push("--global");
+            if (params.universal)
+                installFlags.push("--universal");
+            const installCmd = `npx -y openskills install ${params.repo} ${installFlags.join(" ")}`;
+            let installOutput;
+            try {
+                const { stdout, stderr } = await execAsync(installCmd, { timeout: 120000 });
+                installOutput = stdout || stderr;
+            }
+            catch (installError) {
+                const error = installError;
+                return {
+                    content: [{
+                            type: "text",
+                            text: `❌ **Installation Failed**\n\nRepository: ${params.repo}\n\nError:\n${error.stderr || error.message || "Unknown error"}`
+                        }]
+                };
+            }
+            // Step 3: Read the skill after installation
+            let readOutput;
+            try {
+                const { stdout, stderr } = await execAsync(readCmd, { timeout: 30000 });
+                readOutput = stdout || stderr;
+            }
+            catch (readError) {
+                const error = readError;
+                return {
+                    content: [{
+                            type: "text",
+                            text: `✅ **Installation Succeeded** but **Read Failed**\n\nRepository: ${params.repo}\nSkill: ${params.skillName}\n\n**Install Output:**\n${installOutput}\n\n**Read Error:**\n${error.stderr || error.message || "Skill not found"}\n\n💡 **Tip**: Check if the skill name is correct. Use \`npx openskills list\` to see installed skills.`
+                        }]
+                };
+            }
+            const output = formatInstallAndReadResponse(params.repo, params.skillName, readOutput, false);
+            return {
+                content: [{ type: "text", text: output }],
+                structuredContent: {
+                    repo: params.repo,
+                    skillName: params.skillName,
+                    skillContent: readOutput,
+                    wasAlreadyInstalled: false
+                }
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `❌ **Error**: ${error instanceof Error ? error.message : "An unexpected error occurred"}`
+                    }]
+            };
+        }
+    });
 }
 /**
  * Render a single skill as markdown lines
@@ -205,6 +317,24 @@ function formatAISearchResponse(skills, query) {
         ""
     ];
     skills.forEach((skill, i) => lines.push(...renderSkill(skill, i)));
-    lines.push("💡 **Tip**: Use `npx openskills read <skill-name>` to load a skill's detailed instructions.");
+    lines.push("💡 **Tip**: Use `skillsmp_install_and_read_skill` to install and load a skill's instructions.");
+    return lines.join("\n");
+}
+/**
+ * Format install and read response as markdown
+ */
+function formatInstallAndReadResponse(repo, skillName, skillContent, wasAlreadyInstalled) {
+    const statusIcon = wasAlreadyInstalled ? "📖" : "📦";
+    const statusText = wasAlreadyInstalled ? "Skill Loaded (already installed)" : "Skill Installed & Loaded";
+    const lines = [
+        `# ${statusIcon} ${statusText}: ${skillName}`,
+        "",
+        `**Repository**: ${repo}`,
+        wasAlreadyInstalled ? "**Status**: ⚡ Loaded from local cache (skipped installation)" : "**Status**: ✅ Freshly installed",
+        "",
+        "---",
+        "",
+        skillContent
+    ];
     return lines.join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillsmp-mcp-lite",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Lightweight MCP server for searching AI skills from SkillsMP before starting any task",
   "type": "module",
   "main": "dist/index.js",