cs-note/claude-code-best/docs/features/experimental-skill-search.md

tags, create time

tags	create time
skill-search 语义搜索 技能发现 feature-flag	2026-06-09 22:30

EXPERIMENTAL_SKILL_SEARCH — 技能语义搜索

概述

EXPERIMENTAL_SKILL_SEARCH 提供 DiscoverSkills 工具，根据当前任务语义搜索可用技能。目标是让模型在执行任务时自动发现和推荐相关的技能（包括本地和远程），无需用户手动查找。

[!info] Feature Flag: FEATURE_EXPERIMENTAL_SKILL_SEARCH=1 实现状态：全部 Stub（8 个文件），布线完整

正文

实现架构

模块状态

模块	文件	状态	说明
DiscoverSkillsTool	src/tools/DiscoverSkillsTool/prompt.ts	Stub	空工具名
预取	src/services/skillSearch/prefetch.ts	Stub	3 个函数全部空操作
远程加载	src/services/skillSearch/remoteSkillLoader.ts	Stub	返回空结果
远程状态	src/services/skillSearch/remoteSkillState.ts	Stub	返回 null/undefined
信号	src/services/skillSearch/signals.ts	Stub	DiscoverySignal = any
遥测	src/services/skillSearch/telemetry.ts	Stub	空操作日志
本地搜索	src/services/skillSearch/localSearch.ts	Stub	空操作缓存
功能检查	src/services/skillSearch/featureCheck.ts	Stub	isSkillSearchEnabled => false
SkillTool 集成	src/tools/SkillTool/SkillTool.ts	布线	动态加载所有远程技能模块
提示集成	src/constants/prompts.ts	布线	DiscoverSkills schema 注入

预期数据流

flowchart TD
    A["模型处理用户任务"] --> B{"DiscoverSkills 工具触发 需要实现"}
    B --> C["本地搜索: 索引已安装技能元数据"]
    C --> D["localSearch.ts -> 技能名称/描述/关键字匹配"]
    B --> E["远程搜索: 查询技能市场/注册表"]
    E --> F["remoteSkillLoader.ts -> fetch + 解析"]
    D --> G["结果排序和过滤"]
    F --> G
    G --> H["返回推荐技能列表"]
    H --> I["模型使用 SkillTool 调用推荐技能"]

预取机制

prefetch.ts 预期在用户提交输入前分析消息内容，提前搜索相关技能：

• startSkillDiscoveryPrefetch() — 开始预取
• collectSkillDiscoveryPrefetch() — 收集预取结果
• getTurnZeroSkillDiscovery() — 获取 turn 0 的技能发现结果

需要补全的内容

优先级	模块	工作量	说明
1	DiscoverSkillsTool	大	语义搜索工具 schema + 执行
2	skillSearch/prefetch.ts	中	用户输入分析和预取逻辑
3	skillSearch/remoteSkillLoader.ts	大	远程市场/注册表获取
4	skillSearch/remoteSkillState.ts	小	已发现技能状态管理
5	skillSearch/localSearch.ts	中	本地索引构建/查询
6	skillSearch/featureCheck.ts	小	GrowthBook/配置门控
7	skillSearch/signals.ts	小	DiscoverySignal 类型定义

关键设计决策

1. 预取优化：在用户提交前就开始搜索，减少首次响应延迟
2. 本地+远程双搜索：本地索引快速匹配 + 远程市场深度搜索
3. SkillTool 集成：发现的技能通过 SkillTool 调用，不需要新的调用机制
4. 独立于 MCP_SKILLS：MCP_SKILLS 从 MCP 服务器发现，EXPERIMENTAL_SKILL_SEARCH 从技能市场发现

使用方式

# 启用 feature（需要补全后才能真正使用）
FEATURE_EXPERIMENTAL_SKILL_SEARCH=1 bun run dev

文件索引

文件	职责
src/tools/DiscoverSkillsTool/prompt.ts	工具 schema（stub）
src/services/skillSearch/prefetch.ts	预取逻辑（stub）
src/services/skillSearch/remoteSkillLoader.ts	远程加载（stub）
src/services/skillSearch/remoteSkillState.ts	远程状态（stub）
src/services/skillSearch/signals.ts	信号类型（stub）
src/services/skillSearch/telemetry.ts	遥测（stub）
src/services/skillSearch/localSearch.ts	本地搜索（stub）
src/services/skillSearch/featureCheck.ts	功能检查（stub）
src/tools/SkillTool/SkillTool.ts	SkillTool 集成点
src/constants/prompts.ts:95,335,778	提示增强

关联笔记

• claude-code-best/docs/features/mcp-skills
• claude-code-best/docs/features/extensibility/skills