SKILL.md 文件怎么写？（手把手教程）

第一步：写 YAML 头

--- name: feedback-synthesis description: 将客户反馈综合为主题报告。当用户提及反馈分析、NPS 综合、支持工单主题或客户情感时自动调用。 ---

两个必填字段：

• name

  ：唯一的名字，小写字母加连字符。之后用/feedback-synthesis就能调用它。

• description

  ：描述文字，不仅要让人看懂，还要让 Claude Code 能自动匹配到。要写用户平时会说的话。

第二步：写正文

正文需要包含几个关键部分：

1. 目的说明

用一两句话说清楚这个 Skill 有什么用。先说好处，再说怎么做：

## 目的 将原始客户反馈转化为可操作的洞察报告，供产品团队用于优先级决策。

重点是告诉读者"你能得到什么"，而不是"内部怎么运作的"。

2. 输入要求

说清楚用户需要提供什么：

## 预期输入 - **必填：** 包含客户反馈的 CSV 或文本文件（每行一条反馈） - **可选：** 用于筛选的日期范围（默认为最近 30 天） - 支持格式：CSV、JSON、纯文本文件 - 最低要求：至少 10 条反馈条目以确保有意义分析

写得越具体越好。"CSV 文件"太模糊了，要说"包含反馈文本且列名为 feedback 的 CSV"。

3. 执行步骤

按顺序写出 Claude Code 要干什么：

## 流程 1. **读取并验证输入文件** - 确认文件存在且格式符合预期 - 识别反馈列 - 报告记录数量 2. **识别主题** - 阅读所有反馈条目 - 按常见话题分组 - 如需严格分类，使用 resources/categories.md 中的类别定义 3. **分析每个主题** - 统计出现频率 - 评估情感倾向（正面、负面、混合） - 提取代表性引述（逐字原文） 4. **生成报告** - 遵循 resources/output-template.md 中的模板 - 包含执行摘要、主题分析和建议 - 保存至 reports/feedback-synthesis-[日期].md 5. **质量检查** - 验证所有主题都有支持性引述 - 确认百分比总和约为 100% - 检查建议是否具有可操作性

注意要用"读取文件"这种命令式的语气，不要用"文件应被读取"这种被动句。

4. 输出格式

规定生成的文件长什么样：

## 输出格式 生成文件：reports/feedback-synthesis-YYYY-MM-DD.md 结构： - 执行摘要（3-5 条要点） - 主题分析（每个主题一个章节，包含频率、情感、引述、影响） - 建议（按优先级排序的列表） - 方法论（简要说明）

5. 质量标准

让 Claude Code 在完成前自我检查：

## 质量标准 - 每个主题至少包含 2 条支持性引述 - 引述为源数据逐字原文，非转述 - 情感评估需解释推理过程 - 建议需与特定主题相关联 - 文件成功保存至指定路径

6. 可选部分

还可以加上调用示例、边缘情况和相关 Skill：

调用示例：

## 使用示例 - 标准版："对 data/customer-feedback-q4.csv 运行反馈综合" - 带日期范围："仅针对11月的 feedback.csv 运行反馈综合" - 快速版："运行反馈综合，只需给我前三大主题"

边缘情况：

## 边缘情况 - **数据稀疏（少于10条）：** 生成报告时附带样本量有限的说明 - **格式混杂：** 若反馈列不明确，请用户指定 - **反馈条目过长：** 对超过500字的单条条目进行摘要 - **非英文内容：** 注明语言后继续处理；不尝试翻译

相关Skill：

## 相关Skill - prd-audit：利用反馈综合的洞察来审核PRD的完整性 - user-story-expander：将反馈主题转化为用户故事

完整的 Skill 示例

把上面所有东西拼起来，就是一个完整的 SKILL.md 文件（大概 600 字）：

--- name: feedback-synthesis description: 将客户反馈综合成带有可操作洞察的主题报告。当用户提及反馈分析、NPS综合、支持工单主题、客户情绪或客户之声时自动调用。 ---

