QDKT15-1把功能/应用封装为 Agent 可用的 Skill 技能
如何将已有产品/项目能力抽象、封装为Agent可用的Skill
一、核心概念对齐
1.1 产品的基本组成
所有产品（网页、APP、小程序等）都由前端和后端组成：
前端：人机交互界面（HTML、CSS、Markdown等标记语言渲染）。
后端：处理逻辑、数据存储、API接口。
前后端通过HTTP请求/API通信。
1.2 Skill的本质
Skill是Agent的插件/能力扩展，不是Agent的必备品。
目标：将原有的人机图形界面交互，转变为面向对话的交互范式。
前端 → 对话式消息渲染（支持Markdown、HTML等）。
后端 → 拆解为原子化的能力（脚本、Webhook、API、持久化数据）。
两种后端服务类型：
状态型：持久化数据（如数据库读取），可存为reference或资产文件。
动作型：临时计算/触发操作（如弹窗、计算），封装为脚本或API。
1.3 为什么要进行skill化改造？
让Agent能够调用现有产品的能力，实现自动化的多步骤任务。
将用户的操作流程（点击按钮 → 脚本 → 后端）转化为对话指令（用户说“帮我拉取资讯” → Agent调用对应skill）。
每一步可确认、可追踪、可回滚，提升交互友好性。
二、产品skill化改造的通用方法论
2.1 核心思路
解耦前后端：原有前端图形界面 → 对话式输出（消息/流式数据）。
原有后端逻辑 → 拆成独立可调用的脚本/API。重构数据结构：避免返回超长、无效的上下文（如古早RSS的冗长XML），应萃取为结构化、简洁的格式（如Markdown或精简JSON）。
原子化拆解：按用户旅程（任务流程）而非页面/API拆分功能。每个技能对应一个完整的任务步骤。
2.2 改造流程（推荐分步执行）
步骤一：输出项目功能拆解报告
输入：已有产品的代码库（如GitHub开源项目）。
要求AI分析：
产品核心功能、用户操作路径、前端页面映射。
后端接口依赖、数据流向。
识别仅存在于前端的逻辑（如表单、下拉菜单），并建议如何下沉到服务层或前置为输入参数。
识别过于面向页面的后端接口，提出重构建议（如独立API端点）。
交付物：功能拆解报告（含功能地图、用户操作清单、前后端映射、待确认问题等）。
步骤二：封装为Skill规划
基于步骤一的报告，将每个用户任务抽象为一个Skill候选项。
每个Skill应包含：
名称、使用场景、触发意图、输入/输出参数。
依赖的后端能力（脚本/API/数据文件）。
优先级、复杂度、是否需要用户确认。
重要原则：
按流程拆分，不要按API拆分（一个Skill应完成一个完整任务）。
自包含：Skill不应依赖其他Skill才能工作（避免类似飞书Lark share的强依赖问题）。如需共享认证/配置，应内置或通过环境变量/本地文件解决。
避免巨型Skill：保持每个Skill小而精。
环境变量：所有API Key等敏感信息必须存放在
.env文件中，禁止硬编码在Skill里。返回文件路径：本地环境应返回文件路径而非二进制内容。
输出：Skill规划文档（含索引表、详细描述、封装顺序建议）。
步骤三：创建Skill（使用Skill Creator工具）
推荐使用Skill Creator 1.0（简单、适合日常）或2.0（严格、适合分发/售卖）。
要求AI按规划逐个创建Skill，每个Skill单独生成，不要一次性生成所有。
可启用子Agent并行创建多个Skill，提高效率。
每个Skill的
skill.md应保持精简，低频/详细内容（如API规范、业务规则）放到references/目录下，按需读取。
2.3 一键梭哈方式（不推荐新手）
提供超长提示词，让AI一次性完成全部拆解+封装。
对模型上下文长度要求极高（可能需要24万+ token），且结果质量不稳定。仅适合经验丰富且使用强模型（如Claude Code）的场景。
三、测评方法
3.1 简单测评
检查Skill完整性、代码可溯源（不能编造能力）。
启用子Agent实际调用Skill执行任务，验证可用性。
输出验收报告。
3.2 标准测评（推荐）
使用Skill Creator 2.0内置的测试用例和流程。
该工具提供：
结构化测试提示词。
生成带人工审核界面的网页，记录输入/输出和反馈。
支持根据反馈迭代优化Skill。
此方法同样可用于测评Agent本身。
四、关键注意事项
| 类别 | 要求 |
|---|---|
| 拆分粒度 | 按用户旅程拆分，不要按页面/API拆分 |
| 依赖关系 | Skill必须自包含，不依赖其他Skill |
| 信息存储 | 低频/详细内容放references/，skill.md保持精简 |
| 敏感信息 | 使用环境变量（.env），禁止硬编码 |
| 返回格式 | 本地环境返回文件路径，网页环境返回URL |
| 错误处理 | 允许自动重试（建议最多3次），失败后告知用户 |
| 上下文效率 | 避免一次加载全部API文档，应分步骤按需读取reference |
| 执行步骤 | 小步原子化，便于用户反馈和中断恢复 |
五、推荐工具与资源
| 工具/资源 | 用途 |
|---|---|
| Skill Creator 1.0 | 日常快速开发Skill，规范简洁 |
| Skill Creator 2.0 | 严格测评、分发、商业化场景 |
| Cursor / Claude Code | 执行拆解和封装的IDE/CLI工具 |
| GitHub开源项目 | 作为练习/改造的目标代码库 |
| 腾讯文档（示例） | 存储提示词模板（尽管主讲人吐槽其交互） |
六、典型问题与解答摘录
Q1：什么时候用Skill，什么时候直接写代码脚本？
Skill：为Agent扩展能力，外挂式插件，不修改Agent本身。适合让不同Agent都能调用同一产品能力。
代码脚本：如果你自己开发一个Agent产品，直接写Agent逻辑即可，无需再包一层Skill。
Q2：如何让AI不偷懒（只看文件名/函数名就下结论）？
在提示词中明确要求“基于代码内容分析，不要仅看文件名或函数名”。
提供足够的知识资料（如Skill规范、模板）。
要求输出标注不确定项，说明需要补充的信息。
Q3：原产品后端未暴露独立API怎么办？
需要在改造计划中明确建议：为每个管线/能力增加独立API端点，确保Skill可调用。
对于纯前端逻辑（如表单），应将其转化为Skill的输入参数或下沉为后端校验。
七、总结
本次会议核心：掌握将现有产品“skill化”的三步法（拆解 → 规划 → 封装），理解自包含、原子化、对话式交互的设计原则。