关于作者：10 + 年项目管理与全栈开发经验，近半年专注 Agent Skills 实战落地，帮助团队实现项目交付效率提升 40%。本文所有逻辑、案例与规则均基于 Trae / Cursor / OpenClaw / Hemers 全环境测试通过。

系列专栏：Agent Skills 开发实战・阶段 2 基础实操
这是「Agent Skills 开发实战」系列的 第 6 篇（第 6 周），定位：落地实战、开箱即用、附完整可复制模板，承接上一篇四层排错体系，把理论直接落地成可用的业务技能。

回顾系列前文：第 1 篇建立认知，搞懂 Agent Skills 本质；第 2 篇快速上手，写出 Hello World；第 3 篇拆解底层，吃透 [SKILL.md](SKILL.md) 标准结构；第 4 篇澄清概念，分清 Prompt、Rule、Skill 边界与优先级；第 5 篇故障排查，四层排查法解决 99% 技能失效问题。

系列导航：上一篇：《为什么你的 Skill 总是不生效？四层排查法，从 "完全没反应" 到 "稳定触发"》

一、学完排错，直接落地：今天做一个能干活的需求分析 Skill

先看效果：输入一句话，AI直接输出规范PRD

在对话中输入「帮我写一个AI智能体技能管理系统的需求分析PRD」，Skill自动触发，全程0人工干预，最终输出一份包含项目概述、功能/非功能需求、技术规格、约束条件等6大模块的标准化需求文档（见文末实战截图）。这就是我们今天要手把手做的东西。

上一篇我们讲透了四层排查体系，但很多读者反馈：道理都懂，真要自己写一个业务Skill，还是不知道从哪下手，写出来要么触发率低，要么输出乱，要么一换平台就挂。

新手最缺的不是理论，而是一个完整、规范、可直接复制、全平台稳定运行的实战范本。本篇我们就从零开始，手把手做一个「需求分析 Skill」—— 产品/研发/项目管理场景最高频复用的技能，零基础也能跟着写完。全程边写边对应四层排错标准，写完直接通过自检，不会出现「文件放进去没反应」「AI 不主动调用」「输出格式乱飘」这些新手常见病。文末附完整资源下载，复制到文件夹里就能用。

二、动手前先避坑：前置规范对齐四层排错

写代码前先定规范，这是避免后续反复排错的核心。我们直接用上一篇的四层标准做前置约束，从根源上杜绝 80% 的故障。

1. 文件层规范

• 新建独立文件夹，命名 requirements（与内部 name 字段一致）

• 核心文件严格命名 SKILL.md（全大写，区分大小写系统写错直接失效）

• 文件编码 UTF-8，用纯文本编辑器编写，禁用 Word/WPS

• YAML 头部顶格写，前面不能有空行

如图：

1. 触发层规范

• description 开篇写触发场景，不写空话套话

• 预埋 3-5 个用户高频关键词：PRD、需求文档、需求分析、需求评审

• 明确适用边界，不模糊、不越界

1. 优先级层规范

• Skill 内部明确输出格式与优先级，声明「本技能格式优先于全局 Rule」

• 核心流程不依赖临时 Prompt，避免被用户一句话冲散

1. 环境层规范

• 只用全平台通用字段，不写平台专属语法

• 纯文本 Skill 不依赖脚本，零依赖、可跨平台迁移

三、分步拆解：从零搭建完整需求分析 Skill

3.1 第一步：写头部元数据（技能身份证，对应文件层）

元数据是 AI 识别技能的第一入口，写错一个字符都可能导致技能列表不显示。

✅ 标准正确写法：

yaml --- name: requirements version: 1.0.0 description: 当用户新建项目、变更需求、编写PRD、需求评审时使用，引导完成标准化需求分析文档，包含项目概述、功能/非功能需求、技术规格、约束条件完整流程。 ---

❌ 新手常见错误：

• name 用中文、用驼峰命名（AI 识别不稳定）

• description 只写功能，不写触发场景（AI 不知道什么时候调用）

• --- 前面有空行（YAML 解析失败，整个技能加载不出来）

3.2 第二步：定义触发条件（对应触发层，提升主动调用率）

很多人写的 Skill 只能手动 @ 调用，AI 从不主动用，核心问题就是触发条件写得太笼统。触发条件要做到「场景 + 关键词」双覆盖。

markdown ## 触发条件 当用户进行以下活动时，应使用此技能： - 开始新的项目开发，需要编写需求分析文档 - 现有项目需求变更，需要更新需求分析文档 - 进行项目规划，需要明确功能和非功能需求 - 与 stakeholders 沟通项目需求，需要结构化的文档支持 - 进行需求评审，需要标准化的需求文档格式 - 用户提到关键词："写需求文档"、"起草需求分析"、"创建需求规格"、"PRD"、"功能规格"

触发层优化技巧：把用户最常说的原话直接写进去，而不是写你的专业概括。比如用户会说「帮我写个 PRD」，不会说「进行需求规格说明书编制」，前者才是有效的扳机词。

