| name | skill-generator |
| description | 根据用户任务和画像，分析所需能力并生成子技能。使用场景：(1) 指挥官创建新任务时调用，(2) user-profile 确认后可选调用生成 u_ 技能，(3) 用户请求技能分析时使用。每个任务生成 2-3 个核心 k_ 技能，u_ 技能总数保持在 5 个以内。 |
技能生成器
分析任务所需能力，生成可复用的技能单元。
核心原则：聚焦核心能力，避免过度拆解。
角色定位
skill-generator 是技能分析师，专注于任务分析和技能生成。
职责边界
| ✅ 应该做 | ❌ 不应该做 |
|---|
| 分析任务描述，识别所需能力 | 管理任务状态（active/completed） |
| 读取 .info/usr.json 获取用户画像 | 直接修改 tasks.json |
| 生成技能文件（SKILL.md） | 创建任务结果目录 |
| 决定生成哪些技能及数量 | 协调技能执行顺序 |
| 从画像中提取经验生成 u_ 技能 | 检查用户画像新鲜度 |
| 返回技能列表给调用者 | 执行生成的技能 |
说明：tasks.json 的更新由 track-skills-change.sh hook 自动完成，skill-generator 不直接操作。
与其他 Skills 的关系
┌─────────────────────────────────────────┐
│ skill-generator │ (技能分析师)
│ ┌───────────────────────────────────┐ │
│ │ 输入: 任务描述 + .info/usr.json │ │
│ │ 输出: k_ 技能文件 + u_ 技能文件 │ │
│ └───────────────────────────────────┘ │
└────────────────▲────────▲────────────────┘
│ │
┌─────────┴──┐ ┌┴──────────┐
↓ ↓ ↓ ↓
┌───────────────┐ ┌──────────────┐
│ user-profile │ │ commander │
│ (可选调用) │ │ (主调用者) │
│ u_ 技能生成 │ │ k_ 技能生成 │
└───────────────┘ └──────────────┘
- 对 user-profile：
- 只读画像数据，不修改
- 可被 user-profile 调用（经验模式）：生成 u_ 技能
- 对 commander：接收任务描述，返回技能列表（任务模式）
- 独立性：不管理任务生命周期，只负责分析
- 输出格式：返回标准化的技能列表供调用者使用
调用方式
任务模式（由 commander 调用）
commander → skill-generator 交互流程：
1. 用户运行: /commander start [任务描述]
2. commander 检查用户画像
3. commander 调用: Skill("skill-generator", 任务描述)
4. skill-generator 分析任务并返回分析结果
5. 【第一次确认】AskUserQuestion 确认分析结果
6. skill-generator 规划技能并返回技能计划
7. 【第二次确认】AskUserQuestion 确认技能计划
8. 用户确认后，skill-generator 创建技能文件
9. hook 系统自动注册到 tasks.json
输入格式：
- 任务描述（自然语言）
- 用户画像（自动读取
.info/usr.json）
输出格式：
- 技能生成计划（供用户确认）
- 技能文件（
.claude/skills/k[0-9]_*/SKILL.md）
经验模式（由 user-profile 调用）
user-profile → skill-generator 交互流程：
1. 用户运行: /user-profile
2. user-profile 分析 info/ 目录
3. user-profile 可选调用: Skill("skill-generator", "--mode=experience")
4. skill-generator 返回: u_ 技能生成计划
5. 用户确认后生成 u_ 技能
输入格式：
- 模式标识：
--mode=experience
- 用户画像的 experience 维度
输出格式：
- u_ 技能文件（
.claude/skills/u_*/SKILL.md）
直接调用（用户手动）
用户也可以直接调用进行分析：
/skill-generator 分析"搭建 Next.js 博客"需要的技能
处理流程
任务模式 (k_ 前缀) - 技能分析
原则：每个任务生成 2-3 个 k_ 技能作为步骤
任务步骤列表 = k_ 技能（2-3 个）
k_ 技能生成时参考：
├── p_ 技能（验证技能）→ 优先参考其内容
├── u_ 技能（用户经验）→ 其次参考其内容
└── 能力空白 → 创建新内容
- 读取用户画像
.info/usr.json
- 分配任务编号（k01, k02, ...）
- 分析任务所需的核心能力
- 识别关键技术点：框架、语言、工具、领域知识
- 检查 p_ 技能池：查找已验证的参考技能（最多10个）
- 检查 u_ 技能池：查找用户经验技能（最多5个）
- 确定能力空白：找出需要创建的新技能
- 📝 输出推理块：将分析过程写入
results/k01/.reasoning.md（自动合并到全局日志）
- 【第一次确认】分析结果确认：使用 AskUserQuestion 确认分析结果
- 展示：任务类型、技术栈、复杂度评估
- 展示：匹配到的参考技能（p_ 技能、u_ 技能）
- 展示：识别的能力空白
- 技能生成规划：确定生成 2-3 个 k_ 技能的方案
- 📝 输出推理块：将规划过程写入
results/k01/.reasoning.md（自动合并到全局日志）
- 【第二次确认】技能计划确认：使用 AskUserQuestion 确认技能生成计划
- 展示：拟生成的 k_ 技能列表
- 展示：每个技能的参考来源
- 生成 k_ 技能：
- 优先参考 p_ 技能内容生成
- 其次参考 u_ 技能内容生成
- 最后创建全新内容
- 重要：在每个 k_ 技能末尾添加"完成后续处理"章节，包含 AskUserQuestion
- 📝 输出推理块：将生成过程写入
results/k01/.reasoning.md（自动合并到全局日志）
- 创建
results/k01/ 目录和文件
- 更新
.info/tasks.json
数量控制：
- k_ 技能少于 2 个：任务太简单，直接执行
- k_ 技能多于 3 个：任务太复杂，建议拆分或合并
经验模式 (u_ 前缀) - 经验提取
原则：总数保持在 5 个以内
- 读取用户画像中的
experience 维度
- 评估每个经验的复用价值
- 是否是核心技能
- 是否有通用性
- 是否有独特的最佳实践
- 用户确认：展示拟生成的 u_ 技能列表，等待确认
- 只保留高价值的经验，生成
u_ 技能
- 技能内容包含：执行流程、最佳实践、踩坑记录
- 更新
.info/tasks.json 的 user_skills 字段
数量控制：
- 超过 5 个时：保留最近、最常用的 5 个
- 归档低频经验到
results/archived/u_skills/
子技能命名
详见 命名规范：
任务模式 (k_ 前缀)
| 类型 | 模式 | 示例 |
|---|
| 初始化 | k[任务]_init_[项目] | k01_init_project |
| 配置 | k[任务]_config_[功能] | k01_config_mdx |
| 创建 | k[任务]_create_[组件] | k01_create_layout |
| 实现 | k[任务]_implement_[功能] | k01_implement_auth |
| 添加 | k[任务]_add_[功能] | k01_add_search |
| 删除 | k[任务]_remove_[功能] | k01_remove_deps |
| 更新 | k[任务]_update_[内容] | k01_update_deps |
| 修复 | k[任务]_fix_[问题] | k01_fix_routing |
| 测试 | k[任务]_test_[模块] | k01_test_api |
| 重构 | k[任务]_refactor_[模块] | k01_refactor_auth |
经验模式 (u_ 前缀)
| 类型 | 模式 | 说明 | 示例 |
|---|
| 技术栈经验 | u_[tech]_[feature] | 优先：核心技术+特性 | u_react_hooks, u_next_auth |
| 项目经验 | u_[project]_[purpose] | 备选：知名项目+用途 | u_blog_mdx, u_fastapi_crud |
| 工具经验 | u_[tool]_[usage] | 备选：工具+使用场景 | u_docker_deploy, u_git_workflow |
命名优先级：技术栈 > 项目 > 工具
输出结构
.claude/skills/
├── p_nextjs_mdx/SKILL.md # 验证技能池（参考来源，≤10个）
├── p_docker_deploy/SKILL.md # 验证技能池
├── p_research_open_source/SKILL.md # 验证技能池
├── u_react_hooks/SKILL.md # 用户经验池（参考来源，≤5个）
├── u_docker_deploy/SKILL.md # 用户经验池
├── u_fastapi_crud/SKILL.md # 用户经验池
├── k01_init_project/SKILL.md # 任务技能（实际执行，2-3个/任务）
├── k01_config_mdx/SKILL.md # 任务技能
└── k02_design_schema/SKILL.md # 任务技能
results/k01/
├── README.md # 任务总览
├── plan.md # 任务计划
├── execution.md # 执行记录
├── notes.md # 笔记
└── artifacts/ # 生成的文件
技能内容生成方法论
k_ 技能生成步骤
1. 任务分析
输入：任务描述（自然语言）
输出：任务类型、技术栈、复杂度评估
任务: "搭建 Next.js 博客"
↓
分析结果:
- 类型: Web 开发
- 技术栈: Next.js, MDX, TypeScript
- 复杂度: 中等
- 预计步骤: 3 个
2. 技能匹配
输入：任务分析结果
输出：参考技能列表
p_ 技能池检查:
- p_nextjs_mdx ✓ 匹配 (博客搭建)
- p_docker_deploy ✗ 不相关
- p_research_open_source ✗ 不相关
u_ 技能池检查:
- u_react_hooks ✓ 匹配 (组件状态)
- u_git_workflow ✗ 不直接相关
3. 技能规划
输入：参考技能 + 任务需求
输出：2-3 个 k_ 技能方案
技能规划:
1. k01_init_project (参考 p_nextjs_mdx)
- 初始化 Next.js 项目
- 配置 TypeScript 和 Tailwind
2. k02_config_mdx (参考 p_nextjs_mdx)
- 安装 MDX 依赖
- 配置 MDX 解析器
3. k03_create_layout (全新创建)
- 创建页面布局
- 实现文章列表和详情页
4. 内容生成
输入：技能规划 + 用户画像
输出：完整的 SKILL.md 文件
基于用户画像定制:
- tech_stack.primary_languages → 使用 TypeScript 示例
- preferences.code_style → 遵循既定命名规范
- goals.pain_points → 避开已知的 MDX 配置陷阱
内容生成原则
| 原则 | 说明 |
|---|
| 具体化 | 步骤描述具体可执行，避免模糊表述 |
| 可验证 | 每个步骤有明确的完成标准 |
| 完整性 | 包含从开始到结束的完整流程 |
| 用户导向 | 根据用户画像定制内容和风格 |
| 参考溯源 | 标注参考的 p_/u_ 技能来源 |
| 自动继续 | k_ 技能末尾必须包含"完成后续处理"章节，询问是否执行下一步 |
质量检查
生成技能后，检查：
□ YAML 前置元数据完整
□ 角色定位清晰
□ 执行流程完整
□ 包含预期输出
□ 有错误处理说明
□ 标注参考来源
□ 符合命名规范
□ 格式正确
□ k_ 技能包含"完成后续处理"章节
□ k_ 技能 YAML 包含 task_id, step_index, total_steps, next_skill
□ k_ 技能使用 AskUserQuestion 询问是否继续
详见 技能结构清单。
技能生成参考策略
新任务分析
↓
收集能力需求
↓
检查 p_ 技能池（最多10个）
↓
找到匹配 → 参考内容生成 k_（记录来源）
↓
未找到 → 检查 u_ 技能池（最多5个）
↓
找到匹配 → 参考内容生成 k_（记录来源）
↓
未找到 → 创建全新内容生成 k_
↓
汇总：生成 2-3 个 k_ 技能
注意：步骤列表只包含 k_ 技能（2-3个），p_ 和 u_ 是生成 k_ 时的参考来源
技能参考机制
当生成任务技能时，检查是否有可参考的 p_ 技能或 u_ 技能：
1. 参考逻辑
1. 分析任务关键词（技术栈、工具、领域）
2. 在 p_ 技能池中搜索匹配项
3. 在 u_ 技能池中搜索匹配项
4. 确定需要创建的能力空白
2. 匹配示例
| 任务描述关键词 | 可能匹配的参考技能 |
|---|
| 调研、研究、开源项目 | p_research_open_source |
| 文章、撰写、技术博客 | p_article_techwriter |
| 部署、Docker、容器化 | p_docker_deploy |
| Next.js、MDX、博客 | p_nextjs_mdx |
| React 组件、状态管理 | u_react_hooks |
3. 参考后的处理
技能生成后会：
- 在 k_ 技能文档中标注参考来源
- hook 系统自动更新相关技能的 usage_count
- 记录技能关联到 tasks.json
4. 分析结果展示
┌─────────────────────────────────────────┐
│ 技能分析完成 │
├─────────────────────────────────────────┤
│ ✅ k01_init_project │
│ 参考: p_nextjs_mdx (已验证，复用3次) │
│ │
│ ✅ k02_config_auth │
│ 参考: u_react_hooks (用户经验) │
│ │
│ ✅ k03_ssg_deployment │
│ 全新内容创建 │
└─────────────────────────────────────────┘
技能生成决策树
任务分析
│
收集能力需求（2-3个）
│
┌─────────────┼─────────────┐
│ │ │
检查 p_ 技能 检查 u_ 技能 确定空白
(技能池≤10) (技能池≤5)
│ │ │
┌────┴────┐ ┌────┴────┐ │
│ │ │ │ │
找到参考 未找到 找到参考 未找到 ↓
│ │ │ │ 创建新内容
↓ │ ↓ │ ↓
└─────────┴───┴─────────┴──────┘
│
【第一次确认】分析结果
│
用户确认分析正确？
├─ 否 → 调整分析 → 重新确认
└─ 是 → 继续
│
规划 k_ 技能方案（2-3个）
│
【第二次确认】技能计划
│
用户确认技能方案？
├─ 否 → 调整规划 → 重新确认
└─ 是 → 继续
│
生成 k_ 技能文件
关键点：
- 步骤列表只包含 k_ 技能
- p_ 和 u_ 是生成 k_ 时的参考来源
- 数量限制：k_ 技能 2-3 个/任务
- 新增：两次确认流程（分析结果确认 + 技能计划确认）
推理块格式规范
在执行关键步骤时，使用以下格式输出推理过程，以便用户了解"用了什么方法"和"得到了什么结论"：
### 步骤名称
<reasoning>
🎯 目标：[当前步骤要达成什么]
🔍 方法：[使用了什么方法/工具/策略]
💡 发现：[观察到了什么/得到了什么数据]
✅ 决策：[做出了什么决策及理由]
</reasoning>
**执行**：[具体操作步骤]
推理块自动捕获机制
推理块会通过 Hook 系统自动捕获并维护：
| Hook | 触发时机 | 作用 |
|---|
update-reasoning-on-task.sh | TaskCreate/TaskUpdate | 任务操作时自动更新推理日志 |
capture-reasoning.sh | Write/Edit .reasoning.md | 捕获推理块内容 |
fix-reasoning.sh | SessionStart | 修复损坏的推理文件 |
重要：
- 推理块写入
results/k01/.reasoning.md（任务级）
- 同时合并到
.info/.reasoning.md（全局，活跃任务）
- 每次任务操作（TaskCreate/TaskUpdate）都会自动触发更新
必须输出推理块的时机
在以下关键步骤必须输出推理块：
- 任务分析完成时 - 记录分析结果和参考技能
- 技能规划完成时 - 记录技能生成计划
- 技能生成完成时 - 记录生成过程和结果
示例：
### 1. 分析任务能力需求
<reasoning>
🎯 目标：识别"搭建 Next.js 博客"任务所需的核心能力
🔍 方法：提取关键词 → 匹配技能池 → 识别空白
💡 发现：
- 技术栈：Next.js, MDX, TypeScript
- 匹配到 p_nextjs_mdx（验证技能，已复用 3 次）
- 能力空白：页面布局、SSG 部署
✅ 决策：生成 3 个 k_ 技能，参考 p_nextjs_mdx
</reasoning>
**执行**：
- 读取 `.info/usr.json`
- 搜索 `p_*/SKILL.md`
- 确定技能生成方案
k_ 前缀技能的内容结构
---
name: k01_init_project
description: k01 任务：初始化 Next.js 项目。这是任务"搭建 Next.js 博客"的第 1/3 步骤。包含：创建项目、配置 TypeScript、安装 Tailwind CSS。
task_id: k01
step_index: 0
total_steps: 3
next_skill: k01_config_mdx
---
# k01_init_project
任务 k01 的第 1 步：初始化 Next.js 项目。
## 阶段目标
创建 Next.js 项目基础结构，完成开发环境配置。
## 执行流程
### 1. 创建项目
```bash
npx create-next-app@latest blog --typescript --tailwind --app
2. 验证安装
cd blog && npm run dev
预期输出
完成标准
完成后续处理
✅ 阶段完成！
当前进度：1/3
- ✓ k01_init_project (本步骤)
- ⏭ k01_config_mdx (下一步)
- ⏳ k01_create_layout (待执行)
使用 AskUserQuestion 询问用户：
阶段 1/3 已完成：初始化 Next.js 项目
下一步是：k02_config_mdx (配置 MDX)
- 安装 @next/mdx 和相关依赖
- 配置 MDX 解析器和组件
- 设置 frontmatter 支持
请选择：
- 继续执行下一步 (k02_config_mdx)
- 查看任务详情 (/commander progress k01)
- 暂停，稍后手动继续 (/commander continue k01)
实现方式：
使用 AskUserQuestion 工具，参数：
{
"questions": [{
"question": "阶段 1/3 已完成。是否继续执行下一步：k02_config_mdx (配置 MDX)？",
"header": "继续任务",
"options": [
{"label": "继续下一步", "description": "执行 k02_config_mdx：配置 MDX 解析器和组件"},
{"label": "查看进度", "description": "显示任务详细进度和执行记录"},
{"label": "暂停", "description": "稍后使用 /commander continue k01 继续执行"}
],
"multiSelect": false
}]
}
进度更新（重要）：
在技能执行完成前，必须调用 TaskUpdate 更新任务进度：
# 完成当前步骤后，更新任务进度到下一步
TaskUpdate(
taskId="k01",
subject="已完成 k01_init_project",
status="in_progress"
)
这将自动：
- 更新 tasks.json 中的 current_step（从 0 → 1）
- 触发 update-status.sh 更新 statusline
- 触发 update-reasoning-on-task.sh 更新推理日志
参考来源
## u_ 前缀技能的内容结构
```markdown
---
name: u_blog_mdx
description: 使用 Next.js + MDX 构建博客的已验证方案。包含：初始化配置、MDX 集成、动态路由、SSG、代码高亮。当用户需要搭建博客、文档站点、内容管理系统时使用。
---
# u_blog_mdx
使用 Next.js App Router + MDX 构建博客的执行方案。
## 执行流程
### 1. 初始化项目
```bash
npx create-next-app@latest blog --typescript --tailwind --app
2. 安装依赖
...
最佳实践
| 实践 | 说明 |
|---|
| SSG | 使用 generateStaticParams 预渲染 |
| 代码高亮 | rehype-prism-plus |
已知坑点
| 问题 | 解决方案 |
|---|
| MDX 组件报错 | 声明 'use client' |
| 远程图片不显示 | 配置 images.domains |
关联项目
- k01: 搭建 Next.js 博客（2025-01）
## tasks.json 结构
```json
{
"next_id": 2,
"tasks": {
"k01": {
"id": "k01",
"name": "任务名称",
"type": "web",
"status": "active",
"steps": ["k01_mdx_integration", "k01_dynamic_routing"],
"current_step": 0,
"created_at": "2026-01-27T16:00:00Z"
}
},
"user_skills": {
"u_next_mdx": {
"name": "Next.js + MDX 博客",
"level": "proficient",
"created_at": "2026-01-28T10:00:00Z",
"related_tasks": ["k01"],
"usage_count": 3
}
},
"proven_skills": {},
"archived_u_skills": ["u_old_react_classic"]
}
字段说明：
tasks.k01.steps: 任务步骤列表（只包含 k_ 技能，2-3 个）tasks.k01.current_step: 当前进度索引user_skills: 用户经验技能池（供生成 k_ 时参考），最多 5 个proven_skills: 验证技能池（供生成 k_ 时参考），最多 10 个archived_u_skills: 已归档的低频 u_ 技能列表usage_count: 技能被参考/复用次数，用于归档决策
基于画像的定制
生成的子技能会根据用户画像定制：
| 画像字段 | 用途 |
|---|
tech_stack.primary_languages | 使用熟悉的编程语言 |
preferences.code_style | 遵循命名和格式规范 |
preferences.response_format | 适配代码优先/解释优先 |
behavioral_patterns.work_style | 采用迭代式/规划式开发 |
goals.pain_points | 避开已知的技术难点 |
错误处理
| 场景 | 处理方式 |
|---|
| 用户画像不存在 | 提示运行 /user-profile |
| k_ 技能少于 2 个 | 任务过于简单，可直接执行 |
| k_ 技能多于 3 个 | 任务过于复杂，建议拆分或合并技能 |
| u_ 技能超过 5 个 | 归档低频经验，保留最常用的 5 个 |
| p_ 技能超过 10 个 | 归档低频技能，保留最常用的 10 个 |
| 用户取消生成 | 恢复 tasks.json 的 next_id |
用户确认流程
第一次确认：分析结果确认
在分析完任务后、规划技能前，使用 AskUserQuestion 确认分析结果：
任务"搭建 Next.js 博客"的分析完成：
┌─────────────────────────────────────────┐
│ 📊 分析结果 │
├─────────────────────────────────────────┤
│ 任务类型: Web 开发 │
│ 技术栈: Next.js, MDX, TypeScript │
│ 复杂度: 中等 │
│ 预计步骤: 3 个 │
├─────────────────────────────────────────┤
│ 🎯 匹配的参考技能 │
│ ✅ p_nextjs_mdx (验证技能，复用3次) │
│ ✅ u_react_hooks (用户经验) │
├─────────────────────────────────────────┤
│ 📋 能力空白 │
│ • 页面布局创建 │
│ • SSG 部署配置 │
└─────────────────────────────────────────┘
分析结果是否正确？
- 确认，继续规划技能
- 调整：修改分析结果
- 取消，重新分析
实现方式：
{
"questions": [{
"question": "任务分析完成。类型：Web 开发，技术栈：Next.js + MDX，复杂度：中等。匹配到参考技能：p_nextjs_mdx, u_react_hooks。是否确认继续？",
"header": "确认分析",
"options": [
{"label": "确认继续", "description": "分析结果正确，继续规划技能方案"},
{"label": "调整分析", "description": "修改技术栈或复杂度评估"},
{"label": "取消", "description": "取消当前任务"}
],
"multiSelect": false
}]
}
第二次确认：技能计划确认
技能规划完成后，使用 AskUserQuestion 确认技能生成计划：
任务"搭建 Next.js 博客"的技能规划完成：
将生成 3 个 k_ 技能：
┌─────────────────────────────────────────┐
│ ✅ k01_init_project │
│ 参考: p_nextjs_mdx (已验证，复用3次) │
│ │
│ ✅ k02_config_auth │
│ 参考: u_react_hooks (用户经验) │
│ │
│ ✅ k03_ssg_deployment │
│ 全新内容创建 │
└─────────────────────────────────────────┘
是否接受此方案？
- 接受，开始生成技能
- 调整：修改技能列表
- 取消，重新规划
步骤列表确认（已废弃，由上述两次确认替代）
技能分析完成后，使用 AskUserQuestion 展示方案：
任务"搭建 Next.js 博客"的技能分析完成：
将生成 3 个 k_ 技能：
┌─────────────────────────────────────────┐
│ ✅ k01_init_project │
│ 参考: p_nextjs_mdx (验证技能) │
│ │
│ ✅ k02_config_auth │
│ 参考: u_react_hooks (用户经验) │
│ │
│ ✅ k03_ssg_deployment │
│ 全新内容创建 │
└─────────────────────────────────────────┘
是否接受此方案？
- 接受，开始生成技能
- 调整：修改技能列表
- 取消，重新分析
任务复杂度异常确认
当识别到需要超过 3 个 k_ 技能时：
任务分析完成，但识别到需要 5 个 k_ 技能。
超过 3 个上限，请选择处理方式：
- 拆分任务：将大任务拆分为 2-3 个子任务
- 合并技能：将相关技能合并为 2-3 个综合技能
- 继续生成：按 5 个技能生成（不推荐）
