claude-code/docs/features/mcp-skills.md

MCP_SKILLS — MCP 技能发现

Feature Flag: FEATURE_MCP_SKILLS=1 实现状态：功能性实现（config 门控筛选器完整，核心 fetcher 为 stub） 引用数：9

一、功能概述

MCP_SKILLS 将 MCP 服务器暴露的资源（skill:// URI 方案）发现并转换为可调用的技能命令。MCP 服务器可以同时提供 tools、prompts 和 resources；启用此 feature 后，带有 skill:// URI 的资源被识别为技能。

核心特性

• 自动发现：MCP 服务器连接时自动获取 skill:// 资源
• 命令转换：将 MCP 资源转换为 prompt 类型的 Command 对象
• 实时刷新：prompts/resources 列表变化时重新获取技能
• 缓存一致性：连接关闭时清除技能缓存

二、实现架构

2.1 数据流

MCP Server 连接
      │
      ▼
client.ts: connectToServer / setupMcpClientConnections
  ├── fetchToolsForClient     (MCP tools)
  ├── fetchCommandsForClient   (MCP prompts → Command 对象)
  ├── fetchMcpSkillsForClient  (MCP skill:// 资源 → Command 对象) [MCP_SKILLS]
  └── fetchResourcesForClient  (MCP resources)
      │
      ▼
commands = [...mcpPrompts, ...mcpSkills]
      │
      ▼
AppState.mcp.commands 更新
      │
      ▼
getMcpSkillCommands() 过滤 → SkillTool 调用

2.2 技能筛选

文件：src/commands.ts:604-616

getMcpSkillCommands(mcpCommands) 过滤条件：

cmd.type === 'prompt'                  // 必须是 prompt 类型
cmd.loadedFrom === 'mcp'               // 必须来自 MCP 服务器
!cmd.disableModelInvocation            // 必须可由模型调用
feature('MCP_SKILLS')                  // feature flag 必须开启

2.3 条件加载

文件：src/services/mcp/client.ts:129-133

fetchMcpSkillsForClient 通过 require() 条件加载，feature flag 关闭时不加载任何模块：

const fetchMcpSkillsForClient = feature('MCP_SKILLS')
  ? require('../../skills/mcpSkills.js').fetchMcpSkillsForClient
  : null

2.4 缓存管理

技能获取函数维护 .cache（Map），在以下时机清除：

事件	行为
连接关闭	清除该 client 的技能缓存
disconnectMcpServer()	清除技能缓存
prompts/list_changed 通知	刷新 prompts + 并行获取技能
resources/list_changed 通知	刷新 resources + prompts + 技能

2.5 集成点

文件	行	说明
src/commands.ts	604-616, 620-633	命令过滤和 SkillTool 命令收集
src/services/mcp/client.ts	129-133, 1394, 1672, 2176	技能获取、缓存清除、连接时获取
src/services/mcp/useManageMCPConnections.ts	22-26, 682-740	实时刷新（prompts/resources 变化）

三、关键设计决策

1. Feature gate 隔离：feature('MCP_SKILLS') 守护条件 require() 和所有调用点。关闭时无模块加载、无获取操作
2. 资源到技能映射：技能从 MCP 服务器的 skill:// URI 资源中发现。fetchMcpSkillsForClient 负责转换（当前为 stub）
3. 循环依赖避免：mcpSkillBuilders.ts 作为依赖图叶节点，避免 client.ts ↔ mcpSkills.ts ↔ loadSkillsDir.ts 循环
4. 服务器能力检查：技能获取还需要 MCP 服务器支持 resources (!!client.capabilities?.resources)

四、使用方式

# 启用 feature
FEATURE_MCP_SKILLS=1 bun run dev

# 前提条件：
# 1. 配置了支持 skill:// 资源的 MCP 服务器
# 2. MCP 服务器声明了 resources 能力

五、需要补全的内容

文件	状态	需要实现
src/skills/mcpSkills.ts	Stub	fetchMcpSkillsForClient() — 从 MCP 资源列表中筛选 skill:// URI 并转换为 Command 对象
src/skills/mcpSkillBuilders.ts	Stub	技能构建器注册（避免循环依赖）

六、文件索引

文件	职责
src/commands.ts:547-608	技能命令过滤
src/services/mcp/client.ts:117-2358	技能获取 + 缓存管理
src/services/mcp/useManageMCPConnections.ts	实时刷新
src/skills/mcpSkills.ts	核心转换逻辑（stub）