Agent Skills实战：从RAG到Multi-Agent的工程化指南

大家好我是你们的技术博主。最近 Agent 这个概念确实火得不行从大模型厂商到开源社区几乎所有人都在聊智能体、Multi-Agent、RAG。但说实话在我实际开发智能体应用的时候最头疼的往往不是怎么调大模型接口而是怎么让 Agent 在具体任务里稳定可靠地干活。大模型本身是“通才”但放到业务里我们需要的是“专才”。如果你也想解决这个问题那本篇就来聊聊 Agent Skills——一种把“通用大模型”变成“领域专家”的工程化方案。我会用完整的代码案例带你从概念理解走到实际开发全程手把手新手也能跟着做。本文不打算写成“AI 科普文”而是尽量贴近工程落地从 Agent Skills 的基础结构到结合 RAG 做知识库问答再到 Multi-Agent 场景下的技能编排最后给出常见问题排错清单。如果你正在做大模型应用开发、AI Agent 项目或者想系统学习智能体搭建这篇文章应该能帮你省不少时间。1. Agent Skills 是什么为什么需要它1.1 一个让 Agent 变得更实用的新机制大模型很聪明但每次对话都是“从零开始”。你让它写一段 Python 代码它写得很好你让它按照你公司的代码规范来写它可能就忘了。你让它读一个 PDF 并提炼重点它能做但你让它输出 JSON 格式的数据表它又不稳定了。这种情况的根本原因在于大模型的知识和推理能力是通用的但具体任务的操作方法、输出格式、约束条件都是每项任务特有的。Agent Skills 就是为解决这个问题出现的。它的核心思想是把一项任务需要的“技能”指令、示例、脚本、模板、知识资源打包成一个可复用的目录结构让 Agent 在需要时主动加载并执行。我用一句话概括Agent Skills 是一种面向大模型 Agent 的“能力包”它把任务操作指南、辅助脚本、资源文件和约束条件集中封装让 Agent 按需加载并稳定执行特定任务。它不是一个新的算法也不是一个新的模型而是一套工程化规范。就好比你招了一个聪明的实习生他虽然聪明但需要你给他一份“岗位操作手册”他才能按你的预期干活。Agent Skills 就是给大模型准备的“岗位操作手册”。1.2 它解决了什么问题在我自己的项目实践中Agent Skills 主要解决了以下几个痛点。第一任务稳定性问题。不借助 Skills 时你只能在系统提示词里写一大堆规则但提示词越长大模型越容易丢失重点输出格式越不稳定。把规则放进 Skill 之后Agent 是按需加载需要时才读取既不影响日常对话效果也能保证关键任务的质量。第二能力复用问题。同一个团队里多个 Agent 可能需要做代码审查、日志分析、数据报表生成。如果每个 Agent 都单独维护一套提示词改一次需求就要改好几个地方。而 Skill 是可以跨 Agent 共享的改一处所有挂载该 Skill 的 Agent 一起生效。第三工具使用与知识沉淀分离。很多开发者容易把“调用 API”和“Agent 技能”混在一起。实际上API 调用是工具而“如何组合这些工具完成一件事”才是技能。Agent Skills 正好提供了一个标准目录让工具调用逻辑和任务操作逻辑分层管理。在这种背景下掌握 Agent Skills 已经不是“可选加分项”而是做 AI 应用落地时的基本功。尤其是当你的项目涉及 RAG、Multi-Agent 时Skills 几乎是你梳理任务边界的最佳抓手。1.3 常见应用场景从我的经验看下面几类场景最适合用 Agent Skills代码开发助手代码审查、单元测试生成、依赖升级、代码重构。知识库问答结合 RAG 把企业文档变成可查询的知识资产让 Agent 学会“先检索、后回答”。数据处理任务CSV 清洗、日志解析、报表生成、批量格式转换。多智能体协同不同 Agent 各自负责一项子任务再通过 Skills 定义每个子任务的输入输出规范让协作更可控。垂直行业应用把行业规范、计算公式、术语表封装成 Skill让大模型在金融、法律、医疗、农业等场景下更专业。现在你已经明白 Skills 的价值了。下面我们先把几个相关概念理清楚后面实战才不会迷路。2. Agent Skills 与 Agent、Multi-Agent、RAG 的关系2.1 Agent Skills 与 Agent 智能体Agent 智能体是能感知环境、做出决策并执行动作的 AI 程序。一个完整的 Agent 通常包含几个部分大模型推理核心、任务规划能力、工具调用能力、记忆机制。而 Agent Skills 是 Agent 的“能力模块”。一个 Agent 可以有多个 Skills每个 Skill 对应一类具体任务。在运行时Agent 根据用户意图自动决定加载哪些 Skills。举个例子你的 Agent 是一个“研发助手”。它可以挂载“代码审查 Skill”“单元测试生成 Skill”“需求拆解 Skill”。用户提出“帮我审查这段代码逻辑”Agent 就会去读“代码审查 Skill”按照里面的规则和脚本执行。所以Agent 是“主体”Skills 是“能力包”。Skill 本质上就是 Agent 的插件式扩展。2.2 Agent Skills 与 RAGRAGRetrieval-Augmented Generation检索增强生成是一种让大模型从外部知识库检索相关信息再结合上下文生成回答的技术。那 Skills 和 RAG 有什么区别我用一句话说清楚RAG 解决的是“让 Agent 知道什么”的问题核心是外部知识获取。Skills 解决的是“让 Agent 会做什么”的问题核心是任务操作能力。两者还能结合。比如你做一个“企业制度问答 Agent”可以用 RAG 检索制度文档片段同时用 Agent Skills 规定“回答时必须引用文档原文”“引用格式必须包含章节号”。RAG 提供知识Skills 约束行为。如果你做一个“AI SOP 视频检测”类应用也同样可以先用 RAG 加载操作手册再用 Skills 把检测流程、输出格式固化下来。2.3 Agent Skills 与 Multi-AgentMulti-Agent多智能体是指多个 Agent 协作完成一个复杂任务每个 Agent 负责一个子任务相互传递结果。在 Multi-Agent 场景里Skills 的作用会更加明显。因为每个 Agent 除了要完成自己的任务还必须遵循统一的通信协议和输出格式。如果你把“输出格式规范”和“任务操作流程”写进每个 Agent 的系统提示词维护成本会很高而把它们封装成 Skills 挂到不同 Agent 上就可以统一管理和更新。比如一个项目里有“需求分析 Agent”和“代码生成 Agent”前者负责输出结构化需求文档后者根据需求文档生成代码。你可以给“需求分析 Agent”挂上“需求文档编写 Skill”给“代码生成 Agent”挂上“架构设计复核 Skill”和“代码实现 Skill”。这样每个人职责清晰协作边界自然就稳定了。2.4 Agent Skills、MCP 与 Prompt这三个概念也经常放在一起比较我简单梳理一下。MCPModel Context Protocol模型上下文协议是一种标准化协议用来让大模型连接外部工具和数据源。它解决的是“Agent 怎么调用工具”的问题比如怎么连数据库、怎么访问文件系统。Prompt 是最原始的指令方式直接写在系统提示词里简单但难维护。Agent Skills 介于两者之间它比 Prompt 更结构化比 MCP 更高层。一个 Skill 内部会用到 Prompt也可能调用外部工具工具本身可以通过 MCP 暴露给 Agent。用一句话概括MCP 管连接Prompt 管对话Agent Skills 管任务。打个比方MCP 是插座标准Prompt 是电器的使用说明书Agent Skills 是一个封装好的“电器套件”——告诉你先按哪个按钮、再用哪根线、最后输出什么结果。3. 环境准备与工具链3.1 运行环境说明Agent Skills 目前主要用于 Anthropic 的 Claude 系列产品并通过 Claude Agent SDK 开放给开发者。不过它设计的核心思路——用目录和 Markdown 定义任务技能——在其他 Agent 框架里也有借鉴价值。由于该机制还在快速演进中版本变化比较快。本文示例以常见环境为例重点演示配置思路和实现方法。你需要根据自己的项目实际情况调整版本和 API 配置。我建议你准备以下环境环境说明操作系统Windows / macOS / Linux 均可编程语言Python 3.9 以上大模型访问方式需要可访问的 Claude API或兼容 Claude 协议的服务Agent SDKClaude Agent SDKPython 或 TypeScript开发工具VS Code 或任意代码编辑器命令行使用终端执行命令和运行脚本3.2 验证基础环境先确认 Python 版本python --version安装 Claude Agent SDKpip install claude-agent-sdk如果你使用的是其他 Agent 框架可以跳过这个安装步骤只需要保留“通过目录加载 Skill”的思路即可。接着设置 API 环境变量。注意不要把密钥直接写在代码里生产环境更推荐使用环境变量或密钥管理服务。# 在终端中临时设置Windows 用户可以用 set export ANTHROPIC_API_KEY你的API_KEY验证 SDK 是否安装成功python -c import claude_agent_sdk; print(SDK ready)3.3 示例项目总览为了让你看清全貌我先给出本文实战环节的完整项目结构。后面会按照这个结构一步步创建文件。agent-skills-demo/ ├── skills/ │ ├── code-reviewer/ │ │ ├── SKILL.md │ │ └── scripts/ │ │ └── review.py │ ├── knowledge-base-assistant/ │ │ ├── SKILL.md │ │ ├── scripts/ │ │ │ ├── load_docs.py │ │ │ ├── build_index.py │ │ │ └── search.py │ │ └── references/ │ │ └── faq_template.json │ └──>--- name: code-reviewer description: 审查代码逻辑发现潜在问题并给出优化建议。 --- # 代码审查技能 当你需要对代码进行审查时使用本技能。 ## 工作流程 1. 读取目标代码文件。 2. 检查以下方面 - 命名规范 - 异常处理 - 边界条件 - 性能问题 - 安全性问题 3. 输出审查报告格式如下 json { file: 文件名, issues: [ { severity: high|medium|low, description: 问题描述, suggestion: 修改建议 } ] }注意事项不要修改源代码只输出审查报告。如果目标文件不存在先告知用户不要猜测。这里有两个关键点 **第一description 字段写得越具体Agent 越能在正确时机自动加载这个 Skill。** 比如“审查代码逻辑”“发现潜在问题并给出优化建议”比“代码工具”更容易被 Agent 匹配到。 **第二正文部分是给大模型看的“操作手册”。** 大模型不会像人一样“通读全文”并记住所有细节但当你触发技能时它会按照 SKILL.md 中的步骤执行。所以操作步骤要清晰输出格式要明确最好配合示例。 ### 4.2 辅助脚本的作用 SKILL.md 里可以引用本地脚本。脚本的作用是处理那些大模型不擅长、或者不方便在文本中完成的事情比如 - 正则表达式批量匹配。 - 读取 Excel 文件。 - 调用外部 API。 - 对大量文本做预处理。 大模型可以根据 SKILL.md 的描述生成执行脚本的命令或者在 Python 环境里直接调用脚本函数。 保留一个原则**SKILL.md 描述“怎么做”脚本负责“真正做”两者结合才能让 Agent 稳定执行复杂任务。** ### 4.3 目录加载机制 实际开发中Skill 的加载方式取决于你使用的框架。通常有两种 1. **自动加载**Agent 根据用户请求的意图自动匹配 Skill 列表读取描述合适的 SKILL.md。 2. **显式挂载**开发者把 Skill 挂到 Agent 上作为固定能力。 以 Claude Agent SDK 为例Python 中可以直接指定 skills 目录 python from claude_agent_sdk import ClaudeAgent agent ClaudeAgent( namedemo-agent, skills_dir./skills )在对话过程中Agent 会扫描 skills 目录下的所有 SKILL.md并根据 description 判断是否需要加载。4.4 编写 Skill 的通用规范总结下来编写一个合格的 Skill 需要做到 5 点命名准确name 要能代表任务比如 code-reviewer、data-analyzer。描述具体description 要包含任务场景和关键词帮助 Agent 匹配。步骤清晰正文按 1、2、3 编号让大模型按顺序执行。输出明确最好给出输出格式示例降低大模型自由发挥的空间。资源齐全把脚本、模板、参考文件放到 Skill 目录下保持目录自包含。5. 入门实战从零编写一个代码审查 Skill5.1 技能目标这个 Skill 的目标是让 Agent 在收到“帮我审查代码”的请求时能够按预设规则检查代码并输出结构化的审查报告。我们以 Python 代码为例审查维度包括异常处理、边界条件、代码规范、性能隐患。5.2 创建 Skill 目录在项目根目录下创建如下结构skills/code-reviewer/ ├── SKILL.md └── scripts/ └── review.py5.3 编写 SKILL.md--- name: code-reviewer description: 审查 Python 代码检查异常处理、边界条件、代码规范和性能问题输出结构化 JSON 审查报告。 --- # 代码审查技能 当用户要求“审查代码”“帮我看看这段代码有什么问题”“Code Review”时使用本技能。 ## 输入 - 目标代码文件路径或一段代码文本。 ## 工作流程 1. 获取目标代码内容。 2. 使用 scripts/review.py 对代码进行静态分析。 3. 结合分析结果补充你通过阅读代码发现的问题。 4. 对每个问题标记严重程度high必现问题、medium建议修改、low优化项。 5. 输出审查报告。 ## 输出格式 严格按照 JSON 格式输出不要添加多余文字 json { file: 目标文件路径, summary: 整体评价1-2 句话, issues: [ { severity: high, line: 10, description: 问题描述, suggestion: 修改建议 } ] }注意事项不要修改源代码。如果代码为空或文件不存在输出一个 issues 为空的报告并说明原因。### 5.4 编写辅助脚本 这里的 review.py 做一个简单的静态检查识别出没有 try-except 的除法运算、过长函数、明显的类型隐患等。脚本本身不追求完美重点是演示 Skill 与脚本的协作方式。 python # 文件路径skills/code-reviewer/scripts/review.py import ast import sys from pathlib import Path class CodeVisitor(ast.NodeVisitor): def __init__(self): self.issues [] def visit_BinOp(self, node): # 检查除法运算是否处于 try 块内 if isinstance(node.op, ast.Div): has_try self._in_try_block(node) if not has_try: self.issues.append({ severity: medium, line: node.lineno, description: 除法运算没有异常捕获可能触发 ZeroDivisionError, suggestion: 使用 try-except 包裹或先判断除数是否为 0 }) self.generic_visit(node) def visit_FunctionDef(self, node): # 检查函数行数是否过长 end_line getattr(node, end_lineno, node.lineno) line_count end_line - node.lineno 1 if line_count 80: self.issues.append({ severity: low, line: node.lineno, description: f函数 {node.name} 过长约 {line_count} 行可读性较差, suggestion: 拆分为多个小函数 }) self.generic_visit(node) def _in_try_block(self, node): parent getattr(node, _parent, None) while parent is not None: if isinstance(parent, ast.Try): return True parent getattr(parent, _parent, None) return False def set_parents(node, parentNone): for child in ast.iter_child_nodes(node): child._parent parent set_parents(child, node) def review_file(filepath: str) - dict: filepath Path(filepath) if not filepath.exists(): return { file: filepath, issues: [], error: 文件不存在 } source filepath.read_text(encodingutf-8) tree ast.parse(source) set_parents(tree) visitor CodeVisitor() visitor.visit(tree) return { file: str(filepath), issues: visitor.issues } if __name__ __main__: target sys.argv[1] result review_file(target) print(result)简单说明脚本逻辑visit_BinOp检查除法是否在 try 块内不在就提示潜在风险。visit_FunctionDef检查函数长度超过 80 行提示拆分。_in_try_block从当前节点向上查找父节点判断是否在 try 中。这个脚本只是一个演示。真实项目里你可以接入 pylint、ruff、bandit 等成熟工具把它们的输出整理成统一 JSON 格式。5.5 在主程序中接入 Agent编写main.py主入口# 文件路径main.py import os from claude_agent_sdk import ClaudeAgent def main(): agent ClaudeAgent( namedev-assistant, skills_dir./skills ) # 简单演示向 Agent 提问 response agent.run( 请审查 skills/code-reviewer/scripts/review.py 这个文件 ) print(response) if __name__ __main__: main()运行python main.py如果配置正确Agent 会读取code-reviewer技能执行审查流程并输出 JSON 结构的结果。5.6 验证结果预期结果大致如下实际内容取决于脚本版本和代码内容{ file: skills/code-reviewer/scripts/review.py, summary: 整体结构清晰但存在未捕获异常的除法运算风险。, issues: [ { severity: medium, line: 10, description: 除法运算没有异常捕获可能触发 ZeroDivisionError, suggestion: 使用 try-except 包裹或先判断除数是否为 0 } ] }到这里你已经掌握了一个最小 Skill 的完整开发流程。接下来我们把 RAG 引入做一个更贴近业务场景的知识库问答技能。6. 核心实战做一个带 RAG 能力的知识库问答 Skill6.1 需求分析企业里最常遇到的一类需求是让 Agent 基于内部文档回答问题。比如“报销流程是什么”“服务器登录步骤”“项目立项规范”。直接让大模型回答它会胡说八道把整个文档塞进上下文又超出长度限制。合理方案是先用 RAG 检索出和问题相关的文档片段再把片段交给大模型生成回答。同时用 Agent Skills 约束回答格式和引用规范。本节我们实现一个“知识库问答助手 Skill”。它的完整流程是预处理企业文档切成小块。用嵌入模型把每一块转成向量存入索引。收到用户问题时计算问题向量与文档向量的相似度。返回 Top-K 文档片段。大模型基于这些片段生成回答并附上引用来源。在真实项目中你可以用向量数据库如 Chroma、Milvus、Weaviate完成第 2、3 步。为了演示原理我们用 Python 实现一个轻量版本。6.2 准备文档和依赖先在data/docs下创建几份简单的测试文档。我这里创建一个模拟企业制度文档# 服务器运维规范 1. 所有服务器登录必须使用 SSH 密钥禁止使用明文密码。 2. 生产环境变更必须提前 1 个工作日提交变更申请。 3. 发布窗口为每周二和周四晚上 22:00-24:00。 4. 每次发布后必须观察日志 30 分钟。再创建一份报销文档# 差旅报销流程 1. 员工出差前需要在 OA 系统提交出差申请。 2. 出差结束后 5 个工作日内提交差旅报销单。 3. 报销单需要附上发票、行程单和审批截图。 4. 财务审核通过后报销款将在 7 个工作日内到账。安装依赖pip install sentence-transformers numpy6.3 文档加载与切片脚本新建skills/knowledge-base-assistant/scripts/load_docs.py# 文件路径skills/knowledge-base-assistant/scripts/load_docs.py import os from pathlib import Path def load_docs(docs_dir: str data/docs) - list[dict]: docs [] docs_dir Path(docs_dir) for filepath in docs_dir.glob(*.txt): text filepath.read_text(encodingutf-8) # 按空行或固定长度拆分成块这里简单按段落切分 chunks text.split(\n\n) for idx, chunk in enumerate(chunks): chunk chunk.strip() if chunk: docs.append({ id: f{filepath.stem}-{idx}, source: str(filepath), content: chunk }) return docs if __name__ __main__: for doc in load_docs(): print(doc)这个脚本做的事情很简单读取data/docs目录下的所有.txt文件按段落拆分成 chunk并给每个 chunk 生成唯一 ID。6.4 构建向量索引接着写build_index.py把每个 chunk 通过嵌入模型转成向量并保存到本地文件# 文件路径skills/knowledge-base-assistant/scripts/build_index.py import json from pathlib import Path import numpy as np from sentence_transformers import SentenceTransformer from load_docs import load_docs INDEX_PATH Path(data/index/embeddings.npy) META_PATH Path(data/index/meta.json) def build_index(): docs load_docs() model SentenceTransformer(paraphrase-multilingual-MiniLM-L12-v2) contents [doc[content] for doc in docs] embeddings model.encode(contents, normalize_embeddingsTrue) INDEX_PATH.parent.mkdir(parentsTrue, exist_okTrue) np.save(INDEX_PATH, embeddings) meta [{id: doc[id], source: doc[source], content: doc[content]} for doc in docs] META_PATH.write_text(json.dumps(meta, ensure_asciiFalse, indent2), encodingutf-8) print(f索引构建完成共 {len(meta)} 个文档块) if __name__ __main__: build_index()运行python skills/knowledge-base-assistant/scripts/build_index.py注意paraphrase-multilingual-MiniLM-L12-v2是一个常见的中英文多语言嵌入模型。实际项目里你可以根据数据规模、语言、精度要求选择不同的嵌入模型比如 OpenAI 的 text-embedding-3-small、智谱的 embedding 接口等。首次运行会下载模型需要一些时间。6.5 实现检索脚本新建search.py实现相似度检索# 文件路径skills/knowledge-base-assistant/scripts/search.py import json import sys from pathlib import Path import numpy as np from sentence_transformers import SentenceTransformer INDEX_PATH Path(data/index/embeddings.npy) META_PATH Path(data/index/meta.json) def search(query: str, top_k: int 3) - list[dict]: model SentenceTransformer(paraphrase-multilingual-MiniLM-L12-v2) query_emb model.encode([query], normalize_embeddingsTrue)[0] embeddings np.load(INDEX_PATH) meta json.loads(META_PATH.read_text(encodingutf-8)) scores embeddings query_emb top_indices np.argsort(scores)[::-1][:top_k] results [] for idx in top_indices: results.append({ score: float(scores[idx]), source: meta[idx][source], content: meta[idx][content] }) return results if __name__ __main__: query sys.argv[1] results search(query) for r in results: print(f来源: {r[source]}, 相似度: {r[score]:.4f}) print(r[content]) print(---)这个脚本的核心是向量点积运算。因为我们在构建索引时做了归一化所以点积等价于余弦相似度。测试一下python skills/knowledge-base-assistant/scripts/search.py 报销流程是什么如果文档和代码正确你应该能看到与“差旅报销流程”相关的内容被检索出来。6.6 编写 SKILL.md 让 Agent 学会“先检索后回答”现在写关键的SKILL.md--- name: knowledge-base-assistant description: 基于企业知识库回答用户问题。当用户询问制度、流程、规范、报销、运维、项目立项等内容时使用本技能。 --- # 知识库问答技能 你的任务是基于知识库回答用户问题禁止凭空编造答案。 ## 工作流程 1. 理解用户问题提取核心关键词。 2. 运行以下命令检索知识库 bash python skills/knowledge-base-assistant/scripts/search.py 用户问题阅读检索结果找到与问题相关的片段。如果检索结果与问题相关基于片段内容组织回答。如果检索结果不相关或为空明确告知用户“知识库中没有找到相关信息”不要猜测。回答要求每个结论都必须引用来源格式为【来源文件名】。回答使用简洁的条目列表。如果问题涉及流程按步骤输出。示例用户问题报销流程是什么回答 根据知识库中的《差旅报销流程》报销步骤如下出差前在 OA 系统提交出差申请。出差结束后 5 个工作日内提交差旅报销单。报销单需附上发票、行程单和审批截图。财务审核通过后 7 个工作日内到账。 【来源travel_expense.txt】这里的关键是**把“检索”变成 Skill 执行流程的固定步骤而不是让大模型自己去猜答案。** 这样既利用了 RAG 的知识检索能力又避免了模型幻觉。 ### 6.7 主程序集成 在 main.py 中挂载两个技能 python # 文件路径main.py from claude_agent_sdk import ClaudeAgent def main(): agent ClaudeAgent( nameenterprise-assistant, skills_dir./skills ) questions [ 报销流程是什么, 生产环境变更有什么要求, 如何申请服务器权限, # 这个知识库没有用于测试拒答能力 ] for q in questions: print(f用户: {q}) response agent.run(q) print(fAgent: {response}) print( * 50) if __name__ __main__: main()运行之后观察两个现象前两个问题应该正常回答且带引用来源。第三个问题知识库没有相关内容Agent 应该明确提示找不到而不是编一个流程出来。这就是“RAG Skills”组合的价值既能回答也能诚实地说“不知道”。7. 进阶实战Multi-Agent 场景下的 Skills 编排7.1 场景设定接下来我们提高一点复杂度模拟一个 Multi-Agent 场景。假设我们要做一个“项目周报生成器”输入本周的工作记录输出一份结构化周报。这个任务拆成两个子任务需求分析 Agent从工作记录中提取关键成果、风险、待办。报告生成 Agent把提取的信息整理成周报格式。两个 Agent 各自挂载不同的 Skills。这样分工明确也便于单独升级某一环节。7.2 创建两个 Skill先创建“事项提取 Skill”--- name: work-log-extractor description: 从工作日志中提取成果、风险和待办事项。 --- # 事项提取技能 ## 工作流程 1. 阅读用户提供的工作日志。 2. 提取以下三类信息 - 成果已完成的重要事项。 - 风险影响进度的潜在问题。 - 待办下周需要推进的事项。 3. 输出 JSON json { achievements: [事项1, 事项2], risks: [风险1], todos: [待办1] }注意事项只提取日志中明确提到的内容不要补充。再创建“周报生成 Skill” markdown --- name: weekly-report-writer description: 根据结构化事项生成项目周报。 --- # 周报生成技能 ## 输入 接收 JSON 格式的事项数据 json { achievements: [], risks: [], todos: [] }工作流程将成果按优先级排序。为每个成果写一句话进展说明。风险部分给出应对建议。待办部分给出下周计划。输出 Markdown 格式周报。输出格式# 项目周报 ## 本周成果 - ... ## 风险与应对 - ... ## 下周计划 - ...注意事项不要在周报中添加数据来源之外的内容。### 7.3 主程序编排 在 Python 中我们可以模拟两个 Agent 的接力过程。由于不同版本的 Agent SDK 对多智能体编排的支持不同这里用伪代码展示流程思想 python # 文件路径main_multi.py import json from claude_agent_sdk import ClaudeAgent def run_multi_agent_workflow(raw_log: str): # Agent 1: 事项提取 extractor ClaudeAgent( nameextractor, skills_dir./skills ) extract_result extractor.run( f请提取工作日志中的关键事项\n{raw_log} ) try: structured_data json.loads(extract_result) except json.JSONDecodeError: print(提取结果不是合法 JSON请检查 extractor 输出) return # Agent 2: 周报生成 writer ClaudeAgent( nameweekly-report-writer, skills_dir./skills ) report writer.run( f请根据以下事项生成周报\n{json.dumps(structured_data, ensure_asciiFalse)} ) return report if __name__ __main__: log 本周完成了用户登录模块的重构联调测试通过。 支付接口的第三方回调存在延迟需要关注。 下周计划接入消息推送服务。 report run_multi_agent_workflow(log) print(report)这种编排方式的优势是extractor只负责结构化writer只负责写作格式互不干扰。如果你想调整周报模板只需要改weekly-report-writer的 SKILL.md不需要动提取逻辑。7.4 Multi-Agent 的实际工程化建议在实际项目中多智能体比单 Agent 更难调试因为问题可能出在任何一个环节。我建议你注意以下几点给 Agent 起明确的名字和职责对应。严格控制传递数据的格式最好统一为 JSON。每一步都记录日志便于定位是哪个 Agent 出了问题。不要盲目追求“多 Agent”。如果单 Agent 两三个 Skills 能解决问题就用简单的方案。多 Agent 适合任务边界清晰、需要不同角色专业知识的场景。8. 常见问题与排查思路在实际开发 Agent Skills 时我遇到过不少问题。这里整理成表格方便你按图索骥。问题现象常见原因解决思路Agent 没有加载对应 SkillSKILL.md 中的 description 描述不够具体Agent 无法匹配合适技能在 description 中增加任务关键词和场景词例如“报销”“审查代码”“周报”SKILL.md 内容太复杂Agent 执行时丢失步骤步骤太多或没有编号拆分为多个技能每个技能专注一件事步骤控制在 5-7 步以内辅助脚本执行报错脚本依赖未安装或路径不正确在 SKILL.md 中明确写出依赖安装命令代码中尽量使用相对路径大模型仍然编造知识库没有的内容RAG 检索结果与问题不相关或检索为空时没有拒答逻辑在 SKILL.md 中强制要求“检索结果不相关时必须告知用户找不到”输出格式不稳定没有给出明确的输出格式示例在 SKILL.md 中用代码块给出 JSON 或 Markdown 示例并声明“严格按照格式输出”中英文混排效果差嵌入模型对中文支持不够切换为支持中文的嵌入模型并在构建索引时统一清洗文本Skill 更新后 Agent 还在用旧行为框架缓存了技能内容确保技能目录更新后重置会话或重启 Agent 进程多个 Skill 互相干扰不同技能的 description 相似Agent 选错每个技能职责单一description 中加入差异化关键词9. 最佳实践与工程建议9.1 命名与目录组织Skill 的命名建议采用“短横线命名法”全小写例如code-reviewer。目录结构要保持“一技能一目录”不要把所有脚本放在同一个目录下。推荐的目录模板是skill-name/ ├── SKILL.md ├── scripts/ # 辅助脚本 ├── references/ # 参考文档、模板 └── assets/ # 图片、静态资源9.2 SKILL.md 写作质量写作质量直接决定 Agent 执行效果。我的建议是每个 Skill 只解决一个任务不要试图写“万能技能”。步骤尽量控制在 3-8 步太长会降低执行准确率。在每个需要自定义动作的地方都给出代码示例或输出示例。明确写清“不要做什么”例如“不要修改源代码”“不要编造数据”。描述中嵌入常见的业务关键词提升智能体匹配准确率。9.3 安全与权限Skills 里的脚本会直接执行在你的服务器或本地环境里因此权限控制非常重要。不要在 SKILL.md 或脚本里硬编码 API Key、数据库密码等敏感信息。使用环境变量或专门的密钥管理服务。脚本在执行文件操作时限制可访问的目录范围。如果 Skill 要访问外部 API尽量使用最小权限的只读密钥。不要让大模型直接执行用户提供的任意 Shell 命令必要时做命令白名单校验。9.4 性能优化Agent Skills 的性能瓶颈通常出现在两个地方模型推理和脚本执行。尽量让检索、文件 I/O 等耗时操作在脚本中完成减少大模型的反复推理。如果 RAG 索引很大优先使用专业向量数据库而不是每次启动都重新构建索引。在SKILL.md中告诉 Agent 只在必要时调用脚本而不是每次对话都执行。对于频繁调用的技能可以考虑缓存检索结果。9.5 测试与版本管理技能包本质上也是代码应该纳入版本管理。给每个 Skill 写一个README.md或直接在SKILL.md中记录适用场景和变更记录。修改 SKILL.md 后用准备好的测试用例跑一遍观察输出是否变化。使用 Git 管理技能目录方便回溯。当技能行为发生较大变化时可以给技能名称加版本后缀如code-reviewer-v2便于对比。9.6 生产环境注意事项在上线 Skills 到生产环境前建议做一次完整的“红队测试”用各种边界输入测试 Agent 会不会乱答、会不会执行危险操作、会不会泄露内部信息。考虑到大模型本身的不确定性任何输出都建议经过一层审核或人工确认尤其是涉及财务、法律、医疗等敏感场景。10. 总结与学习路线到这里我们已经把 Agent Skills 从概念一路讲到了 Multi-Agent 场景并且动手完成了两个可运行的技能包。回顾一下核心要点其实就四条第一Skill 是“能力包”它解决的是大模型在具体任务上不稳定、不专业的问题。一个 SKILL.md 文件加上几个辅助脚本就能让 Agent 执行一类特定任务。第二RAG 管知识Skills 管动作。两者可以组合使用让 Agent 既知道该查什么也知道该怎么回答。用“先检索、后回答、不确认不瞎编”这套规则能显著降低模型幻觉。第三Multi-Agent 不是装饰品而是任务拆分的手段。在多 Agent 场景中Skills 一方面让每个 Agent 各司其职另一方面保证了 Agent 之间传递的数据格式可控。第四工程化意识要贯穿始终。目录组织、命名规范、敏感信息保护、版本管理、测试用例这些看似日常的操作才是 Agent 项目能不能长期稳定运行的关键。如果你是从零开始我的建议学习路线是这样先拿一个熟悉的小任务练手比如给代码扫描工具写一个 Skill再尝试把企业文档接成 RAG 问答技能最后才是搭建多 Agent 流程。不要一上来就追求复杂的 Multi-Agent 系统先把单个技能的质量打磨到位。Agent Skills 相关的生态还在快速演进框架和工具链的细节会持续变化。但“把任务能力结构化、封装成技能”这个思路在很长一段时间内都会是大模型应用开发的核心方法之一。建议你搭建一个自己的技能仓库把工作中反复出现的任务逐步沉淀成 Skills这会是你在 AI 应用开发路上最值得的一笔投资。如果本文对你有帮助欢迎收藏备用也欢迎在评论区分享你踩过的坑。下一篇我可以继续拆解 Agent Skills 在垂直行业比如农业、金融、教育的落地实践咱们下次见。