Skills 编写学习

## 简介：
之前看了，官方的SKills 就在参考官方SKIlls 编写。总感觉差点意思。 最近刷到了，谷歌发的推文 学习记录一下。翻译为中文版本后，根据个人理解微调。
## 一、翻译文章
1、将文章下载到本地，让Claude 翻译一下， 并给我讲解。
文章来源：https://x.com/GoogleCloudTech/status/2033953579824758855

 
## 二、skills 设计的五种模式
 
###模式 1：工具封装模式 (Tool Wrapper)原文工具封装模式，为你的智能代理提供特定库的按需上下文。它不是将 API 约定硬编码到系统提示中，而是将这些知识打包到一个技能中。你的智能代理只在实际使用该技术时才会加载这个上下文。
这是最简单的实现模式。SKILL.md 文件会监听用户提示中的特定库关键词，从 references/ 目录动态加载内部文档，并将这些规则应用为绝对真理。这是将团队内部编码准则或特定框架最佳实践直接分发给开发人员工作流程的有效机制。

1. **示例：**
2. ```markdown
4. 个人解读：用户需求 - 先加载skills中约定的知识库-依据知识库（也可以是其他类型的知识库），逐一对用户的代码进行检查-
6. # skills/api-expert/SKILL.md
7. ---
8. name: api-expert    markdown
9. description: FastAPI的开发最佳实践和约定。在构建、审查或调试FastAPI 应用程序、REST API 或 Pydantic 模型时使用。
10. metadata:
11.   pattern: tool-wrapper
12.   domain: fastapi
13. ---
15. 你是 FastAPI 开发专家。将这些约定应用于用户的代码或问题。
17. ## 核心约定
19. 加载 'references/conventions.md' 以获取完整的 FastAPI 最佳实践列表。
21. ## 代码审查时的操作
23. 1. 加载约定参考
24. 2. 逐一对用户的代码进行检查
25. 3. 对于每一个违规，引用具体规则并建议修复
27. ## 编写代码时的操作
29. 1. 加载约定参考
30. 2. 严格遵循每个约定
31. 3. 为所有函数签名添加类型注释
32. 4. 使用 Annotated 风格进行依赖注入
33. ```

复制代码

　　

 ###模式 2：生成器 (Generator)
虽然工具包装器可以应用知识，但生成器则确保输出的一致性。如果你在智能代理每次运行时生成不同的文档结构时遇到困难，生成器通过协调、填空过程来解决这个问题。
它利用两个可选目录：assets/ 保存输出模板，references/ 保存样式指南。指令充当项目管理器的角色。它们告诉智能代理加载模板、阅读样式指南、询问用户缺失的变量，并填充文档。这对于生成可预测的 API 文档、标准化提交消息或搭建项目架构非常实用。 
**示例：**个人解读 ：  提前制定格式  输出样例、输出对象 让ai 了解你的意图，你想要的内容是什么样子;再去工作。(用户需求-触发skills-加载文档风格-加载输出模板-与用户交流-强制、指导如何要求使用输出模板-指定输出文件格式化) skills 针对用户需求编写，是非常个性化的。 

1. ```markdown
2. # skills/report-generator/SKILL.md
3. ---
4. name: report-generator
5. description: 生成 Markdown 格式的结构化技术报告。在用户要求编写、创建或草拟报告、摘要或分析文档时使用。
6. metadata:
7.   pattern: generator
8.   output-format: markdown
9. ---
11. 你是一个技术报告生成器。严格按照以下步骤执行：
13. 第 1 步：加载 'references/style-guide.md' 以获取语气和格式规则。
15. 第 2 步：加载 'assets/report-template.md' 以获取所需的输出结构。
17. 第 3 步：向用户询问填充模板所需的任何缺失信息：   
18. - 主题或主题内容
19. - 主要发现或数据点
20. - 目标受众（技术、高管、一般读者）
22. 第 4 步：按照样式指南规则填充模板。模板中的每个部分在输出中都必须存在。
24. 第 5 步：将完整的报告作为单个 Markdown 文档返回。
25. ```