3.3 第三步：三段式核心工作流（Skill 的灵魂，对应优先级层）

这是 Skill 的主体部分。一个好的业务 Skill 不是把规则甩给 AI，而是给它一套步骤明确、可执行、容错强的标准化流程。

我们采用「上下文收集 → 优化结构化 → 读者测试」三段式工作流，这也是专业产品经理做需求的标准 SOP。

第一阶段：上下文收集

目标：先搞懂项目，再动笔写文档，避免自嗨。

markdown ## 第一阶段：上下文收集 ### 初始提问 先确认 7 项基础元信息： 1. 项目名称是什么？ 2. 项目的简要描述是什么 3. 核心业务目标和价值是什么？ 4. 主要受众和使用人群是谁？ 5. 文档预期达到什么效果？ 6. 是否有指定模板或格式要求？ 7. 还有哪些约束条件（工期、预算、技术栈）？ ### 信息倾倒 引导用户全量输出相关信息：项目背景、替代方案、团队情况、时间压力、技术架构、初步功能想法，支持文字、链接、文档多种形式输入，不用整理结构。 ### 澄清问题 根据信息空白，生成 5-10 个具体澄清问题，用编号列出。用户可简答补充。 ### 过渡 确认用户无更多信息补充后，进入文档起草阶段。

如图：

第二阶段：优化与结构化

目标：逐章节打磨，输出标准化 Markdown 文档。

markdown ## 第二阶段：优化与结构化 ### 章节结构 默认采用 6 大标准章节，支持用户自定义调整： 项目概述、功能需求、非功能需求、技术规格、约束条件、输出规范 ### 执行规则 1. 先创建 `requirements.md` 文件，填充章节占位标题 2. 从信息缺口最大的章节开始（默认功能需求），逐章节处理 3. 每章节执行六步法：澄清提问 → 头脑风暴 → 筛选内容 → 查漏补缺 → 起草内容 → 迭代优化 4. 80% 章节完成后，全局检查一致性、删除冗余、修正矛盾 5. 全部章节完成后，整体审阅，询问是否进入读者测试

如图：

第三阶段：读者测试

目标：避免「自己写的自己看得懂，别人看了一头雾水」。

markdown ## 第三阶段：读者测试 ### 测试方法 1. 预测读者可能提出的 5-10 个核心疑问 2. 指导用户打开全新空白对话，粘贴文档内容 3. 向新对话提问，验证：答案是否准确、有无歧义、是否隐含前置知识、有无内部矛盾 4. 根据测试结果，返回对应章节修改优化 5. 新对话能准确回答全部问题，即为测试通过 ## 最终审阅 提醒用户自行核对事实细节、技术参数、业务逻辑。确认无误后交付完整 Markdown 文档，附带后续迭代维护建议。

如图：

3.4 第四步：内置标准化文档模板

很多 Skill 输出忽长忽短、格式不一，本质是没有内置固定模板。把文档规范写进 Skill，优先级高于全局 Rule，输出就会稳定可控。

markdown ## 需求分析文档规范 ### 项目概述 - 项目名称：XXX - 项目描述：一句话说明项目用途 - 项目目标：明确核心业务目标与交付价值 ### 功能需求 按模块拆分，每个需求带唯一编号： - **FR-001**：功能描述 + 适用角色 + 操作流程 - **触发条件**：前置条件、触发场景、操作路径 ### 非功能需求 按性能、安全、兼容性分类，全部量化： - **NFR-001**：性能指标（响应时间、并发量、吞吐量）+ 测试标准 - **NFR-002**：安全要求（加密、鉴权、权限控制）+ 验证方式 ### 技术规格 分别明确前后端、API 选型： - 后端：技术栈、框架、数据库 - 前端：技术栈、UI 组件库 - API：接口规范、认证方式 ### 约束条件 列出工期、预算、合规、技术依赖等硬性限制，说明例外处理机制。 ### 输出要求 统一 Markdown 格式，带目录、需求编号、术语附录，支持导出 PDF。

3.5 第五步：引导技巧与异常处理

真实使用中用户不会完全按你的流程走，必须加容错处理。

markdown ## 有效引导技巧 - 语气简洁直接，必要时解释原因，不啰嗦、不推销 - 用户想跳过阶段、赶时间，提供简化方案，保留用户主动权 - 遇到陌生术语、信息空白，立刻追问，不脑补、不瞎编 - 质量优先于速度，每次迭代要有实质改进，不敷衍凑数

四、完整技能资源：CSDN 专属一键下载，开箱即用

两种获取方式，按需选择

方式一（学习推荐）：直接复制上文各步骤中的代码块，对照四层规范手动构建。适合想深入理解 Skill 底层结构的读者。

方式二（快捷部署）：为避免手动复制出现漏行、格式错乱、YAML报错等问题，我已将完整合规的需求分析 Skill 全套文件整理打包，上传至CSDN资源中心。下载后无需二次修改，解压即用，完美适配全平台规范。

