@skilljack/mcp 0.3.0 → 0.4.0

package/README.md

@@ -9,9 +9,22 @@ An MCP server that jacks [Agent Skills](https://agentskills.io) directly into yo
 - **Dynamic Skill Discovery** - Watches skill directories and automatically refreshes when skills change
 - **Tool List Changed Notifications** - Sends `tools/listChanged` so clients can refresh available skills
 - **Skill Tool** - Load full skill content on demand (progressive disclosure)
+- **MCP Prompts** - Load skills via `/skill` prompt with auto-completion or per-skill prompts
 - **MCP Resources** - Access skills via `skill://` URIs with batch collection support
 - **Resource Subscriptions** - Real-time file watching with `notifications/resources/updated`
 
+## Motivation
+
+This repo demonstrates a way to approach integrating skills using existing MCP primitives.
+
+MCP already has the building blocks:
+- **Tools** for on-demand skill loading (the `skill` tool with dynamically updated descriptions)
+- **Resources** for explicit skill access (`skill://` URIs)
+- **Notifications** for real-time updates (`tools/listChanged`, `resources/updated`)
+- **Prompts** for explicitly invoking skills by name (`/my-server-skill`)
+
+This approach provides separation of concerns.  Rather than every MCP server needing to embed skill handling, the server acts as a dedicated 'skill gateway'. Server authors can bundle skills alongside their MCP servers without modifying the servers themselves. If MCP registries support robust tool discovery, skill tools become discoverable like any other tool.
+
 ## Installation
 
 ```bash
@@ -75,16 +88,20 @@ The server implements the [Agent Skills](https://agentskills.io) progressive dis
 │   ↓                                                      │
 │ MCP Client connects                                      │
 │   • Skill tool description includes available skills     │
+│   • Prompts registered for each skill                    │
 │   ↓                                                      │
 │ LLM sees skill metadata in tool description              │
 │   ↓                                                      │
 │ SKILL.md added/modified/removed                          │
 │   • Server re-discovers skills                           │
 │   • Updates skill tool description                       │
+│   • Updates prompt list (add/remove/modify)              │
 │   • Sends tools/listChanged notification                 │
-│   • Client refreshes tool definitions                    │
+│   • Sends prompts/listChanged notification               │
+│   • Client refreshes tool and prompt definitions         │
 │   ↓                                                      │
-│ LLM calls "skill" tool with skill name                   │
+│ User invokes /skill prompt or /skill-name prompt         │
+│   OR LLM calls "skill" tool with skill name              │
 │   ↓                                                      │
 │ Server returns full SKILL.md content                     │
 │   ↓                                                      │
@@ -93,14 +110,41 @@ The server implements the [Agent Skills](https://agentskills.io) progressive dis
 └─────────────────────────────────────────────────────────┘
 ```
 
-## Tools vs Resources
+## Tools vs Resources vs Prompts
 
-This server exposes skills via both **tools** and **resources**:
+This server exposes skills via **tools**, **resources**, and **prompts**:
 
 - **Tools** (`skill`, `skill-resource`) - For your agent to use autonomously. The LLM sees available skills in the tool description and calls them as needed.
+- **Prompts** (`/skill`, `/skill-name`) - For explicit user invocation. Use `/skill` with auto-completion or select a skill directly by name.
 - **Resources** (`skill://` URIs) - For manual selection in apps that support it (e.g., Claude Desktop's resource picker). Useful when you want to explicitly attach a skill to the conversation.
 
-Most users will rely on tools for automatic skill activation. Resources provide an alternative for manual control.
+Most users will rely on tools for automatic skill activation. Prompts provide user-initiated loading with auto-completion. Resources provide an alternative for manual control.
+
+## Progressive Disclosure Design
+
+This server implements the [Agent Skills progressive disclosure pattern](https://agentskills.io/specification#progressive-disclosure), which structures skills for efficient context usage:
+
+| Level | Tokens | What's loaded | When |
+|-------|--------|---------------|------|
+| **Metadata** | ~100 | `name` and `description` | At startup, for all skills |
+| **Instructions** | < 5000 | Full SKILL.md body | When skill is activated |
+| **Resources** | As needed | Files in `scripts/`, `references/`, `assets/` | On demand via `skill-resource` |
+
+### How it works
+
+1. **Discovery** - Server loads metadata from all skills into the `skill` tool description
+2. **Activation** - When a skill is loaded (via tool, prompt, or resource), only the SKILL.md content is returned
+3. **Execution** - SKILL.md references additional files; agent fetches them with `skill-resource` as needed
+
+### Why SKILL.md documents its own resources
+
+The server doesn't automatically list all files in a skill directory. Instead, skill authors document available resources directly in their SKILL.md (e.g., "Copy the template from `templates/server.ts`"). This design choice follows the spec because:
+
+- **Skill authors know best** - They decide which files are relevant and when to use them
+- **Context efficiency** - Loading everything upfront wastes tokens on files the agent may not need
+- **Natural flow** - SKILL.md guides the agent through resources in a logical order
+
+**For skill authors:** Reference files using relative paths from the skill root (e.g., `snippets/tool.ts`, `references/api.md`). Keep your main SKILL.md under 500 lines; move detailed reference material to separate files. See the [Agent Skills specification](https://agentskills.io/specification) for complete authoring guidelines.
 
 ## Tools
 
@@ -150,6 +194,38 @@ Returns all files in the directory as multiple content items.
 
 **Security:** Path traversal is prevented - only files within the skill directory can be accessed.
 
+## Prompts
+
+Skills can be loaded via MCP [Prompts](https://modelcontextprotocol.io/specification/2025-11-05/server/prompts) for explicit user invocation.
+
+### `/skill` Prompt
+
+Load a skill by name with auto-completion support.
+
+**Arguments:**
+- `name` (string, required) - Skill name with auto-completion
+
+The prompt description includes all available skills for discoverability. As you type the skill name, matching skills are suggested.
+
+### Per-Skill Prompts
+
+Each discovered skill is also registered as its own prompt (e.g., `/mcp-server-ts`, `/algorithmic-art`).
+
+- No arguments needed - just select and invoke
+- Description shows the skill's own description
+- List updates dynamically as skills change
+
+**Example:** If you have a skill named `mcp-server-ts`, you can invoke it directly as `/mcp-server-ts`.
+
+### Content Annotations
+
+Prompt responses include MCP [content annotations](https://modelcontextprotocol.io/specification/2025-11-25/server/prompts#embedded-resources) for proper handling:
+
+- `audience: ["assistant"]` - Content is intended for the LLM, not the user
+- `priority: 1.0` - High priority content that should be included in context
+
+Prompts return embedded resources with the skill's `skill://` URI, allowing clients to track the content source.
+
 ## Resources
 
 Skills are also accessible via MCP [Resources](https://modelcontextprotocol.io/specification/2025-11-25/server/resources#resources) using `skill://` URIs.
@@ -160,7 +236,8 @@ Skills are also accessible via MCP [Resources](https://modelcontextprotocol.io/s
 |-----|---------|
 | `skill://{name}` | Single skill's SKILL.md content |
 | `skill://{name}/` | All files in skill directory (collection) |
-| `skill://{name}/{path}` | Specific file within skill |
+
+Individual file URIs (`skill://{name}/{path}`) are not listed as resources to reduce noise. Use the `skill-resource` tool to fetch specific files on demand.
 
 ### Resource Subscriptions
 
@@ -211,8 +288,9 @@ The server watches skill directories for changes. When SKILL.md files are added,
 
 1. Skills are re-discovered from all configured directories
 2. The `skill` tool's description is updated with current skill names and metadata
-3. `tools/listChanged` notification is sent to connected clients
-4. Clients that support this notification will refresh tool definitions
+3. Per-skill prompts are added, removed, or updated accordingly
+4. `tools/listChanged` and `prompts/listChanged` notifications are sent to connected clients
+5. Clients that support these notifications will refresh tool and prompt definitions
 
 ## Skill Metadata Format
 

package/dist/index.js

@@ -18,6 +18,7 @@ import * as path from "node:path";
 import { discoverSkills, createSkillMap } from "./skill-discovery.js";
 import { registerSkillTool, getToolDescription } from "./skill-tool.js";
 import { registerSkillResources } from "./skill-resources.js";
+import { registerSkillPrompts, refreshPrompts } from "./skill-prompts.js";
 import { createSubscriptionManager, registerSubscriptionHandlers, refreshSubscriptions, } from "./subscriptions.js";
 /**
  * Subdirectories to check for skills within the configured directory.
@@ -114,9 +115,10 @@ const SKILL_REFRESH_DEBOUNCE_MS = 500;
  * @param skillsDirs - The configured skill directories
  * @param server - The MCP server instance
  * @param skillTool - The registered skill tool to update
+ * @param promptRegistry - For refreshing skill prompts
  * @param subscriptionManager - For refreshing resource subscriptions
  */
-function refreshSkills(skillsDirs, server, skillTool, subscriptionManager) {
+function refreshSkills(skillsDirs, server, skillTool, promptRegistry, subscriptionManager) {
     console.error("Refreshing skills...");
     // Re-discover all skills
     const skills = discoverSkillsFromDirs(skillsDirs);
@@ -128,6 +130,8 @@ function refreshSkills(skillsDirs, server, skillTool, subscriptionManager) {
     skillTool.update({
         description: getToolDescription(skillState),
     });
+    // Refresh prompts to match new skill state
+    refreshPrompts(server, skillState, promptRegistry);
     // Refresh resource subscriptions to match new skill state
     refreshSubscriptions(subscriptionManager, skillState, (uri) => {
         server.server.notification({
@@ -148,9 +152,10 @@ function refreshSkills(skillsDirs, server, skillTool, subscriptionManager) {
  * @param skillsDirs - The configured skill directories
  * @param server - The MCP server instance
  * @param skillTool - The registered skill tool to update
+ * @param promptRegistry - For refreshing skill prompts
  * @param subscriptionManager - For refreshing subscriptions
  */
-function watchSkillDirectories(skillsDirs, server, skillTool, subscriptionManager) {
+function watchSkillDirectories(skillsDirs, server, skillTool, promptRegistry, subscriptionManager) {
     let refreshTimeout = null;
     const debouncedRefresh = () => {
         if (refreshTimeout) {
@@ -158,7 +163,7 @@ function watchSkillDirectories(skillsDirs, server, skillTool, subscriptionManage
         }
         refreshTimeout = setTimeout(() => {
             refreshTimeout = null;
-            refreshSkills(skillsDirs, server, skillTool, subscriptionManager);
+            refreshSkills(skillsDirs, server, skillTool, promptRegistry, subscriptionManager);
         }, SKILL_REFRESH_DEBOUNCE_MS);
     };
     // Build list of paths to watch
@@ -251,15 +256,17 @@ async function main() {
         capabilities: {
             tools: { listChanged: true },
             resources: { subscribe: true, listChanged: true },
+            prompts: { listChanged: true },
         },
     });
-    // Register tools and resources
+    // Register tools, resources, and prompts
     const skillTool = registerSkillTool(server, skillState);
     registerSkillResources(server, skillState);
+    const promptRegistry = registerSkillPrompts(server, skillState);
     // Register subscription handlers for resource file watching
     registerSubscriptionHandlers(server, skillState, subscriptionManager);
     // Set up file watchers for skill directory changes
-    watchSkillDirectories(skillsDirs, server, skillTool, subscriptionManager);
+    watchSkillDirectories(skillsDirs, server, skillTool, promptRegistry, subscriptionManager);
     // Connect via stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/skill-prompts.d.ts

@@ -0,0 +1,47 @@
+/**
+ * MCP prompt registration for skill loading.
+ *
+ * Provides two patterns for loading skills:
+ * 1. /skill prompt - Single prompt with name argument + auto-completion
+ * 2. Per-skill prompts - Dynamic prompts for each skill (e.g., /mcp-server-ts)
+ */
+import { McpServer, RegisteredPrompt } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SkillState } from "./skill-tool.js";
+/**
+ * Track all registered prompts for dynamic updates.
+ */
+export interface PromptRegistry {
+    skillPrompt: RegisteredPrompt;
+    perSkillPrompts: Map<string, RegisteredPrompt>;
+}
+/**
+ * Generate the description for the /skill prompt.
+ * Includes available skills list for discoverability.
+ */
+export declare function getPromptDescription(skillState: SkillState): string;
+/**
+ * Register skill prompts with the MCP server.
+ *
+ * Creates:
+ * 1. /skill prompt with name argument + auto-completion
+ * 2. Per-skill prompts for each discovered skill
+ *
+ * @param server - The McpServer instance
+ * @param skillState - Shared state object (allows dynamic updates)
+ * @returns Registry for tracking and updating prompts
+ */
+export declare function registerSkillPrompts(server: McpServer, skillState: SkillState): PromptRegistry;
+/**
+ * Refresh prompts when skills change.
+ *
+ * Updates:
+ * - /skill prompt description with new skill list
+ * - Disables prompts for removed skills
+ * - Adds prompts for new skills
+ * - Updates descriptions for modified skills
+ *
+ * @param server - The McpServer instance
+ * @param skillState - Updated skill state
+ * @param registry - Prompt registry to update
+ */
+export declare function refreshPrompts(server: McpServer, skillState: SkillState, registry: PromptRegistry): void;

package/dist/skill-prompts.js

@@ -0,0 +1,236 @@
+/**
+ * MCP prompt registration for skill loading.
+ *
+ * Provides two patterns for loading skills:
+ * 1. /skill prompt - Single prompt with name argument + auto-completion
+ * 2. Per-skill prompts - Dynamic prompts for each skill (e.g., /mcp-server-ts)
+ */
+import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
+import { z } from "zod";
+import { loadSkillContent, generateInstructions } from "./skill-discovery.js";
+/**
+ * Auto-completion for /skill prompt name argument.
+ * Returns skill names that start with the given value (case-insensitive).
+ */
+function getSkillNameCompletions(value, skillState) {
+    const names = Array.from(skillState.skillMap.keys());
+    return names.filter((name) => name.toLowerCase().startsWith(value.toLowerCase()));
+}
+/**
+ * Generate the description for the /skill prompt.
+ * Includes available skills list for discoverability.
+ */
+export function getPromptDescription(skillState) {
+    const skills = Array.from(skillState.skillMap.values());
+    const usage = "Load a skill by name with auto-completion.\n\n";
+    return usage + generateInstructions(skills);
+}
+/**
+ * Register skill prompts with the MCP server.
+ *
+ * Creates:
+ * 1. /skill prompt with name argument + auto-completion
+ * 2. Per-skill prompts for each discovered skill
+ *
+ * @param server - The McpServer instance
+ * @param skillState - Shared state object (allows dynamic updates)
+ * @returns Registry for tracking and updating prompts
+ */
+export function registerSkillPrompts(server, skillState) {
+    // 1. Register /skill prompt with argument + auto-completion
+    const skillPrompt = server.registerPrompt("skill", {
+        title: "Load Skill",
+        description: getPromptDescription(skillState),
+        argsSchema: {
+            name: completable(z.string().describe("Skill name"), (value) => getSkillNameCompletions(value, skillState)),
+        },
+    }, async ({ name }) => {
+        const skill = skillState.skillMap.get(name);
+        if (!skill) {
+            const availableSkills = Array.from(skillState.skillMap.keys()).join(", ");
+            return {
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: `Skill "${name}" not found. Available skills: ${availableSkills || "none"}`,
+                        },
+                    },
+                ],
+            };
+        }
+        try {
+            const content = loadSkillContent(skill.path);
+            return {
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "resource",
+                            resource: {
+                                uri: `skill://${name}`,
+                                mimeType: "text/markdown",
+                                text: content,
+                            },
+                            annotations: {
+                                audience: ["assistant"],
+                                priority: 1.0,
+                            },
+                        },
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: `Failed to load skill "${name}": ${message}`,
+                        },
+                    },
+                ],
+            };
+        }
+    });
+    // 2. Register per-skill prompts (no arguments needed)
+    // Returns embedded resource with skill:// URI (MCP-idiomatic)
+    const perSkillPrompts = new Map();
+    for (const [name, skill] of skillState.skillMap) {
+        // Capture skill info in closure for this specific prompt
+        const skillPath = skill.path;
+        const skillName = name;
+        const prompt = server.registerPrompt(name, {
+            title: skill.name,
+            description: skill.description,
+            // No argsSchema - direct invocation
+        }, async () => {
+            try {
+                const content = loadSkillContent(skillPath);
+                return {
+                    messages: [
+                        {
+                            role: "user",
+                            content: {
+                                type: "resource",
+                                resource: {
+                                    uri: `skill://${skillName}`,
+                                    mimeType: "text/markdown",
+                                    text: content,
+                                },
+                                annotations: {
+                                    audience: ["assistant"],
+                                    priority: 1.0,
+                                },
+                            },
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    messages: [
+                        {
+                            role: "user",
+                            content: {
+                                type: "text",
+                                text: `Failed to load skill "${skillName}": ${message}`,
+                            },
+                        },
+                    ],
+                };
+            }
+        });
+        perSkillPrompts.set(name, prompt);
+    }
+    return { skillPrompt, perSkillPrompts };
+}
+/**
+ * Refresh prompts when skills change.
+ *
+ * Updates:
+ * - /skill prompt description with new skill list
+ * - Disables prompts for removed skills
+ * - Adds prompts for new skills
+ * - Updates descriptions for modified skills
+ *
+ * @param server - The McpServer instance
+ * @param skillState - Updated skill state
+ * @param registry - Prompt registry to update
+ */
+export function refreshPrompts(server, skillState, registry) {
+    // Update /skill prompt description with new skill list
+    registry.skillPrompt.update({
+        description: getPromptDescription(skillState),
+    });
+    // Disable removed skill prompts
+    for (const [name, prompt] of registry.perSkillPrompts) {
+        if (!skillState.skillMap.has(name)) {
+            prompt.update({ enabled: false });
+            registry.perSkillPrompts.delete(name);
+        }
+    }
+    // Add/update per-skill prompts
+    for (const [name, skill] of skillState.skillMap) {
+        if (registry.perSkillPrompts.has(name)) {
+            // Update existing prompt description
+            registry.perSkillPrompts.get(name).update({
+                description: skill.description,
+            });
+        }
+        else {
+            // Register new skill prompt with embedded resource
+            const skillPath = skill.path;
+            const skillName = name;
+            const prompt = server.registerPrompt(name, {
+                title: skill.name,
+                description: skill.description,
+            }, async () => {
+                try {
+                    const content = loadSkillContent(skillPath);
+                    return {
+                        messages: [
+                            {
+                                role: "user",
+                                content: {
+                                    type: "resource",
+                                    resource: {
+                                        uri: `skill://${skillName}`,
+                                        mimeType: "text/markdown",
+                                        text: content,
+                                    },
+                                    annotations: {
+                                        audience: ["assistant"],
+                                        priority: 1.0,
+                                    },
+                                },
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    return {
+                        messages: [
+                            {
+                                role: "user",
+                                content: {
+                                    type: "text",
+                                    text: `Failed to load skill "${skillName}": ${message}`,
+                                },
+                            },
+                        ],
+                    };
+                }
+            });
+            registry.perSkillPrompts.set(name, prompt);
+        }
+    }
+    // Notify clients that prompts have changed
+    server.sendPromptListChanged();
+}

package/dist/skill-resources.d.ts

@@ -8,9 +8,12 @@
  * skill updates when MCP roots change.
  *
  * URI Scheme:
- *   skill://{skillName}         -> SKILL.md content (template)
- *   skill://{skillName}/        -> Collection: all files in skill directory
- *   skill://{skillName}/{path}  -> File within skill directory (template)
+ *   skill://{skillName}   -> SKILL.md content (template)
+ *   skill://{skillName}/  -> Collection: all files in skill directory
+ *
+ * Note: Individual file URIs (skill://{skillName}/{path}) are not listed
+ * as resources to reduce noise. Use the skill-resource tool to fetch
+ * specific files on demand.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { SkillState } from "./skill-tool.js";

package/dist/skill-resources.js

@@ -8,9 +8,12 @@
  * skill updates when MCP roots change.
  *
  * URI Scheme:
- *   skill://{skillName}         -> SKILL.md content (template)
- *   skill://{skillName}/        -> Collection: all files in skill directory
- *   skill://{skillName}/{path}  -> File within skill directory (template)
+ *   skill://{skillName}   -> SKILL.md content (template)
+ *   skill://{skillName}/  -> Collection: all files in skill directory
+ *
+ * Note: Individual file URIs (skill://{skillName}/{path}) are not listed
+ * as resources to reduce noise. Use the skill-resource tool to fetch
+ * specific files on demand.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -50,10 +53,11 @@ function getMimeType(filePath) {
 export function registerSkillResources(server, skillState) {
     // Register template for individual skill SKILL.md files
     registerSkillTemplate(server, skillState);
-    // Register collection resource for skill directories (must be before file template)
+    // Register collection resource for skill directories
     registerSkillDirectoryCollection(server, skillState);
-    // Register resource template for skill files
-    registerSkillFileTemplate(server, skillState);
+    // Note: Individual file resources (skill://{name}/{path}) are intentionally
+    // not registered to reduce noise. Use the skill-resource tool to fetch
+    // specific files on demand.
 }
 /**
  * Register a collection resource for skill directories.
@@ -196,91 +200,3 @@ function registerSkillTemplate(server, skillState) {
         }
     });
 }
-/**
- * Register the resource template for accessing files within skills.
- *
- * URI Pattern: skill://{skillName}/{filePath}
- */
-function registerSkillFileTemplate(server, skillState) {
-    server.registerResource("Skill File", new ResourceTemplate("skill://{skillName}/{+filePath}", {
-        list: async () => {
-            // Return all listable skill files (dynamic based on current skillMap)
-            const resources = [];
-            for (const [name, skill] of skillState.skillMap) {
-                const skillDir = path.dirname(skill.path);
-                const files = listSkillFiles(skillDir);
-                for (const file of files) {
-                    const uri = `skill://${encodeURIComponent(name)}/${file}`;
-                    resources.push({
-                        uri,
-                        name: `${name}/${file}`,
-                        mimeType: getMimeType(file),
-                    });
-                }
-            }
-            return { resources };
-        },
-        complete: {
-            skillName: (value) => {
-                const names = Array.from(skillState.skillMap.keys());
-                return names.filter((name) => name.toLowerCase().startsWith(value.toLowerCase()));
-            },
-        },
-    }), {
-        mimeType: "text/plain",
-        description: "Files within a skill directory (scripts, snippets, assets, etc.)",
-    }, async (resourceUri, variables) => {
-        // Extract skill name and file path from URI
-        const uriStr = resourceUri.toString();
-        const match = uriStr.match(/^skill:\/\/([^/]+)\/(.+)$/);
-        if (!match) {
-            throw new Error(`Invalid skill file URI: ${uriStr}`);
-        }
-        const skillName = decodeURIComponent(match[1]);
-        const filePath = match[2];
-        const skill = skillState.skillMap.get(skillName);
-        if (!skill) {
-            const available = Array.from(skillState.skillMap.keys()).join(", ");
-            throw new Error(`Skill "${skillName}" not found. Available: ${available || "none"}`);
-        }
-        const skillDir = path.dirname(skill.path);
-        const fullPath = path.resolve(skillDir, filePath);
-        // Security: Validate path is within skill directory
-        if (!isPathWithinBase(fullPath, skillDir)) {
-            throw new Error(`Path "${filePath}" is outside the skill directory`);
-        }
-        // Check file exists
-        if (!fs.existsSync(fullPath)) {
-            const files = listSkillFiles(skillDir).slice(0, 10);
-            throw new Error(`File "${filePath}" not found in skill "${skillName}". ` +
-                `Available: ${files.join(", ")}${files.length >= 10 ? "..." : ""}`);
-        }
-        const stat = fs.statSync(fullPath);
-        // Reject symlinks
-        if (stat.isSymbolicLink()) {
-            throw new Error(`Cannot read symlink "${filePath}"`);
-        }
-        // Reject directories
-        if (stat.isDirectory()) {
-            const files = listSkillFiles(skillDir, filePath);
-            throw new Error(`"${filePath}" is a directory. Files within: ${files.join(", ")}`);
-        }
-        // Check file size
-        if (stat.size > MAX_FILE_SIZE) {
-            const sizeMB = (stat.size / 1024 / 1024).toFixed(2);
-            throw new Error(`File too large (${sizeMB}MB). Maximum: 10MB`);
-        }
-        // Read and return content
-        const content = fs.readFileSync(fullPath, "utf-8");
-        const mimeType = getMimeType(fullPath);
-        return {
-            contents: [
-                {
-                    uri: uriStr,
-                    mimeType,
-                    text: content,
-                },
-            ],
-        };
-    });
-}

package/dist/subscriptions.d.ts

@@ -9,7 +9,7 @@
  * - skill://              → Watch all skill directories
  * - skill://{name}        → Watch that skill's SKILL.md
  * - skill://{name}/       → Watch entire skill directory (directory collection)
- * - skill://{name}/{path} → Watch specific file
+ * - skill://{name}/{path} → Watch specific file (subscribable but not listed as resource)
  */
 import { FSWatcher } from "chokidar";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/dist/subscriptions.js

@@ -9,7 +9,7 @@
  * - skill://              → Watch all skill directories
  * - skill://{name}        → Watch that skill's SKILL.md
  * - skill://{name}/       → Watch entire skill directory (directory collection)
- * - skill://{name}/{path} → Watch specific file
+ * - skill://{name}/{path} → Watch specific file (subscribable but not listed as resource)
  */
 import chokidar from "chokidar";
 import * as path from "node:path";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilljack/mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "MCP server that discovers and serves Agent Skills. I know kung fu.",
   "type": "module",
   "main": "dist/index.js",

package/dist/roots-handler.d.ts

@@ -1,49 +0,0 @@
-/**
- * MCP Roots handler for dynamic skill discovery.
- *
- * Requests roots from the client, scans for skills in each root,
- * and handles root change notifications.
- *
- * Pattern adapted from:
- * - .claude/skills/mcp-server-ts/snippets/server/index.ts (oninitialized, syncRoots)
- * - .claude/skills/mcp-client-ts/snippets/handlers/roots.ts (URI conversion)
- */
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { SkillMetadata } from "./skill-discovery.js";
-/**
- * Skill discovery locations within each root.
- */
-export declare const SKILL_SUBDIRS: string[];
-/**
- * Discover skills from all roots provided by the client.
- *
- * Scans each root for skill directories (.claude/skills/, skills/)
- * and handles naming conflicts by prefixing with root name.
- *
- * @param roots - Array of Root objects from client's roots/list response
- * @returns Object containing discovered skills
- */
-export declare function discoverSkillsFromRoots(roots: Array<{
-    uri: string;
-    name?: string;
-}>): {
-    skills: SkillMetadata[];
-    rootSources: Map<string, string>;
-};
-/**
- * Callback type for when skills are updated.
- */
-export type SkillsChangedCallback = (skillMap: Map<string, SkillMetadata>, instructions: string) => void;
-/**
- * Sync skills from roots or configured skills directory.
- *
- * Pattern from mcp-server-ts snippets/server/index.ts:
- * - Check client capabilities
- * - Request roots if supported
- * - Use skills directory if not
- *
- * @param server - The McpServer instance
- * @param skillsDir - Optional skills directory if client doesn't support roots
- * @param onSkillsChanged - Callback when skills are updated
- */
-export declare function syncSkills(server: McpServer, skillsDir: string | null, onSkillsChanged: SkillsChangedCallback): Promise<void>;

package/dist/roots-handler.js

@@ -1,199 +0,0 @@
-/**
- * MCP Roots handler for dynamic skill discovery.
- *
- * Requests roots from the client, scans for skills in each root,
- * and handles root change notifications.
- *
- * Pattern adapted from:
- * - .claude/skills/mcp-server-ts/snippets/server/index.ts (oninitialized, syncRoots)
- * - .claude/skills/mcp-client-ts/snippets/handlers/roots.ts (URI conversion)
- */
-import { RootsListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-import { discoverSkills, generateInstructions, createSkillMap, } from "./skill-discovery.js";
-/**
- * Skill discovery locations within each root.
- */
-export const SKILL_SUBDIRS = [".claude/skills", "skills"];
-/**
- * Convert a file:// URI to a filesystem path.
- * Adapted from mcp-client-ts roots.ts pathToRoot() (reverse direction).
- */
-function uriToPath(uri) {
-    return fileURLToPath(new URL(uri));
-}
-/**
- * Discover skills from all roots provided by the client.
- *
- * Scans each root for skill directories (.claude/skills/, skills/)
- * and handles naming conflicts by prefixing with root name.
- *
- * @param roots - Array of Root objects from client's roots/list response
- * @returns Object containing discovered skills
- */
-export function discoverSkillsFromRoots(roots) {
-    const allSkills = [];
-    const rootSources = new Map(); // skill path -> root name
-    const nameCount = new Map(); // track duplicates
-    for (const root of roots) {
-        let rootPath;
-        try {
-            rootPath = uriToPath(root.uri);
-        }
-        catch (error) {
-            console.error(`Failed to parse root URI "${root.uri}":`, error);
-            continue;
-        }
-        const rootName = root.name || path.basename(rootPath);
-        for (const subdir of SKILL_SUBDIRS) {
-            const skillsDir = path.join(rootPath, subdir);
-            if (fs.existsSync(skillsDir)) {
-                try {
-                    const skills = discoverSkills(skillsDir);
-                    for (const skill of skills) {
-                        // Track which root this skill came from
-                        rootSources.set(skill.path, rootName);
-                        // Count occurrences of each name
-                        const count = (nameCount.get(skill.name) || 0) + 1;
-                        nameCount.set(skill.name, count);
-                        allSkills.push(skill);
-                    }
-                }
-                catch (error) {
-                    console.error(`Failed to discover skills in "${skillsDir}":`, error);
-                }
-            }
-        }
-    }
-    // Handle naming conflicts by prefixing duplicates with root name
-    for (const skill of allSkills) {
-        if (nameCount.get(skill.name) > 1) {
-            const rootName = rootSources.get(skill.path);
-            skill.name = `${rootName}:${skill.name}`;
-        }
-    }
-    return { skills: allSkills, rootSources };
-}
-/**
- * Discover skills from a directory, checking both the directory itself
- * and SKILL_SUBDIRS subdirectories.
- */
-function discoverSkillsFromDirectory(skillsDir) {
-    const allSkills = [];
-    // Check if the directory itself contains skills
-    const directSkills = discoverSkills(skillsDir);
-    allSkills.push(...directSkills);
-    // Also check SKILL_SUBDIRS subdirectories
-    for (const subdir of SKILL_SUBDIRS) {
-        const subPath = path.join(skillsDir, subdir);
-        if (fs.existsSync(subPath)) {
-            const subdirSkills = discoverSkills(subPath);
-            allSkills.push(...subdirSkills);
-        }
-    }
-    return allSkills;
-}
-/**
- * Sync skills from roots or configured skills directory.
- *
- * Pattern from mcp-server-ts snippets/server/index.ts:
- * - Check client capabilities
- * - Request roots if supported
- * - Use skills directory if not
- *
- * @param server - The McpServer instance
- * @param skillsDir - Optional skills directory if client doesn't support roots
- * @param onSkillsChanged - Callback when skills are updated
- */
-export async function syncSkills(server, skillsDir, onSkillsChanged) {
-    const capabilities = server.server.getClientCapabilities();
-    const allSkills = [];
-    const seenNames = new Set();
-    // Always discover from configured skills directory first
-    if (skillsDir) {
-        const dirSkills = discoverSkillsFromDirectory(skillsDir);
-        console.error(`Discovered ${dirSkills.length} skill(s) from skills directory`);
-        for (const skill of dirSkills) {
-            if (!seenNames.has(skill.name)) {
-                seenNames.add(skill.name);
-                allSkills.push(skill);
-            }
-        }
-    }
-    // Also discover from roots if client supports them
-    if (capabilities?.roots) {
-        console.error("Client supports roots, requesting workspace roots...");
-        try {
-            const { roots } = await server.server.listRoots();
-            console.error(`Received ${roots.length} root(s) from client`);
-            const { skills: rootSkills } = discoverSkillsFromRoots(roots);
-            console.error(`Discovered ${rootSkills.length} skill(s) from roots`);
-            // Add roots skills, skipping duplicates (skillsDir takes precedence)
-            for (const skill of rootSkills) {
-                if (!seenNames.has(skill.name)) {
-                    seenNames.add(skill.name);
-                    allSkills.push(skill);
-                }
-            }
-            // Listen for roots changes if client supports listChanged
-            if (capabilities.roots.listChanged) {
-                setupRootsChangeHandler(server, skillsDir, onSkillsChanged);
-            }
-        }
-        catch (error) {
-            console.error("Failed to get roots from client:", error);
-        }
-    }
-    else {
-        console.error("Client does not support roots");
-    }
-    console.error(`Total skills available: ${allSkills.length}`);
-    const skillMap = createSkillMap(allSkills);
-    const instructions = generateInstructions(allSkills);
-    onSkillsChanged(skillMap, instructions);
-}
-/**
- * Set up handler for roots/list_changed notifications.
- */
-function setupRootsChangeHandler(server, skillsDir, onSkillsChanged) {
-    server.server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
-        console.error("Roots changed notification received, re-discovering skills...");
-        try {
-            const allSkills = [];
-            const seenNames = new Set();
-            // Always include skills from configured directory first
-            if (skillsDir) {
-                const dirSkills = discoverSkillsFromDirectory(skillsDir);
-                for (const skill of dirSkills) {
-                    if (!seenNames.has(skill.name)) {
-                        seenNames.add(skill.name);
-                        allSkills.push(skill);
-                    }
-                }
-            }
-            // Add skills from roots
-            const { roots } = await server.server.listRoots();
-            const { skills: rootSkills } = discoverSkillsFromRoots(roots);
-            console.error(`Re-discovered ${rootSkills.length} skill(s) from updated roots`);
-            for (const skill of rootSkills) {
-                if (!seenNames.has(skill.name)) {
-                    seenNames.add(skill.name);
-                    allSkills.push(skill);
-                }
-            }
-            console.error(`Total skills available: ${allSkills.length}`);
-            const skillMap = createSkillMap(allSkills);
-            const instructions = generateInstructions(allSkills);
-            onSkillsChanged(skillMap, instructions);
-            // Notify client that resources have changed
-            await server.server.notification({
-                method: "notifications/resources/list_changed",
-            });
-        }
-        catch (error) {
-            console.error("Failed to re-discover skills after roots change:", error);
-        }
-    });
-}