@agiflowai/one-mcp 0.2.6 → 0.3.0

package/dist/{http-D9BDXhHn.mjs → http-Bi2N9PUM.mjs}

@@ -1,6 +1,6 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema, isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
-import { access, mkdir, readFile, readdir, stat, unlink, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, readdir, stat, unlink, watch, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import yaml from "js-yaml";
 import { z } from "zod";
@@ -10,6 +10,7 @@ import { tmpdir } from "node:os";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { Liquid } from "liquidjs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
@@ -201,6 +202,7 @@ const ClaudeCodeStdioServerSchema = z.object({
 	env: z.record(z.string(), z.string()).optional(),
 	disabled: z.boolean().optional(),
 	instruction: z.string().optional(),
+	timeout: z.number().positive().optional(),
 	config: AdditionalConfigSchema
 });
 const ClaudeCodeHttpServerSchema = z.object({
@@ -209,6 +211,7 @@ const ClaudeCodeHttpServerSchema = z.object({
 	type: z.enum(["http", "sse"]).optional(),
 	disabled: z.boolean().optional(),
 	instruction: z.string().optional(),
+	timeout: z.number().positive().optional(),
 	config: AdditionalConfigSchema
 });
 const ClaudeCodeServerConfigSchema = z.union([ClaudeCodeStdioServerSchema, ClaudeCodeHttpServerSchema]);
@@ -279,6 +282,7 @@ const McpServerConfigSchema = z.discriminatedUnion("transport", [
 		toolBlacklist: z.array(z.string()).optional(),
 		omitToolDescription: z.boolean().optional(),
 		prompts: z.record(z.string(), InternalPromptConfigSchema).optional(),
+		timeout: z.number().positive().optional(),
 		transport: z.literal("stdio"),
 		config: McpStdioConfigSchema
 	}),
@@ -288,6 +292,7 @@ const McpServerConfigSchema = z.discriminatedUnion("transport", [
 		toolBlacklist: z.array(z.string()).optional(),
 		omitToolDescription: z.boolean().optional(),
 		prompts: z.record(z.string(), InternalPromptConfigSchema).optional(),
+		timeout: z.number().positive().optional(),
 		transport: z.literal("http"),
 		config: McpHttpConfigSchema
 	}),
@@ -297,6 +302,7 @@ const McpServerConfigSchema = z.discriminatedUnion("transport", [
 		toolBlacklist: z.array(z.string()).optional(),
 		omitToolDescription: z.boolean().optional(),
 		prompts: z.record(z.string(), InternalPromptConfigSchema).optional(),
+		timeout: z.number().positive().optional(),
 		transport: z.literal("sse"),
 		config: McpSseConfigSchema
 	})
@@ -330,6 +336,7 @@ function transformClaudeCodeConfig(claudeConfig) {
 				toolBlacklist: stdioConfig.config?.toolBlacklist,
 				omitToolDescription: stdioConfig.config?.omitToolDescription,
 				prompts: stdioConfig.config?.prompts,
+				timeout: stdioConfig.timeout,
 				transport: "stdio",
 				config: {
 					command: interpolatedCommand,
@@ -348,6 +355,7 @@ function transformClaudeCodeConfig(claudeConfig) {
 				toolBlacklist: httpConfig.config?.toolBlacklist,
 				omitToolDescription: httpConfig.config?.omitToolDescription,
 				prompts: httpConfig.config?.prompts,
+				timeout: httpConfig.timeout,
 				transport,
 				config: {
 					url: interpolatedUrl,
@@ -806,6 +814,8 @@ var ConfigFetcherService = class {
 
 //#endregion
 //#region src/services/McpClientManagerService.ts
+/** Default connection timeout in milliseconds (30 seconds) */
+const DEFAULT_CONNECTION_TIMEOUT_MS = 3e4;
 /**
 * MCP Client wrapper for managing individual server connections
 * This is an internal class used by McpClientManagerService
@@ -911,8 +921,10 @@ var McpClientManagerService = class {
 	}
 	/**
 	* Connect to an MCP server based on its configuration with timeout
+	* Uses the timeout from server config, falling back to default (30s)
 	*/
-	async connectToServer(serverName, config, timeoutMs = 1e4) {
+	async connectToServer(serverName, config) {
+		const timeoutMs = config.timeout ?? DEFAULT_CONNECTION_TIMEOUT_MS;
 		if (this.clients.has(serverName)) throw new Error(`Client for ${serverName} is already connected`);
 		const client = new Client({
 			name: `@agiflowai/one-mcp-client`,
@@ -944,6 +956,7 @@ var McpClientManagerService = class {
 	*/
 	async performConnection(mcpClient, config) {
 		if (config.transport === "stdio") await this.connectStdioClient(mcpClient, config.config);
+		else if (config.transport === "http") await this.connectHttpClient(mcpClient, config.config);
 		else if (config.transport === "sse") await this.connectSseClient(mcpClient, config.config);
 		else throw new Error(`Unsupported transport type: ${config.transport}`);
 	}
@@ -957,6 +970,10 @@ var McpClientManagerService = class {
 		const childProcess = transport["_process"];
 		if (childProcess) mcpClient.setChildProcess(childProcess);
 	}
+	async connectHttpClient(mcpClient, config) {
+		const transport = new StreamableHTTPClientTransport(new URL(config.url), { requestInit: config.headers ? { headers: config.headers } : void 0 });
+		await mcpClient["client"].connect(transport);
+	}
 	async connectSseClient(mcpClient, config) {
 		const transport = new SSEClientTransport(new URL(config.url));
 		await mcpClient["client"].connect(transport);
@@ -999,6 +1016,209 @@ var McpClientManagerService = class {
 	}
 };
 
+//#endregion
+//#region src/utils/findConfigFile.ts
+/**
+* Config File Finder Utility
+*
+* DESIGN PATTERNS:
+* - Utility function pattern for reusable logic
+* - Fail-fast pattern with early returns
+* - Environment variable configuration pattern
+*
+* CODING STANDARDS:
+* - Use sync filesystem operations for config discovery (performance)
+* - Check PROJECT_PATH environment variable first
+* - Fall back to current working directory
+* - Support both .yaml and .json extensions
+* - Return null if no config file is found
+*
+* AVOID:
+* - Throwing errors (return null instead for optional config)
+* - Hardcoded file names without extension variants
+* - Ignoring environment variables
+*/
+/**
+* Find MCP configuration file by checking PROJECT_PATH first, then cwd
+* Looks for both mcp-config.yaml and mcp-config.json
+*
+* @returns Absolute path to config file, or null if not found
+*/
+function findConfigFile() {
+	const configFileNames = [
+		"mcp-config.yaml",
+		"mcp-config.yml",
+		"mcp-config.json"
+	];
+	const projectPath = process.env.PROJECT_PATH;
+	if (projectPath) for (const fileName of configFileNames) {
+		const configPath = resolve(projectPath, fileName);
+		if (existsSync(configPath)) return configPath;
+	}
+	const cwd = process.cwd();
+	for (const fileName of configFileNames) {
+		const configPath = join(cwd, fileName);
+		if (existsSync(configPath)) return configPath;
+	}
+	return null;
+}
+
+//#endregion
+//#region src/utils/parseToolName.ts
+/**
+* Parse tool name to extract server and actual tool name
+* Supports both plain tool names and prefixed format: {serverName}__{toolName}
+*
+* @param toolName - The tool name to parse (e.g., "my_tool" or "server__my_tool")
+* @returns Parsed result with optional serverName and actualToolName
+*
+* @example
+* parseToolName("my_tool") // { actualToolName: "my_tool" }
+* parseToolName("server__my_tool") // { serverName: "server", actualToolName: "my_tool" }
+*/
+function parseToolName(toolName) {
+	const separatorIndex = toolName.indexOf("__");
+	if (separatorIndex > 0) return {
+		serverName: toolName.substring(0, separatorIndex),
+		actualToolName: toolName.substring(separatorIndex + 2)
+	};
+	return { actualToolName: toolName };
+}
+
+//#endregion
+//#region src/utils/parseFrontMatter.ts
+/**
+* Parses YAML front matter from a string content.
+* Front matter must be at the start of the content, delimited by `---`.
+*
+* Supports:
+* - Simple key: value pairs
+* - Literal block scalar (|) for multi-line preserving newlines
+* - Folded block scalar (>) for multi-line folding to single line
+*
+* @param content - The content string that may contain front matter
+* @returns Object with parsed front matter (or null) and remaining content
+*
+* @example
+* const result = parseFrontMatter(`---
+* name: my-skill
+* description: A skill description
+* ---
+* The actual content here`);
+* // result.frontMatter = { name: 'my-skill', description: 'A skill description' }
+* // result.content = 'The actual content here'
+*
+* @example
+* // Multi-line with literal block scalar
+* const result = parseFrontMatter(`---
+* name: my-skill
+* description: |
+*   Line 1
+*   Line 2
+* ---
+* Content`);
+* // result.frontMatter.description = 'Line 1\nLine 2'
+*/
+function parseFrontMatter(content) {
+	const trimmedContent = content.trimStart();
+	if (!trimmedContent.startsWith("---")) return {
+		frontMatter: null,
+		content
+	};
+	const endDelimiterIndex = trimmedContent.indexOf("\n---", 3);
+	if (endDelimiterIndex === -1) return {
+		frontMatter: null,
+		content
+	};
+	const yamlContent = trimmedContent.slice(4, endDelimiterIndex).trim();
+	if (!yamlContent) return {
+		frontMatter: null,
+		content
+	};
+	const frontMatter = {};
+	const lines = yamlContent.split("\n");
+	let currentKey = null;
+	let currentValue = [];
+	let multiLineMode = null;
+	let baseIndent = 0;
+	const saveCurrentKey = () => {
+		if (currentKey && currentValue.length > 0) if (multiLineMode === "literal") frontMatter[currentKey] = currentValue.join("\n").trimEnd();
+		else if (multiLineMode === "folded") frontMatter[currentKey] = currentValue.join(" ").trim();
+		else frontMatter[currentKey] = currentValue.join("").trim();
+		currentKey = null;
+		currentValue = [];
+		multiLineMode = null;
+		baseIndent = 0;
+	};
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		const trimmedLine = line.trim();
+		const colonIndex = line.indexOf(":");
+		if (colonIndex !== -1 && !line.startsWith(" ") && !line.startsWith("	")) {
+			saveCurrentKey();
+			const key = line.slice(0, colonIndex).trim();
+			let value = line.slice(colonIndex + 1).trim();
+			if (value === "|" || value === "|-") {
+				currentKey = key;
+				multiLineMode = "literal";
+				if (i + 1 < lines.length) {
+					const match = lines[i + 1].match(/^(\s+)/);
+					baseIndent = match ? match[1].length : 2;
+				}
+			} else if (value === ">" || value === ">-") {
+				currentKey = key;
+				multiLineMode = "folded";
+				if (i + 1 < lines.length) {
+					const match = lines[i + 1].match(/^(\s+)/);
+					baseIndent = match ? match[1].length : 2;
+				}
+			} else {
+				if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
+				if (key && value) frontMatter[key] = value;
+			}
+		} else if (multiLineMode && currentKey) {
+			const lineIndent = line.match(/^(\s*)/)?.[1].length || 0;
+			if (trimmedLine === "") currentValue.push("");
+			else if (lineIndent >= baseIndent) {
+				const unindentedLine = line.slice(baseIndent);
+				currentValue.push(unindentedLine);
+			} else saveCurrentKey();
+		}
+	}
+	saveCurrentKey();
+	return {
+		frontMatter,
+		content: trimmedContent.slice(endDelimiterIndex + 4).trimStart()
+	};
+}
+/**
+* Checks if parsed front matter contains valid skill metadata.
+* A valid skill front matter must have both `name` and `description` fields.
+*
+* @param frontMatter - The parsed front matter object
+* @returns True if front matter contains valid skill metadata
+*/
+function isValidSkillFrontMatter(frontMatter) {
+	return frontMatter !== null && typeof frontMatter.name === "string" && frontMatter.name.length > 0 && typeof frontMatter.description === "string" && frontMatter.description.length > 0;
+}
+/**
+* Extracts skill front matter from content if present and valid.
+*
+* @param content - The content string that may contain skill front matter
+* @returns Object with skill metadata and content, or null if no valid skill front matter
+*/
+function extractSkillFrontMatter(content) {
+	const { frontMatter, content: remainingContent } = parseFrontMatter(content);
+	if (frontMatter && isValidSkillFrontMatter(frontMatter)) return {
+		skill: {
+			name: frontMatter.name,
+			description: frontMatter.description
+		},
+		content: remainingContent
+	};
+	return null;
+}
+
 //#endregion
 //#region src/services/SkillService.ts
 /**
@@ -1069,14 +1289,21 @@ var SkillService = class {
 	skillPaths;
 	cachedSkills = null;
 	skillsByName = null;
+	/** Active file watchers for skill directories */
+	watchers = [];
+	/** Callback invoked when cache is invalidated due to file changes */
+	onCacheInvalidated;
 	/**
 	* Creates a new SkillService instance
 	* @param cwd - Current working directory for resolving relative paths
 	* @param skillPaths - Array of paths to skills directories
+	* @param options - Optional configuration
+	* @param options.onCacheInvalidated - Callback invoked when cache is invalidated due to file changes
 	*/
-	constructor(cwd, skillPaths) {
+	constructor(cwd, skillPaths, options) {
 		this.cwd = cwd;
 		this.skillPaths = skillPaths;
+		this.onCacheInvalidated = options?.onCacheInvalidated;
 	}
 	/**
 	* Get all available skills from configured directories.
@@ -1122,6 +1349,54 @@ var SkillService = class {
 		this.skillsByName = null;
 	}
 	/**
+	* Starts watching skill directories for changes to SKILL.md files.
+	* When changes are detected, the cache is automatically invalidated.
+	*
+	* Uses Node.js fs.watch with recursive option for efficient directory monitoring.
+	* Only invalidates cache when SKILL.md files are modified.
+	*
+	* @example
+	* const skillService = new SkillService(cwd, skillPaths, {
+	*   onCacheInvalidated: () => console.log('Skills cache invalidated')
+	* });
+	* await skillService.startWatching();
+	*/
+	async startWatching() {
+		this.stopWatching();
+		for (const skillPath of this.skillPaths) {
+			const skillsDir = isAbsolute(skillPath) ? skillPath : join(this.cwd, skillPath);
+			if (!await pathExists(skillsDir)) continue;
+			const abortController = new AbortController();
+			this.watchers.push(abortController);
+			this.watchDirectory(skillsDir, abortController.signal).catch((error) => {
+				if (error?.name !== "AbortError") console.error(`[skill-watcher] Error watching ${skillsDir}: ${error instanceof Error ? error.message : "Unknown error"}`);
+			});
+		}
+	}
+	/**
+	* Stops all active file watchers.
+	* Should be called when the service is being disposed.
+	*/
+	stopWatching() {
+		for (const controller of this.watchers) controller.abort();
+		this.watchers = [];
+	}
+	/**
+	* Watches a directory for changes to SKILL.md files.
+	* @param dirPath - Directory path to watch
+	* @param signal - AbortSignal to stop watching
+	*/
+	async watchDirectory(dirPath, signal) {
+		const watcher = watch(dirPath, {
+			recursive: true,
+			signal
+		});
+		for await (const event of watcher) if (event.filename && event.filename.endsWith("SKILL.md")) {
+			this.clearCache();
+			this.onCacheInvalidated?.();
+		}
+	}
+	/**
 	* Load skills from a directory.
 	* Supports both flat structure (SKILL.md) and nested structure (name/SKILL.md).
 	*
@@ -1180,6 +1455,7 @@ var SkillService = class {
 	}
 	/**
 	* Load a single skill file and parse its frontmatter.
+	* Supports multi-line YAML values using literal (|) and folded (>) block scalars.
 	*
 	* @param filePath - Path to the SKILL.md file
 	* @param location - Whether this is a 'project' or 'user' skill
@@ -1193,150 +1469,62 @@ var SkillService = class {
 	* // Returns null if frontmatter is missing name or description
 	*/
 	async loadSkillFile(filePath, location) {
-		let content;
+		let fileContent;
 		try {
-			content = await readFile(filePath, "utf-8");
+			fileContent = await readFile(filePath, "utf-8");
 		} catch (error) {
 			throw new SkillLoadError(`Failed to read skill file: ${error instanceof Error ? error.message : "Unknown error"}`, filePath, error instanceof Error ? error : void 0);
 		}
-		const { metadata, body } = this.parseFrontmatter(content);
-		if (!metadata.name || !metadata.description) return null;
+		const { frontMatter, content } = parseFrontMatter(fileContent);
+		if (!frontMatter || !frontMatter.name || !frontMatter.description) return null;
 		return {
-			name: metadata.name,
-			description: metadata.description,
+			name: frontMatter.name,
+			description: frontMatter.description,
 			location,
-			content: body,
+			content,
 			basePath: dirname(filePath)
 		};
 	}
-	/**
-	* Parse YAML frontmatter from markdown content.
-	* Frontmatter is delimited by --- at start and end.
-	*
-	* @param content - Full markdown content with frontmatter
-	* @returns Parsed metadata and body content
-	*
-	* @example
-	* // Input content:
-	* // ---
-	* // name: my-skill
-	* // description: A sample skill
-	* // ---
-	* // # Skill Content
-	* // This is the skill body.
-	*
-	* const result = parseFrontmatter(content);
-	* // result.metadata = { name: 'my-skill', description: 'A sample skill' }
-	* // result.body = '# Skill Content\nThis is the skill body.'
-	*/
-	parseFrontmatter(content) {
-		const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
-		if (!match) return {
-			metadata: {},
-			body: content
-		};
-		const [, frontmatter, body] = match;
-		const metadata = {};
-		const lines = frontmatter.split("\n");
-		for (const line of lines) {
-			const colonIndex = line.indexOf(":");
-			if (colonIndex > 0) {
-				const key = line.slice(0, colonIndex).trim();
-				let value = line.slice(colonIndex + 1).trim();
-				if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
-				if (key === "name" || key === "description" || key === "license") metadata[key] = value;
-			}
-		}
-		return {
-			metadata,
-			body: body.trim()
-		};
-	}
 };
 
 //#endregion
-//#region src/utils/findConfigFile.ts
+//#region src/constants/index.ts
 /**
-* Config File Finder Utility
-*
-* DESIGN PATTERNS:
-* - Utility function pattern for reusable logic
-* - Fail-fast pattern with early returns
-* - Environment variable configuration pattern
-*
-* CODING STANDARDS:
-* - Use sync filesystem operations for config discovery (performance)
-* - Check PROJECT_PATH environment variable first
-* - Fall back to current working directory
-* - Support both .yaml and .json extensions
-* - Return null if no config file is found
-*
-* AVOID:
-* - Throwing errors (return null instead for optional config)
-* - Hardcoded file names without extension variants
-* - Ignoring environment variables
+* Shared constants for one-mcp package
 */
 /**
-* Find MCP configuration file by checking PROJECT_PATH first, then cwd
-* Looks for both mcp-config.yaml and mcp-config.json
-*
-* @returns Absolute path to config file, or null if not found
+* Prefix added to skill names when they clash with MCP tool names.
+* This ensures skills can be uniquely identified even when a tool has the same name.
 */
-function findConfigFile() {
-	const configFileNames = [
-		"mcp-config.yaml",
-		"mcp-config.yml",
-		"mcp-config.json"
-	];
-	const projectPath = process.env.PROJECT_PATH;
-	if (projectPath) for (const fileName of configFileNames) {
-		const configPath = resolve(projectPath, fileName);
-		if (existsSync(configPath)) return configPath;
-	}
-	const cwd = process.cwd();
-	for (const fileName of configFileNames) {
-		const configPath = join(cwd, fileName);
-		if (existsSync(configPath)) return configPath;
-	}
-	return null;
-}
-
-//#endregion
-//#region src/utils/parseToolName.ts
+const SKILL_PREFIX$1 = "skill__";
 /**
-* Parse tool name to extract server and actual tool name
-* Supports both plain tool names and prefixed format: {serverName}__{toolName}
-*
-* @param toolName - The tool name to parse (e.g., "my_tool" or "server__my_tool")
-* @returns Parsed result with optional serverName and actualToolName
-*
-* @example
-* parseToolName("my_tool") // { actualToolName: "my_tool" }
-* parseToolName("server__my_tool") // { serverName: "server", actualToolName: "my_tool" }
+* Log prefix for skill detection messages.
+* Used to easily filter skill detection logs in stderr output.
 */
-function parseToolName(toolName) {
-	const separatorIndex = toolName.indexOf("__");
-	if (separatorIndex > 0) return {
-		serverName: toolName.substring(0, separatorIndex),
-		actualToolName: toolName.substring(separatorIndex + 2)
-	};
-	return { actualToolName: toolName };
-}
-
-//#endregion
-//#region src/templates/skills-description.liquid?raw
-var skills_description_default = "{% if skills.size > 0 %}\n<skills>\n<instructions>\nWhen users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.\n\nHow to use skills:\n- Invoke skills using this tool with the skill name only (no arguments)\n- When you invoke a skill, you will see <command-message>The \"{name}\" skill is loading</command-message>\n- The skill's prompt will expand and provide detailed instructions on how to complete the task\n- Examples:\n  - `skill: \"pdf\"` - invoke the pdf skill\n  - `skill: \"xlsx\"` - invoke the xlsx skill\n  - `skill: \"ms-office-suite:pdf\"` - invoke using fully qualified name\n\nImportant:\n- Only use skills listed in <available_skills> below\n- Do not invoke a skill that is already running\n- Do not use this tool for built-in CLI commands (like /help, /clear, etc.)\n</instructions>\n\n<available_skills>\n{% for skill in skills -%}\n<item><name>{{ skill.displayName }}</name><description>{{ skill.description }}</description></item>\n{% endfor -%}\n</available_skills>\n</skills>\n{% endif %}\n";
+const LOG_PREFIX_SKILL_DETECTION = "[skill-detection]";
+/**
+* Prefix for prompt-based skill locations.
+* Format: "prompt:{serverName}:{promptName}"
+*/
+const PROMPT_LOCATION_PREFIX = "prompt:";
 
 //#endregion
-//#region src/templates/mcp-servers-description.liquid?raw
-var mcp_servers_description_default = "<mcp_servers>\n<instructions>\nBefore you use any tools above, you MUST call this tool with a list of tool names to learn how to use them properly before use_tool; this includes:\n- Arguments schema needed to pass to the tool use\n- Description about each tool\n\nThis tool is optimized for batch queries - you can request multiple tools at once for better performance.\n</instructions>\n\n{% for server in servers -%}\n<server name=\"{{ server.name }}\">\n{% if server.instruction -%}\n<instruction>{{ server.instruction }}</instruction>\n{% endif -%}\n<tools>\n{% if server.omitToolDescription -%}\n{{ server.toolNames | join: \", \" }}\n{% else -%}\n{% for tool in server.tools -%}\n<item><name>{{ tool.displayName }}</name><description>{{ tool.description | default: \"No description\" }}</description></item>\n{% endfor -%}\n{% endif -%}\n</tools>\n</server>\n{% endfor -%}\n</mcp_servers>\n";
+//#region src/templates/toolkit-description.liquid?raw
+var toolkit_description_default = "<toolkit>\n<instruction>\nBefore you use any capabilities below, you MUST call this tool with a list of names to learn how to use them properly; this includes:\n- For tools: Arguments schema needed to pass to use_tool\n- For skills: Detailed instructions that will expand when invoked (Prefer to be explored first when relevant)\n\nThis tool is optimized for batch queries - you can request multiple capabilities at once for better performance.\n\nHow to invoke:\n- For MCP tools: Use use_tool with toolName and toolArgs based on the schema\n- For skills: Use this tool with the skill name to get expanded instructions\n</instruction>\n\n<available_capabilities>\n{% for server in servers -%}\n<group name=\"{{ server.name }}\">\n{% if server.instruction -%}\n<group_instruction>{{ server.instruction }}</group_instruction>\n{% endif -%}\n{% if server.omitToolDescription -%}\n{% for toolName in server.toolNames -%}\n<item name=\"{{ toolName }}\"></item>\n{% endfor -%}\n{% else -%}\n{% for tool in server.tools -%}\n<item name=\"{{ tool.displayName }}\"><description>{{ tool.description | default: \"No description\" }}</description></item>\n{% endfor -%}\n{% endif -%}\n</group>\n{% endfor -%}\n{% if skills.size > 0 -%}\n<group name=\"skills\">\n{% for skill in skills -%}\n<item name=\"{{ skill.displayName }}\"><description>{{ skill.description }}</description></item>\n{% endfor -%}\n</group>\n{% endif -%}\n</available_capabilities>\n</toolkit>\n";
 
 //#endregion
 //#region src/tools/DescribeToolsTool.ts
 /**
-* Prefix used to identify skill invocations
+* Formats skill instructions with the loading command message prefix.
+* This message is used by Claude Code to indicate that a skill is being loaded.
+*
+* @param name - The skill name
+* @param instructions - The raw skill instructions/content
+* @returns Formatted instructions with command message prefix
 */
-const SKILL_PREFIX$1 = "skill__";
+function formatSkillInstructions(name, instructions) {
+	return `<command-message>The "${name}" skill is loading</command-message>\n${instructions}`;
+}
 /**
 * DescribeToolsTool provides progressive disclosure of MCP tools and skills.
 *
@@ -1359,6 +1547,8 @@ var DescribeToolsTool = class DescribeToolsTool {
 	clientManager;
 	skillService;
 	liquid = new Liquid();
+	/** Cache for auto-detected skills from prompt front-matter */
+	autoDetectedSkillsCache = null;
 	/**
 	* Creates a new DescribeToolsTool instance
 	* @param clientManager - The MCP client manager for accessing remote servers
@@ -1369,12 +1559,79 @@ var DescribeToolsTool = class DescribeToolsTool {
 		this.skillService = skillService;
 	}
 	/**
+	* Clears the cached auto-detected skills from prompt front-matter.
+	* Use this when prompt configurations may have changed or when
+	* the skill service cache is invalidated.
+	*/
+	clearAutoDetectedSkillsCache() {
+		this.autoDetectedSkillsCache = null;
+	}
+	/**
+	* Detects and caches skills from prompt front-matter across all connected MCP servers.
+	* Fetches all prompts and checks their content for YAML front-matter with name/description.
+	* Results are cached to avoid repeated fetches.
+	*
+	* Error Handling Strategy:
+	* - Errors are logged to stderr but do not fail the overall detection process
+	* - This ensures partial results are returned even if some servers/prompts fail
+	* - Common failure reasons: server temporarily unavailable, prompt requires arguments,
+	*   network timeout, or server doesn't support listPrompts
+	* - Errors are prefixed with [skill-detection] for easy filtering in logs
+	*
+	* @returns Array of auto-detected skills from prompt front-matter
+	*/
+	async detectSkillsFromPromptFrontMatter() {
+		if (this.autoDetectedSkillsCache !== null) return this.autoDetectedSkillsCache;
+		const clients = this.clientManager.getAllClients();
+		const autoDetectedSkills = [];
+		let listPromptsFailures = 0;
+		let fetchPromptFailures = 0;
+		const fetchPromises = [];
+		for (const client of clients) {
+			const configuredPromptNames = new Set(client.prompts ? Object.keys(client.prompts) : []);
+			const listPromptsPromise = (async () => {
+				try {
+					const prompts = await client.listPrompts();
+					if (!prompts || prompts.length === 0) return;
+					const promptFetchPromises = prompts.map(async (promptInfo) => {
+						if (configuredPromptNames.has(promptInfo.name)) return;
+						try {
+							const skillExtraction = extractSkillFrontMatter(((await client.getPrompt(promptInfo.name)).messages || []).map((m) => {
+								const content = m.content;
+								if (typeof content === "string") return content;
+								if (content && typeof content === "object" && "text" in content) return String(content.text);
+								return "";
+							}).join("\n"));
+							if (skillExtraction) autoDetectedSkills.push({
+								serverName: client.serverName,
+								promptName: promptInfo.name,
+								skill: skillExtraction.skill
+							});
+						} catch (error) {
+							fetchPromptFailures++;
+							console.error(`${LOG_PREFIX_SKILL_DETECTION} Failed to fetch prompt '${promptInfo.name}' from ${client.serverName}: ${error instanceof Error ? error.message : "Unknown error"}`);
+						}
+					});
+					await Promise.all(promptFetchPromises);
+				} catch (error) {
+					listPromptsFailures++;
+					console.error(`${LOG_PREFIX_SKILL_DETECTION} Failed to list prompts from ${client.serverName}: ${error instanceof Error ? error.message : "Unknown error"}`);
+				}
+			})();
+			fetchPromises.push(listPromptsPromise);
+		}
+		await Promise.all(fetchPromises);
+		if (listPromptsFailures > 0 || fetchPromptFailures > 0) console.error(`${LOG_PREFIX_SKILL_DETECTION} Completed with ${listPromptsFailures} server failure(s) and ${fetchPromptFailures} prompt failure(s). Detected ${autoDetectedSkills.length} skill(s).`);
+		this.autoDetectedSkillsCache = autoDetectedSkills;
+		return autoDetectedSkills;
+	}
+	/**
 	* Collects skills derived from prompt configurations across all connected MCP servers.
-	* Prompts with a skill configuration are converted to skill format for display.
+	* Includes both explicitly configured prompts and auto-detected skills from front-matter.
 	*
 	* @returns Array of skill template data derived from prompts
 	*/
-	collectPromptSkills() {
+	async collectPromptSkills() {
 		const clients = this.clientManager.getAllClients();
 		const promptSkills = [];
 		for (const client of clients) {
@@ -1385,16 +1642,22 @@ var DescribeToolsTool = class DescribeToolsTool {
 				description: promptConfig.skill.description
 			});
 		}
+		const autoDetectedSkills = await this.detectSkillsFromPromptFrontMatter();
+		for (const autoSkill of autoDetectedSkills) promptSkills.push({
+			name: autoSkill.skill.name,
+			displayName: autoSkill.skill.name,
+			description: autoSkill.skill.description
+		});
 		return promptSkills;
 	}
 	/**
 	* Finds a prompt-based skill by name from all connected MCP servers.
-	* Returns the prompt name and skill config for fetching the prompt content.
+	* Searches both explicitly configured prompts and auto-detected skills from front-matter.
 	*
 	* @param skillName - The skill name to search for
 	* @returns Object with serverName, promptName, and skill config, or undefined if not found
 	*/
-	findPromptSkill(skillName) {
+	async findPromptSkill(skillName) {
 		if (!skillName) return void 0;
 		const clients = this.clientManager.getAllClients();
 		for (const client of clients) {
@@ -1405,16 +1668,24 @@ var DescribeToolsTool = class DescribeToolsTool {
 				skill: promptConfig.skill
 			};
 		}
+		const autoDetectedSkills = await this.detectSkillsFromPromptFrontMatter();
+		for (const autoSkill of autoDetectedSkills) if (autoSkill.skill.name === skillName) return {
+			serverName: autoSkill.serverName,
+			promptName: autoSkill.promptName,
+			skill: autoSkill.skill,
+			autoDetected: true
+		};
 	}
 	/**
 	* Retrieves skill content from a prompt-based skill configuration.
 	* Fetches the prompt from the MCP server and extracts text content.
+	* Handles both explicitly configured prompts and auto-detected skills from front-matter.
 	*
 	* @param skillName - The skill name being requested
 	* @returns SkillDescription if found and successfully fetched, undefined otherwise
 	*/
 	async getPromptSkillContent(skillName) {
-		const promptSkill = this.findPromptSkill(skillName);
+		const promptSkill = await this.findPromptSkill(skillName);
 		if (!promptSkill) return void 0;
 		const client = this.clientManager.getClient(promptSkill.serverName);
 		if (!client) {
@@ -1422,7 +1693,7 @@ var DescribeToolsTool = class DescribeToolsTool {
 			return;
 		}
 		try {
-			const instructions = (await client.getPrompt(promptSkill.promptName)).messages?.map((m) => {
+			const rawInstructions = (await client.getPrompt(promptSkill.promptName)).messages?.map((m) => {
 				const content = m.content;
 				if (typeof content === "string") return content;
 				if (content && typeof content === "object" && "text" in content) return String(content.text);
@@ -1430,8 +1701,8 @@ var DescribeToolsTool = class DescribeToolsTool {
 			}).join("\n") || "";
 			return {
 				name: promptSkill.skill.name,
-				location: promptSkill.skill.folder || `prompt:${promptSkill.serverName}/${promptSkill.promptName}`,
-				instructions
+				location: promptSkill.skill.folder || `${PROMPT_LOCATION_PREFIX}${promptSkill.serverName}/${promptSkill.promptName}`,
+				instructions: formatSkillInstructions(promptSkill.skill.name, rawInstructions)
 			};
 		} catch (error) {
 			console.error(`Failed to get prompt-based skill '${skillName}': ${error instanceof Error ? error.message : "Unknown error"}`);
@@ -1439,49 +1710,18 @@ var DescribeToolsTool = class DescribeToolsTool {
 		}
 	}
 	/**
-	* Builds the skills section of the tool description using a Liquid template.
+	* Builds the combined toolkit description using a single Liquid template.
 	*
-	* Retrieves all available skills from the SkillService and prompt-based skills,
-	* then renders them using the skills-description.liquid template. Skills are only
-	* prefixed with skill__ when their name clashes with an MCP tool or another skill.
-	*
-	* @param mcpToolNames - Set of MCP tool names to check for clashes
-	* @returns Rendered skills section string with available skills list
-	*/
-	async buildSkillsSection(mcpToolNames) {
-		const rawSkills = this.skillService ? await this.skillService.getSkills() : [];
-		const promptSkills = this.collectPromptSkills();
-		const allSkillsData = [...rawSkills.map((skill) => ({
-			name: skill.name,
-			displayName: skill.name,
-			description: skill.description
-		})), ...promptSkills];
-		const skillNameCounts = /* @__PURE__ */ new Map();
-		for (const skill of allSkillsData) skillNameCounts.set(skill.name, (skillNameCounts.get(skill.name) || 0) + 1);
-		const skills = allSkillsData.map((skill) => {
-			const clashesWithMcpTool = mcpToolNames.has(skill.name);
-			const clashesWithOtherSkill = (skillNameCounts.get(skill.name) || 0) > 1;
-			const needsPrefix = clashesWithMcpTool || clashesWithOtherSkill;
-			return {
-				name: skill.name,
-				displayName: needsPrefix ? `${SKILL_PREFIX$1}${skill.name}` : skill.name,
-				description: skill.description
-			};
-		});
-		return this.liquid.parseAndRender(skills_description_default, { skills });
-	}
-	/**
-	* Builds the MCP servers section of the tool description using a Liquid template.
-	*
-	* Collects all tools from connected MCP servers, detects name clashes,
-	* and renders them using the mcp-servers-description.liquid template.
+	* Collects all tools from connected MCP servers and all skills, then renders
+	* them together using the toolkit-description.liquid template.
 	*
 	* Tool names are prefixed with serverName__ when the same tool exists
-	* on multiple servers to avoid ambiguity.
+	* on multiple servers. Skill names are prefixed with skill__ when they
+	* clash with MCP tools or other skills.
 	*
-	* @returns Object with rendered servers section and set of all tool names for skill clash detection
+	* @returns Object with rendered description and set of all tool names
 	*/
-	async buildServersSection() {
+	async buildToolkitDescription() {
 		const clients = this.clientManager.getAllClients();
 		const toolToServers = /* @__PURE__ */ new Map();
 		const serverToolsMap = /* @__PURE__ */ new Map();
@@ -1502,9 +1742,6 @@ var DescribeToolsTool = class DescribeToolsTool {
 		}));
 		/**
 		* Formats tool name with server prefix if the tool exists on multiple servers
-		* @param toolName - The original tool name
-		* @param serverName - The server providing this tool
-		* @returns Tool name prefixed with serverName__ if clashing, otherwise plain name
 		*/
 		const formatToolName = (toolName, serverName) => {
 			return (toolToServers.get(toolName) || []).length > 1 ? `${serverName}__${toolName}` : toolName;
@@ -1524,31 +1761,56 @@ var DescribeToolsTool = class DescribeToolsTool {
 				toolNames: formattedTools.map((t) => t.displayName)
 			};
 		});
+		const rawSkills = this.skillService ? await this.skillService.getSkills() : [];
+		const promptSkills = await this.collectPromptSkills();
+		const seenSkillNames = /* @__PURE__ */ new Set();
+		const allSkillsData = [];
+		for (const skill of rawSkills) if (!seenSkillNames.has(skill.name)) {
+			seenSkillNames.add(skill.name);
+			allSkillsData.push({
+				name: skill.name,
+				displayName: skill.name,
+				description: skill.description
+			});
+		}
+		for (const skill of promptSkills) if (!seenSkillNames.has(skill.name)) {
+			seenSkillNames.add(skill.name);
+			allSkillsData.push(skill);
+		}
+		const skills = allSkillsData.map((skill) => {
+			const clashesWithMcpTool = allToolNames.has(skill.name);
+			return {
+				name: skill.name,
+				displayName: clashesWithMcpTool ? `${SKILL_PREFIX$1}${skill.name}` : skill.name,
+				description: skill.description
+			};
+		});
 		return {
-			content: await this.liquid.parseAndRender(mcp_servers_description_default, { servers }),
+			content: await this.liquid.parseAndRender(toolkit_description_default, {
+				servers,
+				skills
+			}),
 			toolNames: allToolNames
 		};
 	}
 	/**
-	* Gets the tool definition including available servers, tools, and skills.
+	* Gets the tool definition including available tools and skills in a unified format.
 	*
 	* The definition includes:
-	* - List of all connected MCP servers with their available tools
-	* - List of available skills with skill__ prefix
-	* - Usage instructions for querying tool/skill details
+	* - All MCP tools from connected servers
+	* - All available skills (file-based and prompt-based)
+	* - Unified instructions for querying capability details
 	*
-	* Tool names are prefixed with serverName__ when the same tool name
-	* exists on multiple servers to avoid ambiguity.
+	* Tool names are prefixed with serverName__ when clashing.
+	* Skill names are prefixed with skill__ when clashing.
 	*
 	* @returns Tool definition with description and input schema
 	*/
 	async getDefinition() {
-		const serversResult = await this.buildServersSection();
-		const skillsSection = await this.buildSkillsSection(serversResult.toolNames);
+		const { content } = await this.buildToolkitDescription();
 		return {
 			name: DescribeToolsTool.TOOL_NAME,
-			description: `${serversResult.content}
-${skillsSection}`,
+			description: content,
 			inputSchema: {
 				type: "object",
 				properties: { toolNames: {
@@ -1613,14 +1875,14 @@ ${skillsSection}`,
 			const notFoundItems = [];
 			for (const requestedName of toolNames) {
 				if (requestedName.startsWith(SKILL_PREFIX$1)) {
-					const skillName = requestedName.slice(7);
+					const skillName = requestedName.slice(SKILL_PREFIX$1.length);
 					if (this.skillService) {
 						const skill = await this.skillService.getSkill(skillName);
 						if (skill) {
 							foundSkills.push({
 								name: skill.name,
 								location: skill.basePath,
-								instructions: skill.content
+								instructions: formatSkillInstructions(skill.name, skill.content)
 							});
 							continue;
 						}
@@ -1659,7 +1921,7 @@ ${skillsSection}`,
 								foundSkills.push({
 									name: skill.name,
 									location: skill.basePath,
-									instructions: skill.content
+									instructions: formatSkillInstructions(skill.name, skill.content)
 								});
 								continue;
 							}
@@ -2031,9 +2293,16 @@ async function createServer(options) {
 		if (failedConnections.length > 0 && failedConnections.length === Object.keys(config.mcpServers).length) throw new Error(`All MCP server connections failed: ${failedConnections.map((f) => `${f.serverName}: ${f.error.message}`).join(", ")}`);
 	}
 	const skillsConfig = options?.skills || configSkills;
-	const skillService = skillsConfig && skillsConfig.paths.length > 0 ? new SkillService(process.cwd(), skillsConfig.paths) : void 0;
+	const toolsRef = { describeTools: null };
+	const skillService = skillsConfig && skillsConfig.paths.length > 0 ? new SkillService(process.cwd(), skillsConfig.paths, { onCacheInvalidated: () => {
+		toolsRef.describeTools?.clearAutoDetectedSkillsCache();
+	} }) : void 0;
 	const describeTools = new DescribeToolsTool(clientManager, skillService);
 	const useTool = new UseToolTool(clientManager, skillService);
+	toolsRef.describeTools = describeTools;
+	if (skillService) skillService.startWatching().catch((error) => {
+		console.error(`[skill-watcher] File watcher failed (non-critical): ${error instanceof Error ? error.message : "Unknown error"}`);
+	});
 	server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [await describeTools.getDefinition(), useTool.getDefinition()] }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
 		const { name, arguments: args } = request.params;
@@ -2452,4 +2721,4 @@ var HttpTransportHandler = class {
 };
 
 //#endregion
-export { findConfigFile as a, ConfigFetcherService as c, createServer as i, SseTransportHandler as n, SkillService as o, StdioTransportHandler as r, McpClientManagerService as s, HttpTransportHandler as t };
+export { SkillService as a, ConfigFetcherService as c, createServer as i, SseTransportHandler as n, findConfigFile as o, StdioTransportHandler as r, McpClientManagerService as s, HttpTransportHandler as t };