资源包包含内容

• 完整可运行 SKILL.md 主文件，对齐四层排错所有规范

• 内置三段式专业工作流、容错机制、标准化 PRD 模板

• 全平台适配配置，兼容 Trae / Cursor / OpenClaw / Hemers

• 极简部署 + 使用说明书，小白零门槛上手

✅ 部署使用方法

1. 下载资源包并解压，获取完整 requirements 技能文件夹；

1. 将文件夹放入对应平台的 skills 项目目录；

1. 重启客户端、刷新技能列表，自动加载生效；

1. 直接输入自然语言指令，即可自动触发技能、生成标准 PRD。

资源获取：文章最上面【资源下载】区，一键获取全套源码文件

五、写完必做：四层排查法自检

写完不要急着用，用上一篇的四层排查法过一遍，排除 99% 的隐性故障。

1. 文件层自检

• 文件夹名 requirements 与 name 字段一致

• 文件名 SKILL.md 大小写完全正确

• 编码 UTF-8，YAML 头顶格无空行

• 字段无拼写错误

1. 触发层自检

• description 开头即触发场景

• 预埋了 PRD、需求文档、需求分析等高频关键词

• 手动调用能生效，自然提问也能匹配

1. 优先级层自检

• 内置了明确的文档格式规范，不依赖全局 Rule

• 核心流程完整，不会被简短临时 Prompt 完全冲散

• 边界清晰，不会和其他 Skill 抢活

1. 环境层自检

• 纯文本 Skill，无脚本依赖

• 只用通用字段，无平台专属语法

• 跨 Trae / Cursor / OpenClaw / Hemers 无需修改

六、新手最容易踩的 5 个坑

结合四层排错经验，整理新手写需求分析 Skill 的高频翻车点：

1. 只写流程，不固定输出模板
   后果：每次输出格式都不一样，文档规范性差。
   解决：把文档结构、编号规则、章节模板全部写死在 Skill 里。

1. 省略读者测试环节
   后果：写出来的文档只有自己看得懂，开发拿到全是歧义。
   解决：把读者测试作为标准流程强制环节，不能跳过。

1. description 写得太笼统
   后果：AI 从不主动调用，只能手动 @。
   解决：开篇就写「当用户…… 时使用」，直接埋关键词。

1. YAML 头空行 / 文件名小写
   后果：技能根本加载不出来，属于第一层文件故障。
   解决：严格按规范命名，写完先去技能列表确认能看到。

1. 流程太刚性，没有容错
   后果：用户想跳过某步、想加快速度时，AI 只会机械坚持流程，体验很差。
   解决：保留简化模式和跳过选项，给用户主动权。

七、怎么用：一句话触发

配置完成后，直接在对话里说：

• 「帮我写一个在线教育平台的需求分析 PRD」

• 「用需求分析 Skill 拆解一下这个电商后台项目」

• 「帮我做一份项目需求文档，要标准格式」

AI 会自动匹配并激活这个 Skill，按三段式流程引导你一步步输出完整、规范的需求分析文档。

八、实战效果：真实运行界面展示

下图为需求分析 Skill 在 Trae SOLO Agent 模式下的实际运行效果，完整对应前文所述的三段式工作流：

图注：

• 左侧对话区：Skill 自动触发后，进入「上下文收集」阶段，按预设的 7 项基础问题引导用户补充项目信息，全程无需手动引导；

• 右侧文档区：用户输入信息后，Skill 自动进入「优化与结构化」阶段，生成标准化《AI 智能体技能管理系统（SkillMaster）需求分析文档》，完整覆盖项目概述、功能需求等模块，格式统一、编号规范，可直接交付团队使用。

从实际运行效果可以看到，整个过程 AI 严格遵循预设流程，无自由发挥，输出结果稳定可控，彻底解决了普通 Prompt 输出飘忽不定的问题。

关于 Agent Skills 开发实战系列

本文为「Agent Skills 开发实战・阶段 2 基础实操」系列第 6 篇，承接上一篇四层排错体系，将文件、触发、优先级、环境四层规范完整落地到真实业务场景，产出可直接复制使用的需求分析 Skill 模板。

系列往期文章：

1、《一文读懂 Agent Skills》：AI 智能体技能核心认知解析

2、《5 分钟上手：写第一个 Hello World Skill》：零基础快速建立开发信心

3、《[Skill.md](Skill.md) 文件结构拆解》：夯实 Agent 技能底层编写规范

4、《Prompt、Rule、Skill 区别一篇讲透：90% 的 Skill 不稳定，都是因为分不清这三兄弟》

5、《为什么你的 Skill 总是不生效？四层排查法，从 "完全没反应" 到 "稳定触发"》

下期预告：第 7 周《跨平台适配：同一套 Skill 如何在 Trae 和 OpenClaw 中通用？》，详解这套需求分析 Skill 如何零修改兼容多平台，拆解各平台目录规范、语法差异与兼容技巧，真正实现一次编写、全平台复用。