复制代码

　　
  模式 3：审核器 (Reviewer)审核器模式将检查内容与检查方式分离。与其在一个长系统提示中详细列出每个代码问题，你可以将模块化的评估标准存储在 references/review-checklist.md 文件中。
当用户提交代码时，智能代理会加载此检查清单并按严重程度分组对代码进行评分。如果你将 Python 风格检查清单替换为 OWASP 安全检查清单，你会使用完全相同的技能架构获得完全不同的专门审核。这是在人工查看前自动化 PR 审核或捕获漏洞的高效方法。

1. **示例：**
2. 个人解读：   用户需求-加载检查标准(可以是各个行业的标准)-阅读用户代码 - 告诉AI将全部标准用于代码 及如何处理发现的问题(不同的业务需要个性化处理)
4. ```markdown
5. # skills/code-reviewer/SKILL.md
6. ---
7. name: code-reviewer
8. description: 检查 Python 代码的质量、风格和常见错误。在用户提交代码进行审查、要求反馈或需要代码审计时使用。
9. metadata:
10.   pattern: reviewer
11.   severity-levels: error,warning,info
12. ---
14. 你是一个 Python 代码审核员。严格按照以下审核协议执行：   加载标准-阅读用户代码 - 告诉AI 将标准用于代码   及细节要求
16. 第 1 步：加载 'references/review-checklist.md' 以获取完整的审核标准。  
18. 第 2 步：仔细阅读用户的代码。在评估之前先理解其目的。
20. 第 3 步：将检查清单中的每个规则应用于代码。对于发现的每个违规：
21. - 指出行号（或大致位置）
22. - 分类严重程度：错误（必须修复）、警告（应该修复）、信息（考虑）
23. - 解释为什么这是一个问题，而不仅仅是指出错误
24. - 建议具体的修复方法和修正后的代码
26. 第 4 步：生成结构化的审核报告，包含以下部分：
27. - **摘要**：代码功能概述、整体质量评估
28. - **发现**：按严重程度分组（错误优先，然后是警告，最后是信息）
29. - **分数**：1-10 分的
30. 评分和简短理由
31. - **前 3 条建议**：前三步骤最具影响力(可以翻译权重最高)
32. ```

复制代码

　　
 模式 4：反向模式 (Inversion)       （曾经这种模式， 用户制定去决策，代理执行，执行前询问决策者） 智能代理本质上想要立即猜测和生成。反向模式颠覆了这种动态。不是用户驱动提示和智能代理执行，而是智能代理扮演采访者的角色。
反向模式依赖于明确的、不可协商的门控指令（如“在所有阶段完成之前，不要开始构建”）来强制智能代理首先收集上下文。并等待你的答案后才会它会顺序询问结构化问题，进入下一阶段。在获得完整的需求和部署约束之前，智能代理会拒绝合成最终输出。

1. **示例：**
2. 个人解读：
3. (接受到用户要做的事情-先咨询用户需求-再询问用户所拥有的客观条件：部署环境、硬件要求、偏好的技术栈，不能接受的配置-再展示规划，并迭代直到用户确认)
4. 解决了Agent，不能充分理解使用者意图， 直接生成、执行有瑕疵方案。
6. ```markdown
7. # skills/project-planner/SKILL.md
8. ---
9. name: project-planner
10. description: 通过结构化问题收集需求后，规划新软件项目。在用户说“我想构建”、“帮我规划”、“设计系统”或“开始一个新项目”时使用。
11. metadata:
12.   pattern: inversion
13.   interaction: multi-turn
14. ---
16. 你正在进行结构化需求访谈。在所有阶段完成之前，**不要开始构建或设计**。
18. ## 第一阶段 - 问题发现（每次只问一个问题，等待每个回答）     (先咨询用户需求-再询问用户 客观条件硬件要求-再展示规划，并迭代 作用用户确认)
20. 按顺序询问这些问题。不要跳过任何问题。
22. - 问题 1：“这个项目为用户解决了什么问题？”
23. - 问题 2：“主要用户是谁？他们的技术水平如何？”
24. - 问题 3：“预期规模是多少？（每日用户数、数据量、请求率）”
26. ## 第二阶段 - 技术约束（仅在第一阶段完全回答后）
28. - 问题 4：“你将使用什么部署环境？”
29. - 问题 5：“你有任何技术栈要求或偏好吗？”
30. - 问题 6：“不可协商的需求是什么？（延迟、正常运行时间、合规性、预算）”
32. ## 第三阶段 - 综合（仅在所有问题回答后）
34. 1. 加载 'assets/plan-template.md' 以获取输出格式
35. 2. 使用收集到的需求填写模板的每个部分
36. 3. 向用户展示完整的计划
37. 4. 询问：“这个计划准确捕获了你的需求吗？你想更改什么？”
38. 5. 迭代反馈，直到用户确认
39. ```

