skill-adapter

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. 不假设业务：所有适配项通过询问确认，不做任何假设
2. 无限询问模式：持续询问直到所有适配项确认完成
3. 扫描优先：先扫描识别适配项，再逐项处理
4. 状态追踪：记录适配进度，支持中断后继续

---

工作流程

阶段 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 脚本路径检查功能，支持验证脚本存在性、路径格式、环境变量