| name | app-skill-wizard |
| description | Skill 创建向导 - 交互式引导按模块生成 Copilot 专家 Skill。
支持任意平台和应用层级，自动从 project-profile.json 读取技术栈配置。
分批深度研究 + 分批生成，确保代码入口精确。
触发关键词: 创建Skill, 新应用专家, 生成模块专家, app skill wizard,
新增应用, 为应用创建专家, 添加应用Skill, create app skills,
平台Skill, 再生专家, regenerate experts, 批量生成Skill,
项目接入, project setup, 新项目专家
|
Skill 创建向导
交互式引导：为目标项目按模块生成 Copilot 专家 Skill，注册到类别系统，通过 GUI 部署。
支持任意平台和应用层级。当存在 project-profile.json 时自动消费其中的技术栈/分层信息。
AI 自动执行大部分操作，在 3 个检查点暂停等用户确认。
🔴 执行声明（强制）
你正在执行一个交互式向导，必须严格按照以下流程执行。
每个步骤完成后更新进度，在 🔴 检查点处必须暂停等用户确认后再继续。
启动时的开场引导（强制）
收到用户消息后，立即显示以下引导信息（在做任何操作之前）：
👋 你好！我来帮你生成 Copilot Skill。
**整个过程我来跑，你只需要在 3 个关键节点确认一下：**
1️⃣ 确认模块清单 — 我分析完代码后，你看看模块划分对不对
2️⃣ 确认生成质量 — Skill 文件生成完，我会自动 lint 检查 + 评分
3️⃣ 确认交付清单 — 最终文件列表，可选自动提交 PR 并通知审阅人
⬇️ 现在开始收集信息...
然后进入 Step 0。
执行流程
Step 0 环境 + 信息收集
│
├── 0-pre 运行模式选择
├── 0a 提取应用名 + 命名前缀
├── 0a' 确定 Skill 层级（应用/平台）
├── 0b 获取模块列表
└── 0c 分析平台继承关系（应用层）
│
▼
🔴 CP0 模块清单确认 ◀── 暂停：展示表格，等用户确认/修改
│
▼
Step 1 分批研究 + 生成
│
├── 1a 读取模版 + 参考
├── 1b 分批深度研究（runSubagent）
├── 1c 基于研究报告逐批生成 SKILL.md
├── 1d [应用层] 读取 XML 配置自动填充
└── 1e 自动 lint 验证
│
▼
🔴 CP1 生成质量确认 ◀── 暂停：展示 lint 结果 + 评分卡，等用户确认
│
▼
Step 2 注册类别 + 配置（AI自动）
│
▼
🔴 CP2 交付确认 ◀── 暂停：展示文件清单，等用户确认
│
▼
Step 3 [可选] 提交 PR + 飞书通知
│
├── 3-local [多根工作区] 本地脚本 create_skill_pr.ps1
└── 3-remote [纯目标项目] MCP create_branch → create_commit → create_pull_request
│
▼
🔴 CP3 最终交付确认 ◀── 暂停：展示 PR 链接 + 通知状态
Step 0：环境 + 信息收集
0-pre-profile. 检查 project-profile.json
优先检查 .copilot-temp/project-setup/*/project-profile.json 是否存在。
如存在：
- 读取 profile 中的
techStack、layers、platform、configDiscovery
- 跳过 Step 0a'(Skill层级)和 Step 0c(平台继承分析) 中的 平台特有逻辑
- 在 Step 1b 的研究指令中注入技术栈相关搜索项
- 在 Step 1d 的配置发现中使用 profile 的
configDiscovery 规则
如不存在：
0-pre. 运行模式选择
自动检测当前工作区结构，使用 ask_questions 确认运行模式：
- 检查工作区根目录列表 — 确认是否包含工具项目（含
templates/skills/ 和 data/skill_categories.json）
- 检查 MCP 可用性 — 确认是否有
azureDevOpsHSW MCP server（可访问工具仓库）
模式选择（ask_questions）：
- header: "运行模式"
- question: "检测到当前环境支持以下模式，请选择："
- 选项A（推荐 — 如检测到工具项目）: "多根工作区模式 — 工具项目已在工作区，本地读写"
- 选项B（推荐 — 如未检测到工具项目但有 MCP）: "纯目标项目模式 — 通过 MCP 远程读写工具仓库"
| 多根工作区模式 | 纯目标项目模式 |
|---|
| 前提 | 工具项目 + 目标项目同时打开 | MCP 已配置 azureDevOpsHSW |
| 模板读取 | read_file 本地读取 | MCP get_file_content 远程读取 |
| Skill 生成位置 | templates/skills/（工具项目内） | .github/skills/（目标项目本地预览） |
| 类别注册 | 本地编辑 skill_categories.json | MCP create_commit search/replace 远程编辑 |
| PR 创建 | create_skill_pr.ps1 本地脚本 | MCP create_branch → create_commit → create_pull_request |
| 部署到目标项目 | python scripts/deploy_skills.py 或 GUI | 已在本地，无需额外部署 |
如果两种模式都不可用（无工具项目 + 无 HSW MCP），使用 ask_questions 引导：
- header: "环境设置"
- question: "当前环境无法访问工具仓库。请选择以下方式之一设置环境："
- 选项A: "添加工具项目到工作区（File > Add Folder to Workspace...）"
- 选项B: "运行 GUI 工具配置 MCP（双击 点我启动.bat）"
0a. 提取应用名和命名前缀
从用户消息中提取应用名称（如 "YourApp"、"{{PLATFORM_REPO}}"），然后推导：
- 命名前缀: 全小写 + 连字符，如
cardiacct- 或 平台-
- Skill 命名格式:
{前缀}{模块名}-expert
如果用户未明确说应用名，使用 ask_questions 对话框询问：
- header: "应用名称"
- question: "请输入要创建 Skill 的应用/项目名称（如 YourApp、YourPlatform、{{PLATFORM_REPO}}）"
- allowFreeformInput: true，无预设选项
0a'. 确定 Skill 层级
如已从 project-profile.json 读取层级信息，可跳过此步。
使用 ask_questions 确认 Skill 层级：
- header: "Skill层级"
- question: "这批 Skill 属于哪个层级？不同层级的模版章节和行数限制不同。"
- 选项A: "应用层 — 有配置映射，≤120 行" (recommended)
- 选项B: "平台层 — 有搜索策略+核心概念，≤150 行"
层级差异：
| 应用层 | 平台层 |
|---|
| 行数上限 | ≤ 120 行 | ≤ 150 行 |
| 运行时配置映岄 | ✅ 必填 | ⬜ 跳过 |
| 搜索策略 | ⬜ 跳过 | ✅ 必填 |
| 核心概念 | ⬜ 跳过 | ✅ 必填（5-8 行） |
| 与平台的关系 | ✅ 必填 | ⬜ 跳过 |
0b. 获取模块列表
直接在多根工作区中访问目标项目，按优先级获取模块列表：
- 用户提到了模块清单文件 → 直接
read_file 读取
- 搜索现有清单 → 在目标项目中
file_search 搜索 *功能模块清单*
- 扫描目录结构推断 →
list_dir 目标项目关键目录
- 如有
project-profile.json: 使用 layers[].dirPattern 扫描对应目录
- 平台默认: 扫描
BE/、FE/、WebFE/ 目录
- 其他项目: 扫描
src/、packages/、modules/ 等通用目录
- 均无法确定 → 使用 ask_questions 对话框询问用户提供模块列表
对每个模块确定：
- 模块中文名
- 模块英文标识（用于 Skill 命名）
- 一句话职责描述
0c. 分析平台继承关系
仅应用层执行，平台层跳过。
对每个模块判断与平台的关系：
- 如有
project-profile.json: 读取 platform.identifier 构建平台专家前缀
- 搜索关键词:
project-profile.platform.name 相关的 import/using/include 语句
- 平台专家关联:
#{platform_identifier}-{component}-expert
- 平台默认（无 profile 时）:
- 依据 1: 模块名是否与已有
{{PLATFORM_PREFIX}}-*-expert 同名
- 依据 2: 搜索
using.*平台|import.*平台 判断是否引用平台
- 依据 3: 应用特有功能判定为 🆕 独立实现
输出两类：
- 🔄 扩展继承: 有对应平台模块 → 记录关联的平台专家
- 🆕 独立实现: 无对应平台模块
🔴 检查点 0：模块清单确认
必须暂停，向用户展示以下表格并等待确认：
## 📋 模块清单确认
**Skill 层级**: {应用层/平台层}
**应用名**: {AppName}
**命名前缀**: `{app}-`
**模块总数**: {N} 个
**计划分批**: {ceil(N/6)} 批（每批 ≤6 个模块）
| # | 模块 | Skill 名称 | 继承类型 | 关联平台专家 |
|---|------|-----------|----------|-------------|
| 1 | ... | `{app}-{mod}-expert` | 🔄/🆕 | ... |
请确认是否正确，可以增删模块、修改命名、调整继承类型。
使用 ask_questions 让用户确认：
- header: "模块确认"
- question: "请看上面的模块列表，确认划分是否合理"
- 选项A（推荐）: "没问题，继续生成"
- 选项B: "需要修改" (allowFreeformInput: true)
Step 1：分批研究 + 生成
1a. 读取模版和参考
多根工作区模式：
- 读取
templates/skills/_templates/module-expert-skill.md — 获取标准模版结构
- 读取一个已有的同层级 Skill 作为格式参考：
- 应用层:
templates/skills/app-*-expert/SKILL.md
- 平台层:
templates/skills/{{PLATFORM_PREFIX}}-*-expert/SKILL.md（若无，到目标项目 .github/skills/ 找）
纯目标项目模式：
- MCP
get_file_content(repo=AdvAppCommonKnowledge, path=templates/skills/_templates/module-expert-skill.md) — 远程读取模版
- 如目标项目
.github/skills/_templates/module-expert-skill.md 存在（GUI 部署时已复制），优先用本地版本
- 格式参考同上，优先本地
.github/skills/ 下已有的 Skill
1b. 分批深度研究
将模块按 每批 ≤6 个 分组，对每一批使用 runSubagent 进行深度研究。
Subagent 研究指令模板：
请对以下 {N} 个模块进行深度研究，目标项目在 {target_project_root}。
模块列表：{module1}, {module2}, ...
对每个模块，请调查以下内容并输出结构化报告：
1. **目录结构**: 列出各代码层级目录下的相关子目录和文件数量
2. **关键类清单**: 找出 3-8 个核心类/接口名称（精确大小写）
3. **命名空间/包名**: 查找模块的命名空间或包名模式
4. **导出/公开接口**: 查找公开接口和导出符号
5. **常见拼写陷阱**: 搜索非标准拼写
{tech_specific_instructions}
技术栈特定研究指令 ({tech_specific_instructions}):
| 来源 | 注入内容 |
|---|
| project-profile.json | 根据 techStack 和 layers 动态构建 |
| 平台默认（无 profile） | 6. 命名空间宏: {{PLATFORM_NS_PREFIX}}_*_BEGIN_NAMESPACE + 7. 导出宏: *_Export + 8. XML 配置关联 |
| C#/.NET 项目 | 6. 命名空间: namespace 声明 + 7. DI 注册: AddScoped/AddTransient |
| Python 项目 | 6. 包结构: __init__.py 导出 + 7. 装饰器: @app.route/@router.post |
| Java 项目 | 6. 包名: package 声明 + 7. 注解: @Service/@Controller/@Bean |
| TypeScript 项目 | 6. 模块导出: export default/export class + 7. 路由: @Controller/@Get/@Post |
研究报告产出到对话中，不写文件。每批完成后输出进度。
1c. 基于研究逐批生成 SKILL.md
依据研究报告 + 模版结构，为当前批次的每个模块生成 SKILL.md。
生成位置:
- 多根工作区模式:
templates/skills/{app}-{module}-expert/SKILL.md（工具项目内）
- 纯目标项目模式:
.github/skills/{app}-{module}-expert/SKILL.md（目标项目内，本地预览）
生成规则：
- YAML frontmatter 必填：
name 与目录名相同，description 含 ≥3 触发关键词
- 必填章节 — 参考
module-expert-skill.md 的标记系统（[通用]/[应用必填]/[平台必填]）
- 精确性要求（v3 核心原则）：
- 类名、文件路径必须来自研究报告的实际扫描结果
- 禁止编造或推测不存在的符号
- 拼写陷阱必须有具体文件名为证
- 行数控制: 应用层 ≤ 120 行 / 平台层 ≤ 150 行
- 内容完整性红线（强制）：
- ❗ 模板格式不可简化: 执行声明规范、必填章节等固定格式必须完整保留，禁止压缩或省略
- ❗ 必要内容不可删减: 场景入口、陷阱条目、依赖行、配置映射等经验证的内容不得为了行数限制而删除或合并
- ✅ 超限时拆分到 reference: 若行数超限，将较大的独立章节（如运行时配置映射、大型表格）拆分到
references/ 目录
- 拆分后在 SKILL.md 中保留指针:
📖 详细内容见 \references/xxx.md``
- 业务规则: 框架完整但内容标记
🔴 TODO: 待补充
每生成 3 个 Skill 后输出进度：
✅ 批次 {B}/{total}: 已生成 {app}-{mod1}-expert, {app}-{mod2}-expert, {app}-{mod3}-expert
1d. [应用层] 配置文件自动填充
仅应用层执行，平台层跳过。配置格式从模板 v4 的配置发现规则获取。
配置发现策略：
- 如有
project-profile.json: 使用 configDiscovery.format 和 configDiscovery.basePath
- XML: 搜索
{basePath}/**/*.xml，提取 <Operation>/<Handler> 等节点
- YAML/JSON: 搜索
{basePath}/**/*.{yaml,yml,json}，提取路由/服务配置
- none: 跳过此步
- 平台默认（无 profile）: 搜索 XML 配置文件
- 搜索路径:
file_search("**/appdata/*/config/[你的配置目录]/[配置文件]")
- 核心文件:
[后端配置文件]、BE/WorkflowController.xml、[前端命令配置]
- 提取内容: 按模块名 grep 相关 Operation/Widget/Model 注册项
- 自动填充: 将提取结果写入各 SKILL.md 的「运行时配置映射」章节，标记 🤖
1e. 自动 lint 验证
所有 Skill 生成完毕后，自动在终端运行 lint 检查：
python scripts/lint_skills.py --skill {app}-*-expert
lint 检查项：
- YAML frontmatter 必填字段（name + description）
- 触发词冲突检测（与现有 Skill 无重复）
- references 文件引用有效性
- 名称规范（连字符格式，≤64 字符）
将 lint 结果纳入 CP1 评分卡。如果有 lint 错误，先自动修复，修复后重新 lint，确认全部通过后再进入 CP1。
🔴 检查点 1：生成质量确认
必须暂停，向用户展示 lint 结果 + 质量评分卡：
## 📊 生成质量评分卡
### Lint 检查
✅ 全部通过（{N} 个 Skill, 0 个错误）
### 内容评分
| Skill | 行数 | frontmatter | 场景入口 | 上下游 | 得分 |
|-------|------|:-----------:|:--------:|:------:|------|
| `{app}-xxx-expert` | 95 | ✅ | ✅ 3个 | ✅ | 4/4 |
| ... | | | | | |
**评分标准**:
- frontmatter: name + description（含 ≥3 触发关键词）
- 行数: 应用层 ≤120 / 平台层 ≤150
- 场景→入口: ≥ 2 个场景有搜索关键词
- 上下游依赖: 标注了影响程度
> ⚠️ 所有业务规则已标记 🔴 TODO，待领域专家后续补充
使用 ask_questions 让用户确认：
- header: "质量确认"
- question: "请看评分卡，如有不满意的可以在输入框里告诉我哪个 Skill 需修改"
- 选项A（推荐）: "都没问题，继续"
- 选项B: "需要调整" (allowFreeformInput: true)
Step 2：注册类别 + 配置
2a. 编辑 skill_categories.json
多根工作区模式 — 本地编辑 data/skill_categories.json：
"{app}": {
"display_name": "{app}",
"prefixes": ["{app}-"],
"description": "{AppName} 应用/平台",
"default_selected": false
}
在 presets 中添加对应预设：
"{AppName}应用开发": ["platform", "{app}"]
纯目标项目模式 — 通过 MCP create_commit 的 search/replace 模式远程修改：
- 先 MCP
get_file_content 读取当前 skill_categories.json 内容
- 用 search/replace 在
"categories" 和 "presets" 中各插入一条
2b. 验证 + 部署说明
执行 python -c "import json; ..." 验证 skill_categories.json 配置正确、{app}-* Skills 数量匹配。
多根工作区模式 — 部署到目标项目：使用 ask_questions 询问是否自动部署：
- header: "自动部署"
- question: "是否立即将 Skills 部署到目标项目？"
- 选项A（推荐）: "是，自动部署"
- 选项B: "否，我稍后手动运行 GUI"
如果选择自动部署，在工具项目根目录执行：
python scripts/deploy_skills.py --target-path "{target_project_root}" --categories platform,{app} --force
💡 其他开发者需各自运行 GUI 或 CLI 部署。
纯目标项目模式：Skill 已直接生成在 .github/skills/ 下，无需额外部署。
2c. 更新用户偏好（user_preferences.json）
读取 data/user_preferences.json，在 selected_skill_categories 数组中追加 "{app}"（如果不存在的话），确保 GUI 下次启动时默认勾选新应用类别。
🔴 检查点 2：交付确认
必须暂停，向用户展示以下交付清单：
## 📦 交付清单
**应用名**: {AppName}
**Skill 数量**: {N} 个模块
### 生成的文件
| 文件路径 | 行数 | 类型 |
|---------|------|------|
| `templates/skills/{app}-xxx-expert/SKILL.md` | ... | SKILL.md |
| `templates/skills/{app}-xxx-expert/references/xxx.md` | ... | reference |
| ... | | |
### 配置注册
| 配置文件 | 变更内容 |
|---------|---------|
| `data/skill_categories.json` | 新增 `{app}` 分类 + `"{AppName}应用开发"` 预设 |
### 部署方式
重启 VS Code 后，通过 `#{app}-xxx-expert` 调用。
每位开发者需各自运行 GUI 工具部署 Skill。
展示完清单后，必须使用 ask_questions 弹出两个交互选项：
选择 1 — PR 操作：
- header: "提交PR"
- question: "Skill 已生成完毕。是否自动创建 PR 并通知审阅人？"
- 选项A（推荐）: "创建 PR 并飞书通知审阅人"
- 选项B: "只创建 PR，不发通知"
- 选项C: "跳过，我手动处理"
选择 2 — PR 审阅人（仅选择 A/B 时展示）：
- header: "审阅人"
- question: "PR 审阅人（默认从 shared_config.json 读取）"
- 选项A（推荐）: "YourName (your.email@example.com)" — 从
shared_config.json 的 notification_recipients 动态读取
- allowFreeformInput: true — 用户可输入其他审阅人姓名或邮箱
⚠️ 禁止跳过此 ask_questions 步骤。展示文件清单 ≠ 交付确认完成，必须等用户通过交互选项选择后才算 CP2 完成。
A/B → Step 3 | C → 输出部署说明，结束
Step 3：[可选] 提交 PR + 飞书通知
📚 实现原理参考: read_file("references/pr-notification.md") — Step 3 执行前必须读取！
根据 Step 0-pre 选择的运行模式，执行对应的 PR 创建流程。
根据 CP2 的选择确定通知模式：选项 A → PR 并通知 | 选项 B → 仅 PR
3-local. 多根工作区模式：本地脚本
在工具项目根目录执行（通过 run_in_terminal）：
powershell -ExecutionPolicy Bypass -File scripts/create_skill_pr.ps1 `
-AppName "{AppName}" -AppPrefix "{app}" -ModuleCount {N} `
-Mode "{PRAndNotify|PROnly}"
脚本输出 ===RESULT_JSON_BEGIN===/===RESULT_JSON_END=== 之间的 JSON 摘要。
退出码: 0=全成功, 1=配置错, 2=Git 失败, 3=PR 失败, 4=部分成功。
3-remote. 纯目标项目模式：MCP 远程操作
使用 azureDevOpsHSW MCP server（工具仓库在 HSW Collection）：
- 创建分支: MCP
create_branch — repo AdvAppCommonKnowledge, source master, new skill/{app}-experts
- 推送文件: MCP
create_commit — 将本地 .github/skills/{app}-*-expert/ 内容推送到 templates/skills/{app}-*-expert/
- 新文件用
--- /dev/null 格式的 unified diff
skill_categories.json 用 search/replace 模式修改
- 创建 PR: MCP
create_pull_request — reviewers 从 CP2 用户选择获取
- 飞书通知（如选择 A）: 通过飞书 MCP 或
create_skill_pr.ps1 的飞书 API 发送卡片消息
🔴 任何失败都不阻断，降级为提示用户手动处理。详见 references/pr-notification.md 中的错误处理表。
🔴 检查点 3：最终交付确认
展示最终交付结果：Skill 文件列表 + PR 链接 + 飞书通知状态 + 后续事项（业务规则 TODO、等待审阅、GUI 部署）。
进度模板
每次向用户展示消息时，在开头显示当前进度：
📋 Skill 向导 — {AppName}（{层级}）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Step 0: 环境 + 信息收集
✅ CP0: 模块清单确认 (用户已确认)
⭕ Step 1: 分批研究 + 生成 (批次 2/4, 已完成 8/20)
⬜ CP1: 生成质量确认
⬜ Step 2: 注册 + 配置
⬜ CP2: 交付确认（含 PR 选择）
⬜ Step 3: 提交 PR + 飞书通知
⬜ CP3: 最终交付确认
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
状态图标: ✅ 完成 | ⭕ 进行中 | ⬜ 未开始
错误处理
| 错误场景 | 处理方式 |
|---|
| 工作区未包含目标项目且无 HSW MCP | 引导用户二选一：添加工具项目到工作区 或 运行 GUI 配置 MCP |
| 用户未提供应用名 | 直接询问，不要猜测 |
| 没有找到模块清单文件 | 扫描目录结构推断，或询问用户 |
skill_categories.json 已有同名类别 | 使用 ask_questions 询问是否覆盖 |
| 生成的 Skill 超过行数上限 | 将较大的独立章节拆分到 references/ 目录，SKILL.md 中保留 📖 ... 见 references/xxx.md 指针。禁止通过简化模板格式或删减必要内容来降低行数 |
templates/skills/{app}-* 目录已存在 | 使用 ask_questions 询问是否覆盖 |
| runSubagent 研究报告信息不足 | 补发更具针对性的研究指令 |
| DevOps PAT 未配置 | 提示用户运行 GUI 工具配置 PAT |
git push 失败（无远程/权限不足） | 跳过 PR 创建，输出部署说明 |
| DevOps PR API 返回 401/403 | 先检查 PAT Collection 是否匹配 |
MCP create_commit search 不匹配 | 先 get_file_content 读取最新内容，调整 search 文本 |
MCP azureDevOpsHSW 不可用 | 降级提示运行 GUI 配置或手动处理 |
| lint 检查发现错误 | 自动修复后重新 lint，全部通过才进 CP1 |
| 飞书通知收件人未配置 | 使用 CP2 用户输入的审阅人邮箱，或提示补充配置 |
user_preferences.json 被外部覆盖 | 写入前先读取最新内容，合并而非全量覆盖 |
skill_categories.json 被外部覆盖丢失类别 | 写入前先读取，确保新增类别不会覆盖已有的其他类别 |
| 飞书 MCP 不可用 | 不阻断流程，提示用户手动发送 PR 链接 |
参考文件
- 统一模版:
read_file("templates/skills/_templates/module-expert-skill.md") — Step 1 前读取（纯目标项目模式用 MCP get_file_content）
- 质量标准:
read_file("references/details.md")
- PR + 通知:
read_file("references/pr-notification.md") — Step 3 前必须读取
- 格式参考: 任意
templates/skills/app-*-expert/SKILL.md（应用层）或 {{PLATFORM_PREFIX}}-*-expert/SKILL.md（平台层）
