| name | skill-adapter |
| description | 扫描新迁移的 Skill 文件,识别适配项并逐项询问用户完成适配,直到所有配置适配新项目环境 |
| aliases | ["skill-adapter","skill-migrate","skill 迁移,适配 Skill"] |
| commands | ["/skill-adapter"] |
| author | Kei |
| triggers | ["迁移 Skill","适配 Skill","这个 Skill 是从别的项目复制的,帮我适配 Skill","skill 移植"] |
| version | 2.0.0 |
| metadata | {"category":"部署流程","type":"交互式配置向导","pattern":"inversion","interaction":"multi-turn","stages":"4","gating":"required"} |
skill-adapter - Skill 迁移适配向导
用途
当用户将 Skill 从其他项目迁移到当前项目时,自动扫描 Skill 文件,识别需要适配的配置项,并通过交互式询问引导用户完成所有适配。
核心原则:
- 不假设业务:所有适配项通过询问确认,不做任何假设
- 无限询问模式:持续询问直到所有适配项确认完成
- 扫描优先:先扫描识别适配项,再逐项处理
- 状态追踪:记录适配进度,支持中断后继续
工作流程
阶段 1:扫描适配项
步骤 1.1:确认扫描范围
询问用户:
## 确认扫描范围
请告诉我需要适配的 Skill:
1. **单个 Skill**:提供 Skill 名称(如 `kb-trigger`)
2. **全部 Skill**:扫描 `.claude/skills/` 目录下所有 Skill
3. **指定目录**:提供具体路径
请回复选项或提供路径。
步骤 1.2:扫描 Skill 文件
读取以下文件识别适配项:
SKILL.md - 主文件(必需)
references/ - 参考文档
scripts/ - 脚本文件
checklists/ - 检查清单
步骤 1.3:识别适配项类型
| 适配项类型 | 识别模式 | 示例 |
|---|
| 硬编码路径 | 绝对路径或特定目录名 | Knowledge Base/、/Users/xxx/ |
| 脚本依赖 | .claude/scripts/ 引用 | node .claude/scripts/xxx.js |
| Hook 配置 | settings.local.json 引用 | UserPromptSubmit hooks |
| Hooks 脚本路径 | hooks command 中的脚本引用 | node .claude/scripts/xxx.js |
| 领域特定 | 技术名词库、模式库 | TECH_ENTITIES、COMMAND_PATTERNS |
| 文件引用 | 相对路径引用 | references/xxx.md |
| MCP 服务依赖 | mcp__ 前缀工具调用 | mcp__playwright__browser_navigate |
| 环境变量 | $VAR、${VAR} 格式 | $PROJECT_DIR |
| 触发器配置 | YAML Frontmatter 中的 triggers/commands/aliases | triggers: [调研,研究] |
步骤 1.4:Hooks 专项检查(如存在)
如果检测到 settings.local.json 中存在 hooks 配置,执行额外检查:
### Hooks 配置检查
检测到 hooks 配置,开始验证...
**检查项:**
1. 脚本文件是否存在
2. 路径格式是否正确(Windows/Linux 分隔符)
3. 环境变量是否可展开(如 %CD%)
4. 路径是否包含空格需要引号包裹
Hooks 验证流程:
| 检查项 | 检测方法 | 修复建议 |
|---|
| 脚本存在性 | Glob 扫描脚本路径 | 确认脚本已复制或路径正确 |
| 路径分隔符 | 检查 / 和 \ 混用 | 统一为平台适用分隔符 |
| 环境变量 | 检测 %VAR% 或 $VAR | 建议改用绝对路径或确认支持 |
| JSON 转义 | 检查 Windows 路径单反斜杠 | JSON 中使用 \\ 双反斜杠 |
阶段 2:列出适配项
步骤 2.1:汇总适配项
路径归一化与合并:
- 扫描完成后,对相同路径值进行归一化处理
- 将使用相同路径的适配项合并为一组
- 每组路径只提问一次,修改应用到所有位置
输出格式:
## 扫描结果
发现以下需要适配的项目:
### Skill: [Skill 名称]
| 序号 | 适配项类型 | 位置 | 当前值 | 优先级 | 合并 |
|------|------------|------|--------|--------|------|
| 1 | 硬编码路径 | SKILL.md:56 等 3 处 | `Knowledge Base/` | 高 | ✅ |
| 2 | 脚本依赖 | SKILL.md:37 | `.claude/scripts/kb-checker.js` | 高 | - |
| 3 | 领域特定 | scripts/xxx.js:20 | `TECH_ENTITIES` | 中 | - |
**待适配总数:** 3 项(已合并 2 处重复路径)
步骤 2.2:确认适配顺序
询问用户:
## 确认适配顺序
建议按以下顺序处理:
1. **高优先级**:路径和脚本依赖(必须先处理)
2. **中优先级**:领域特定配置
3. **低优先级**:可选优化项
是否按建议顺序处理?或指定其他顺序。
阶段 3:逐项询问适配
步骤 3.1:逐项询问
对每个适配项,输出:
## 适配项 #1:硬编码路径
**位置:** `SKILL.md:56`
**当前值:** `Knowledge Base/[主题]/`
**说明:** 这是知识库文档存储路径
**请选择适配方式:**
1. **使用默认路径**:`Knowledge Base/`(当前项目目录)
2. **自定义路径**:输入新路径
3. **跳过**:暂不处理,后续手动修改
请回复选项编号或输入路径。
步骤 3.2:执行修改
根据用户选择:
- 选项 1:使用默认路径
- 选项 2:读取用户输入的路径并替换
- 选项 3:标记为"待处理",继续下一项
步骤 3.3:确认修改
已将 `Knowledge Base/` 替换为 `[用户选择的路径]`
**修改预览:**
```diff
- 存储位置:Knowledge Base/[主题]/[主题名] 核心知识体系.md
+ 存储位置:Docs/[主题]/[主题名] 核心知识体系.md
是否确认此修改?
---
### 阶段 4:验证适配完成
**步骤 4.1:检查适配状态**
扫描所有适配项,确认状态:
| 状态 | 说明 |
|------|------|
| ✅ 已完成 | 用户确认并修改完成 |
| ⏳ 待处理 | 用户选择跳过 |
| ❌ 失败 | 修改执行失败 |
**步骤 4.2:生成适配报告**
```markdown
## 适配完成报告
**Skill 名称:** kb-trigger
**适配时间:** 2026-03-25 10:30
**适配结果:**
| 适配项 | 状态 | 修改内容 |
|--------|------|----------|
| 硬编码路径 | ✅ 完成 | `Knowledge Base/` → `Docs/` |
| 脚本依赖 | ✅ 完成 | 脚本路径已更新 |
| 领域特定 | ⏳ 待处理 | 用户选择跳过 |
**待处理项:** 1 项
**建议:** 后续手动处理待处理项
输出格式
扫描结果格式
## 扫描结果
**扫描目录:** `.claude/skills/kb-trigger/`
**发现适配项:** 3 项
| 序号 | 类型 | 位置 | 当前值 | 优先级 |
|------|------|------|--------|--------|
| 1 | 硬编码路径 | SKILL.md:56 | `...` | 高 |
| 2 | ... | ... | ... | ... |
适配报告格式
## 适配完成报告
**Skill 名称:** [名称]
**适配时间:** [时间]
**适配结果:**
| 适配项 | 状态 | 修改内容 |
|--------|------|----------|
| ... | ... | ... |
**待处理项:** N 项
踩坑清单
| 陷阱 | 错误做法 | 正确做法 |
|---|
| 假设路径 | 直接使用默认路径 | 必须询问用户确认 |
| 批量修改 | 一次性修改所有项 | 逐项询问,逐项确认 |
| 遗漏检查 | 只检查 SKILL.md | 扫描所有相关文件 |
| 状态丢失 | 不记录适配进度 | 写入状态文件支持继续 |
| 跳过不管 | 跳过项不记录 | 记录待处理项并提醒 |
示例
示例 1:适配单个 Skill
用户: /skill-adapter kb-trigger
响应:
📋 开始扫描 Skill: kb-trigger
## 扫描结果
发现以下需要适配的项目:
### Skill: kb-trigger
| 序号 | 类型 | 位置 | 当前值 | 优先级 |
|------|------|------|--------|--------|
| 1 | 硬编码路径 | SKILL.md:56 | `Knowledge Base/` | 高 |
| 2 | 脚本依赖 | SKILL.md:37 | `.claude/scripts/kb-checker.js` | 高 |
**待适配总数:** 2 项
开始逐项适配,是否继续?
示例 2:适配全部 Skill
用户: /skill-adapter all
响应:
📋 开始扫描全部 Skill...
## 扫描结果
**扫描目录:** `.claude/skills/`
**发现 Skills:** 4 个
**发现适配项:** 12 项
按 Skill 分类:
- kb-trigger: 3 项
- auto-skill: 4 项
- research: 2 项
- skill-creator: 3 项
建议按 Skill 逐个处理,是否继续?
示例 3:处理适配项
适配项 #1 询问:
## 适配项 #1:硬编码路径
**位置:** `SKILL.md:56`
**当前值:** `Knowledge Base/[主题]/`
**说明:** 知识库文档存储路径
**请选择适配方式:**
1. 使用默认路径:`Knowledge Base/`
2. 自定义路径:输入新路径
3. 跳过
请回复选项编号或输入路径。
示例 4:适配完成
响应:
## 适配完成报告
**Skill 名称:** kb-trigger
**适配时间:** 2026-03-25 10:30
**适配结果:**
| 适配项 | 状态 | 修改内容 |
|--------|------|----------|
| 硬编码路径 | ✅ 完成 | `Knowledge Base/` → `Docs/` |
| 脚本依赖 | ✅ 完成 | 路径已更新 |
✅ 所有适配项已完成!
注意事项
交互原则
- 不假设:所有适配项必须询问用户
- 不跳过:跳过的项必须记录并提醒
- 不丢失:适配状态必须保存
文件安全
限制说明
- 无法自动检测业务逻辑相关的适配项
- 无法访问需要权限的文件
资源索引
| 资源 | 文件 | 用途 |
|---|
| 适配项类型 | references/adaptation-items.md | 适配项类型定义 |
| 检查清单 | checklists/adaptation-checklist.md | 适配完成检查 |
Skill 版本:1.3.0 | 作者:Kei | 创建日期:2026-03-25
更新:2026-03-27 添加触发器配置适配;添加路径归一化与合并提问规则
更新:2026-03-31 增加 Hooks 脚本路径检查功能,支持验证脚本存在性、路径格式、环境变量