# 反馈综合 ## 目的 将原始客户反馈转化为可操作的洞察报告，供产品团队用于优先级决策。 ## 预期输入 - **必需：** 包含客户反馈的文件（CSV、JSON或纯文本） - **可选：** 日期范围、特定关注领域 - 至少10条反馈条目才能进行有意义的分析 - 支持来自以下渠道的反馈：支持工单、NPS调查、用户访谈、应用商店评论 ## 流程 1. **读取并验证输入** - 确认文件存在且可读 - 识别反馈内容 2. **识别主题** - 按常见话题对反馈进行分组 - 目标为4-8个主题 3. **分析每个主题** - 统计频率 - 计算百分比 - 评估情绪 - 提取2-3条代表性引述 4. **综合发现** - 撰写执行摘要 - 按频率和业务影响排序 - 生成可操作的建议 5. **生成报告** - 保存至 reports/feedback-synthesis-YYYY-MM-DD.md 6. **质量检查** - 验证所有主题均有支持性引述 ## 输出格式 生成文件：reports/feedback-synthesis-YYYY-MM-DD.md ## 质量标准 - 每个主题至少有2条逐字引述支持 - 引述为来源原文，非转述 - 百分比总和约等于100% - 建议足够具体，具有可操作性 ## 边缘情况 - **数据稀疏（少于10条）：** 继续处理，但附带样本有限的说明 - **反馈列不明确：** 请用户指定哪一列包含反馈 - **条目过长（超过500字）：** 在分类前先进行摘要 ## 使用示例 - "对 data/q4-feedback.csv 运行反馈综合" - "综合 surveys/november.json 中的NPS回复"

五种常用的 Skill 设计模式

1. 转换模式：整理数据

适用场景：手上有一堆乱七八糟的数据，需要整理成规整的报告。

例子：客户反馈 → 主题报告 / 访谈记录 → 洞察摘要 / Git提交 → 发布说明 / 会议记录 → 行动项

流程：

## 流程 1. 读取并验证输入数据 2. 应用转换逻辑（分类、摘要、重构） 3. 生成结构化输出 4. 对照标准进行质量检查

2. 调查模式：回答问题

适用场景：需要查资料回答一个具体问题，还要提供证据。

例子："为什么转化率下降了？" → 根因分析 / "这个功能怎么工作的？" → 带文件引用的解释

流程：

## 流程 1. 理解问题 2. 确定相关数据源 3. 分析数据源以获取答案 4. 整理证据（引用、参考、数据点） 5. 综合答案与支持证据

⚠️ 调查模式和转换模式的区别：调查模式的输出结构不固定，取决于找到了什么。

3. 生成模式：按需创建

适用场景：你给参数，Skill 自动生成文档。

例子：功能描述 → 用户故事 / 冲刺目标 → 状态报告 / 产品领域 → 竞品分析

流程：

## 流程 1. 接收参数（功能名称、日期范围、关注领域） 2. 收集上下文（来自代码库、模板、参考文档） 3. 按照模板生成产物 4. 根据质量标准进行验证

4. 同步模式：拉取外部数据

适用场景：从外部系统拉数据，更新本地文档。

例子：Jira → PRD 章节 / 分析仪表板 → 每周指标 / 竞品网站 → 竞争概况

流程：

## 流程 1. 连接外部源（通过 MCP 或导出） 2. 提取相关数据 3. 转换为本地格式 4. 创建或更新本地产物 5. 记录同步时间戳

5. 审计模式：检查质量

适用场景：拿现有文档对照标准检查，找出问题。

例子：PRD → 完整性检查 / 用户故事 → 质量评估 / 文档 → 代码准确性验证

流程：

## 流程 1. 读取待审计的产物 2. 加载评估标准（来自参考文件） 3. 针对每条标准评估产物 4. 整理发现（通过项、未通过项、缺失项） 5. 生成改进建议

怎么选？