learnwy/project-skill-writer

项目技能编写器

设计理念：用户不知道"技能"是什么或如何描述。他们只知道自己的问题。此技能将问题描述转化为可运行的技能。

共享原则： 本技能与 project-agent-writer / project-skill-installer / project-rules-writer 共享 5 条 writer 通用纪律（理解→分析→确认→项目相对路径→验证）。详见 references/writer-discipline.md。

适用场景

适合调用：

• 用户描述了重复性的困扰或手动任务
• 用户说"创建一个技能"、"我每次都要手动做 X"、"我希望 AI 能自动……"
• 用户提供了可以标准化的工作流

不适合调用：

• 用户想要智能体（请转交 project-agent-writer）
• 用户想安装现有技能（请转交 project-skill-installer）
• 用户想要规则而非技能（请转交 project-rules-writer）
• 没有复用潜力的一次性请求

前置条件

• Node.js >= 18
• 目标项目必须有可写目录（默认为 .agents/skills/）

工作流

[L1: 问题理解]
       ↓
[L2: 项目分析]  ← 并行子智能体
       ↓
[L3: 技能设计]
       ↓
[L4: 用户确认]  ← 等待确认
       ↓
[L5: 生成]
       ↓
[L6: 质量验证]

L1：问题理解

提取问题、分类并推断技能元数据——不要让用户来定义这些。

| 问题模式 | 技能类型 | 示例 | |---------|---------|------| | "我每次都写相同的代码" | Generator（生成器） | 组件生成器、API 客户端 | | "我每次都做相同的检查" | Validator（验证器） | 代码检查、安全扫描 | | "我每次都解释相同的事情" | Informer（信息提供器） | 架构文档、API 文档 | | "我每次都遵循相同的步骤" | Workflow（工作流） | 部署、发布流程 | | "我每次都查找和修复相同的问题" | Remediation（修复器） | Bug 修复、重构 |

仅在存在多个有效方案且用户偏好重要时才提问。绝不问"你想让技能做什么？"——从问题中推断。

L2：项目分析管道

通过 Task 工具并行启动这些智能体（它们相互独立）：

| 智能体 | 用途 | 工具调用 | |-------|------|---------| | 项目扫描器 | 结构、现有资产、模式 | Task(subagent_type="search", query="...") | | 技术栈分析器 | 语言、框架、构建工具 | Task(subagent_type="search", query="...") | | 约定检测器 | 命名、导入、代码风格 | Task(subagent_type="search", query="...") |

在进入设计阶段前，将它们的输出合并为统一的项目档案。

L3：技能设计

基于问题 + 项目分析，生成设计规格：

## 技能：{name}

### 解决的问题
{1 句话描述此技能解决的问题}

### 触发条件
- {触发条件 1}
- {触发条件 2}

### 架构
- 输入：{技能接受什么}
- 输出：{技能产出什么}
- 处理：{技能如何工作}

### 项目集成
- 输出路径：{项目相对路径}
- 约定：{来自项目分析}

### 质量标准
- {可衡量的成功标准}

### Hooks（可选）
- 作用域：{global|project}
- 事件：{要挂载的 IDE 生命周期事件}
- 用途：{hooks 提供的确定性自动化}

设计原则：

1. 单一职责 — 一个技能 = 解决一个问题
2. 遵循约定 — 使用项目的命名、结构和模式
3. 最小摩擦 — 触发条件应匹配自然语言
4. 可验证输出 — 明确的成功/失败标准

L4：确认

生成之前，向用户展示：

我将创建一个技能：

问题：{用户原话描述的问题}
方案：{技能将做什么}
触发条件：{何时激活}
输出：{将创建的文件}

这样是否正确？需要调整什么吗？

等待用户确认后再生成。

L5：生成

用户确认后：

1. 脚手架：运行 scripts/cli.cjs init 并使用 --problem 标志，或使用 skill.md.template 手动创建文件
2. 填充：将 L2 分析中的项目特定约定注入 SKILL.md 各节
3. 参考文件：仅在技能需要时创建 references/、assets/、scripts/
4. 路径：使用路径发现确定输出路径——始终使用项目相对路径

回退方案：如果 cli.cjs init 失败或模板不适用，直接按模板结构编写 SKILL.md。

L6：质量验证

对生成的技能运行质量验证器。

交付前的最低检查：

• [ ] 技能有有意义的触发条件（不仅仅是文件名）
• [ ] 输出路径是项目相对路径，而非全局路径
• [ ] Frontmatter 包含 name 和 description
• [ ] 工作流可执行（不仅仅是抽象步骤）
• [ ] 依赖已声明
• [ ] 示例展示了真实用法
• [ ] 如果技能有自动模式 → hooks.json 存在且作用域正确（global vs project）
• [ ] Hook 脚本使用共享库（src/shared/hooks-lib.ts），而非自定义 stdin 解析

错误处理

| 问题 | 解决方案 | |------|---------| | 无法检测技术栈 | 向用户询问语言/框架，或扫描文件扩展名 | | 项目过大（>500 个顶层条目） | 在项目扫描器中使用 focus_folders 参数 | | 发现冲突的现有技能 | 展示对比，询问用户：扩展现有还是创建新的？ | | 用户问题映射到多种技能类型 | 展示前 2 个候选方案及权衡，让用户选择 | | 路径发现未找到标记 | 默认使用项目根目录的 .agents/skills/ | | 生成的技能未通过质量验证 | 展示失败项，自动修复可修复的，标记其余 |

输出合约

始终产出四个部分：

1. 问题理解：识别出的问题
2. 方案设计：技能架构
3. 交付物：创建的文件
4. 使用指南：如何触发和使用技能

智能体

• 项目扫描器：结构和模式分析
• 技术栈分析器：语言/框架检测
• 约定检测器：代码风格提取
• 质量验证器：生成后验证

参考文档

• 路径发现：输出路径确定（设计完成后加载）
• 高级模式：技能架构模式（工作流、领域、模板、多变体）