复制代码

　　

 ###模式 5：流水线 (Pipeline)个人解读：解决了跳过步骤、导出整体结果失败的风险。（实际使用加了判断逻辑，AI还是会跳过，感觉简单任务还是封装成脚本使用，比较稳定。）
对于复杂任务，你不能承受跳过步骤或忽略指令的风险。流水线模式强制严格的顺序工作流程，并包含检查点。说明本身，充当工作流程定义。通过实现明确的菱形门控条件（例如，在从文档字符串生成到最终组装之前需要用户批准），流水线确保智能代理不能绕过复杂任务并呈现未验证的最终结果。
这种模式利用所有可选目录，只在需要的特定步骤中，提取不同的参考文件和模板，保持上下文窗口清洁。

1. **示例：**
2. ```markdown
3. # skills/doc-pipeline/SKILL.md
4. ---
5. name: doc-pipeline
6. description: 通过多步骤流水线，从 Python源代码生成 API 文档。在用户要求为模块编写文档、生成 API 文档或从代码创建文档时使用。
7. metadata:
8.   pattern: pipeline
9.   steps: "4"
10. ---
12. 你正在运行一个文档生成流水线。按顺序执行每个步骤。**不要跳过步骤或在步骤失败时继续**。
14. ## 第 1 步 - 解析与清单
16. 分析用户的 Python 代码，提取所有公共类、函数和常量。将清单作为检查清单呈现。询问：“这是你想要文档化的完整公共 API 吗？”
18. ## 第 2 步 - 生成文档字符串
20. 对于每个缺少文档字符串的函数：
21. - 加载 'references/docstring-style.md' 以获取所需格式
22. - 严格按照样式指南生成文档字符串
23. - 为每个生成的文档字符串呈现用户批准
25. 在用户确认前，不要进入第 3 步。
27. ## 第 3 步 - 组装文档
29. 加载 'assets/api-doc-template.md' 以获取输出结构。将所有类、函数和文档字符串编译成单个 API 参考文档。
31. ## 第 4 步 - 质量检查
33. 对照 'references/quality-checklist.md' 进行审查：
34. - 所有公共符号是否有文档
35. - 每个参数是否有类型和描述
36. - 每个函数是否至少有一个使用示例
38. 报告结果。在呈现最终文档前修复问题。
39. ```

复制代码

　　
 ## 如何选择正确的模式
每个模式都回答了一个不同的问题。使用此决策树找到适合你的用例的模式：
### 模式选择决策树：
1. **是否需要专业知识应用？** → 工具包装器2. **是否需要一致的输出？** → 生成器3. **是否需要对代码进行评分/审计？** → 审核器4. **是否需要深度理解需求？** → 反向模式5. **是否是复杂的多步骤过程？** → 流水线
---
## 模式组合  将五种基础模式搭配使用。
这些模式不是相互排斥的——它们可以组合使用：
- 流水线技能可以在末尾包含一个审核器步骤，以双重检查自己的工作- 生成器可以在开始时依赖反向模式来在填充模板之前收集必要的变量
感谢 ADK 的 SkillToolset 和渐进式披露功能，你的智能代理只需要在运行时在需要的确切模式上花费上下文 token。
---
## 最终建议
停止尝试将复杂且脆弱的指令塞进单个系统提示中。相反，应该：1. **分解工作流程**2. **应用正确的结构模式**3. **构建可靠的智能代理** 
来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！