构建具备 Skills 调用能力的 Agent —— 学习笔记
环境基准:LangChain 1.1 / Claude Code 2.1,示例模型为 DeepSeek(兼容 OpenAI 格式均可)。 本文主线回答三个问题:
- 需求说明:为什么 Agent 需要"Skills 调用能力"?
- 如何实现一个 Skill:一个 Skill 长什么样?怎么写才不踩坑?
- 如何让 Agent 调用 Skills:Agent 从"看到技能"到"执行技能"的完整机制是什么?
目录
- 需求说明:为什么要给 Agent 配 Skills
- 核心原理:Agent 是如何调用 Skills 的
- 如何实现一个 Skill
- 反面冲击:三个"坏 Skill"案例
- 设计范式:拿到需求后怎么选型
- 实战:从零创建 document-summarizer
- 评估与进化:创建完成只完成 20%
- 总结
一、需求说明:为什么要给 Agent 配 Skills
1.1 问题背景
Agent(智能体)本身只会"对话 + 调工具"。当任务变复杂(如"把这份 PDF 总结成汇报摘要"、"帮我部署这个服务")时,如果每次都靠模型临场发挥,会出现三类问题:
| 问题 | 表现 |
|---|---|
| 每次都要重新"教" | 相同任务每次都重复一遍操作步骤,浪费 token 且结果不稳定 |
| 知识散落、无法复用 | 好的流程沉淀在聊天记录里,换一个会话就丢了 |
| Skills 一多就"爆炸" | 当 Agent 拥有 10 个以上技能时,若缺乏设计规范,会出现触发混乱、维护困难、无法复用的"技能爆炸"状态 |
1.2 Skill 是什么(一个比喻先讲清楚)
Skill 的本质:一份"可执行的流程规范",而不是"知识百科"。
- 好的 Skill 像"作战指令":清晰、简洁、可执行。
- 坏的 Skill 像"参考手册":详尽、冗长、需要理解。
一个 Skill 的价值判断标准(什么时候值得做成 Skill):
- 任务会重复出现;
- 操作步骤相对稳定;
- 手工执行成本高、易出错;
- 输出质量可以被验证。
1.3 需求归纳
我们要构建的 Agent 需要:
- 自动发现技能:不需要硬编码,把 Skill 文件放进目录就能被识别;
- 按需触发:根据用户请求,判断该不该用某个 Skill(该触发时触发、不该触发时不触发);
- 读取并执行:触发后能读取 Skill 的定义文件,按其中步骤调用工具完成任务;
- 可维护、可进化:Skill 可以独立开发、测试、迭代,而不用改 Agent 代码。
二、核心原理:Agent 是如何调用 Skills 的
这一节是全文的机制核心。整个调用链可以概括为"扫描 → 注入 → 匹配 → 读取 → 执行"五步。
2.1 全景流程图
┌─────────────────────────────────────────────┐
│ ① 扫描:scan_skills(skills_dir) │
│ 遍历 skills/ 下所有 SKILL.md │
│ 解析 YAML frontmatter │
└──────────────────┬──────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ ② 生成 XML 快照 │
│ 只有 name / description / location │
│ (不含正文,节省 token) │
└──────────────────┬──────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ ③ 注入系统提示词 │
│ build_system_prompt() 把快照拼进 │
│ System Prompt │
└──────────────────┬──────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ ④ 用户提问 → 模型匹配 │
│ 拿用户意图和各 Skill 的 │
│ description 做判断 │
└──────────────────┬──────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ ⑤ 命中 Skill → 调用 read_file │
│ 读取该 Skill 的完整 SKILL.md │
└──────────────────┬──────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ ⑥ 按正文步骤执行 │
│ 调用 terminal / fetch_url 等工具 │
│ 完成具体任务 │
└─────────────────────────────────────────────┘
2.2 第①②步:scan_skills —— 只读"目录页",不读"正文"
scan_skills 只解析每个 SKILL.md 顶部的 YAML frontmatter(--- 包裹的那几行),提取 name、description、location 三个字段,拼成 XML 字符串:
<available_skills>
<skill>
<name>get_weather</name>
<description>查询指定城市的天气信息</description>
<location>./skills/get_weather/SKILL.md</location>
</skill>
</available_skills>
为什么只注入元数据、不注入全文? 这就是"渐进式披露"思想:Agent 每轮对话都要带着系统提示词,如果 100 个 Skill 的全文全部塞进去,上下文直接爆炸。只给"目录页"(几十个 token),等真正用到时再去读全文,是最省资源的做法。
2.3 第③步:注入 System Prompt —— 立"规矩"
快照会被拼进一段协议式的系统提示词,明确告诉模型"技能怎么用":
## 可用技能
{skills_snapshot} ← 上一步生成的 XML 快照在这里展开
## 技能调用协议
当你需要使用某个技能时,必须:
1. 先使用 read_file 工具读取技能定义文件(location 字段指定的路径)
2. 仔细阅读 SKILL.md 中的执行步骤
3. 根据步骤调用相应的工具(fetch_url、terminal 等)
禁止直接猜测技能用法,必须先读取文件!
关键设计:"禁止猜测、必须先读文件"。模型很擅长"编",如果不强制它先读 SKILL.md,它很可能凭训练知识瞎编步骤。这条协议保证了 Skill 的定义文件是唯一的执行依据。
2.4 第④⑤⑥步:匹配 → 读取 → 执行
- 匹配是模型自己的"语义判断":拿用户请求和每个 Skill 的
description对比。所以 description 写得好不好,直接决定触发准不准(后面反面案例会反复证明这一点)。 - 读取通过
read_file工具完成。Agent 初始化时除了 Skills 对应的工具,还内置read_file(读文件)、fetch_url(取网页)、terminal(沙箱执行命令)三个基础工具。 - 执行时模型按 SKILL.md 正文的步骤,调用 terminal 跑脚本、调用 fetch_url 拿数据等。
2.5 对应的初始化代码(课件原文,注释已补充)
from pathlib import Path
from standalone_agent import scan_skills, initialize_agent, chat, chat_stream
# 指定 Skills 目录:每个子目录 = 一个 Skill,必须包含 SKILL.md
skills_dir = Path("./skills")
# 第一步:扫描目录,得到 XML 快照(Agent "知道自己会什么" 的来源)
skills_snapshot = scan_skills(skills_dir)
# 第二步:初始化 Agent(内部会自动执行 build_system_prompt 把快照注入系统提示词)
agent = initialize_agent(
api_key=api_key, # 大模型 API Key(从 .env 加载,不要硬编码)
base_url="https://api.deepseek.com", # API 基础地址(任何 OpenAI 兼容接口均可)
model="deepseek-chat", # 模型名称
temperature=0.7, # 温度:日常对话用 0.7;创建/评估 Skill 时建议降到 0.1-0.3 提升稳定性
skills_dir=skills_dir, # Skills 目录,初始化时会扫描
base_dir=Path(".") # 项目根目录(read_file 等工具的沙箱边界)
)
# 第三步:对话即可。Agent 会在需要时自动触发 Skill
response = chat(agent, "帮我用 Stripe 创建一个 100 美元的支付订单")
项目结构约定:
project/ ├── standalone_agent.py # Agent 核心模块(扫描/初始化/对话) ├── requirements.txt # 依赖列表 ├── .env # 环境变量(API Key),务必加入 .gitignore └── skills/ # Skills 目录 ├── get_weather/ │ └── SKILL.md # 一个 Skill = 一个目录 + 一个 SKILL.md └── search_web/ └── SKILL.md好处:新增 Skill 无需改 Agent 代码,建目录、写文件、重启即可被扫描到。
三、如何实现一个 Skill
3.1 三层架构(理解一切设计的钥匙)
一个设计良好的 Skill 应该清晰地分为三层:
┌────────────────────────────────────────────────────────┐
│ 路由层 · frontmatter │
│ 位置:SKILL.md 顶部 YAML,3-5 行 │
│ 职责:决定"要不要激活" │
│ 内容:name + description + triggers │
└───────────────────────────┬────────────────────────────┘
▼
┌────────────────────────────────────────────────────────┐
│ 控制层 · SKILL.md 正文 │
│ 位置:60-100 行 Markdown │
│ 职责:决定"怎么做决策" │
│ 内容:Goal / Workflow / Constraints / Validation │
└───────────────────────────┬────────────────────────────┘
▼
┌────────────────────────────────────────────────────────┐
│ 执行层 · 独立子目录 │
│ 位置:scripts/ + references/ + assets/ │
│ 职责:负责"具体怎么做" │
│ 大小:不限,按需扩展 │
└────────────────────────────────────────────────────────┘
判断标准很简单:写 SKILL.md 时随时问自己"这段内容应该放哪一层"。如果你发现自己在 SKILL.md 里写大段代码或详细文档,说明你混淆了控制层和执行层的职责。
3.2 标准 Skill 目录结构
my-skill/
├── SKILL.md # 主文件(路由层+控制层,建议 60-500 行,核心 Skill 100-200 行最佳)
├── scripts/ # 可执行脚本(自动化重复操作),按功能拆分成多个文件
│ ├── process_data.py
│ ├── validate.py
│ └── cleanup.sh
├── references/ # 参考文档(领域知识、详细规则),分 core/(必读)和 advanced/(可选)
│ ├── core/
│ │ ├── api-guide.md
│ │ └── examples.md
│ └── advanced/
│ └── edge-cases.md
├── assets/ # 输出素材(输出模板、示例输出),是"输出素材"而非"输入文档"
│ ├── templates/
│ └── examples/
├── agents/ # 子 Agent 定义(可选,仅在复杂协作时使用)
└── tests/ # 测试用例(可选)
各目录的"读者"不同——这是关注点分离的本质:
| 信息类型 | 存放位置 | 变化频率 | 谁来读 |
|---|---|---|---|
| 执行指令 | SKILL.md | 低(设计时确定) | Agent |
| 代码实现 | scripts/*.py | 中(功能迭代) | Python 解释器 |
| 配置参数 | assets/templates/ 或环境变量 | 高(每次使用可能不同) | 脚本运行时 |
| 领域知识 | references/ | 低(相对稳定) | Agent(按需引用) |
3.3 SKILL.md 长什么样(一个真实 v1 的 frontmatter)
---
name: document-summarizer
# description 是"路由层"最关键的字段:
# 必须写清"做什么 + 什么时候用 + 什么时候不用",中英混合有利于触发匹配
description: >-
将长文档(PDF、DOCX、Markdown、TXT)压缩成结构化摘要。
Use this skill when the user wants to summarize, extract key points,
or generate a report-ready abstract from a long document.
触发场景:总结文档、提炼要点、生成汇报摘要、压缩长文。
不触发:翻译、改写、全文问答、复杂决策分析。
# 正面触发示例:什么样的请求"应该"触发本 Skill
triggers:
- 帮我总结这份文档
- 提炼这篇文章的要点
- 生成汇报摘要
- summarize this document
# 反面示例:什么样的"邻居请求"不应触发(这是防止误触发的关键!)
non_triggers:
- 帮我翻译这段话
- 改写这篇文章
- 这份文档里有没有提到 X
- 分析这个数据集
version: "1.0"
paradigm: architect # 本 Skill 采用的主导范式(见第五章)
---
正文部分则只写"流程",示例:
## Workflow
1. 验证输入:检查文档格式是否支持(PDF/DOCX/MD)
2. 提取文本:调用 `scripts/extract_text.py`
3. 分块处理:如果文档 >5000 字,调用 `scripts/chunk_document.py`
4. 生成摘要:使用 LLM API 生成结构化摘要
5. 格式化输出:应用 `assets/summary-template.md` 模板
6. 验证完整性:检查摘要是否覆盖所有关键章节
## Constraints
- 只处理文档摘要类任务,不做翻译、改写、问答。
- 摘要长度不超过原文 30%。
## Validation
- 摘要包含文档核心信息
- 结构清晰(标题/要点/结论)
- 长度适中
3.4 三条底线设计规则
这三条规则分别回答三个问题:边界怎么定、结构怎么放、信息怎么收。
规则 1:单一职责原则(SRP)——一个 Skill 只做一件事
一个 Skill 只解决一个明确的问题,只有一个清晰的调用理由。可以用三个测试快速判断职责是否单一:
| 测试 | 做法 | 不合格的信号 |
|---|---|---|
| 一句话描述测试 | 用一句话描述功能,若需要"和/或/以及"连接词 | "创建项目和生成文档以及运行测试" → 三个职责 |
| 变化原因测试 | 列出所有会导致修改的原因,超过一个就不单一 | 模板变化、文档规范变化、测试框架升级都会改它 |
| 调用场景测试 | 列出调用场景,场景之间没有强关联就不单一 | 建骨架、写文档、跑测试是三件独立的事 |
拆分方法:按用户要解决的问题拆(问题域分解),不要按技术栈拆。宁可多几个小 Skill,也不要一个大而全的 Skill。
规则 2:关注点分离(SoC)——SKILL.md 只写执行流程
SKILL.md 只包含执行指令(做什么、怎么做、输入输出、异常处理);代码实现放 scripts/;配置参数放 assets/templates/ 或环境变量;详细知识放 references/。
踩坑预警:很多人喜欢在 SKILL.md 里嵌大量代码示例,认为"更详细"。实际上代码示例应放独立文件,SKILL.md 只需说明"调用哪个脚本、传什么参数"。
规则 3:信息精炼原则——只保留执行必需的信息
公式:
SKILL.md 内容 = 执行步骤 + 关键参数 + 异常处理 + 文档引用
从冗长文档提炼要点用"三步过滤法":
- 识别执行路径:只留"完成任务需要执行哪些步骤",删掉背景介绍、原理解释;
- 提取关键参数:只留必需参数和影响结果的参数,删掉可选参数和默认值;
- 标注异常情况:只留"哪些情况会失败、如何处理",删掉边缘情况和理论分析。
嵌入还是引用的选择标准:
| 信息类型 | 执行必需? | 处理方式 |
|---|---|---|
| 执行步骤 / 关键参数 / 异常处理 | 是 | 嵌入 SKILL.md |
| 设计理念 / 完整 API 文档 | 否 | 引用外部文档(references/ 或 URL) |
| 示例代码 | 视情况 | < 20 行嵌入,> 20 行引用 |
规则冲突时的优先级
SRP > SoC > 信息精炼。职责边界是基础——边界错了,后面把结构整理得再漂亮,也只是把不该放一起的东西整理得更漂亮而已。
3.5 设计检查清单(发布前自查)
| 检查项 | 通过标准 | 不通过示例 |
|---|---|---|
| 职责唯一性 | 一句话能说清职责 | "负责数据处理、日志记录和邮件通知" |
| 变更原因单一 | 只有一类需求变更会影响它 | 需求、日志格式、邮件模板变更都会影响 |
| 结构完整性 | 至少有清晰的执行指令部分 | 只有一段文字,无结构标记 |
| 关注点独立 | 执行流程/上下文/外部依赖分开表达 | 全部混在一起 |
| 长度合理性 | 核心 Skill 100-200 行,复杂 Skill 200-500 行 | 超过 1000 行 |
| 冗余消除 | 每条信息只出现一次 | 同一配置项在多处重复说明 |
四、反面冲击:三个"坏 Skill"案例
先看坏的,才知道好的为什么好。三个案例分别对应三条规则的反面。
4.1 案例 1:ai-dev-assistant(万能瑞士军刀)——违反 SRP
需求(设计者的初衷):做一个"全能开发助手",代码审查、Bug 修复、重构、测试、文档、部署、优化、安全审计全都能干。
实测现象:
# 测试方法:用三种不同请求喂给 Agent,观察触发行为
response1 = chat(agent, "帮我看看这段代码有没有问题") # 触发了 ai-dev-assistant
response2 = chat(agent, "这个函数报错了,帮我修复一下") # 又触发了 ai-dev-assistant
response3 = chat(agent, "这段代码运行太慢了,能优化吗") # 还是它!
无论用户说什么,Agent 都倾向于触发这个 Skill——因为它的 description 覆盖了几乎所有开发场景,形成**"触发污染"**:一个宽泛的 Skill 会抢走其他 Skills 的触发机会。执行时它还要不断做分支判断("这是审查还是优化?"),效率极低,容易卡住。
问题总结:
| 问题类型 | 具体表现 | 根本原因 |
|---|---|---|
| 触发混乱 | 任何开发相关请求都触发 | 描述过于宽泛,缺乏明确边界 |
| 执行低效 | 不断分支判断,容易卡住 | 步骤爆炸,缺乏清晰执行路径 |
| 维护困难 | 487 行 SKILL.md,改一处影响全局 | 违反单一职责原则 |
教训 → 规则 1:一个 Skill 只做一件事,触发描述要精准。
4.2 案例 2:code-bomb-deployer(厨房水槽)——违反 SoC
需求(设计者的初衷):做一个部署 Skill,把所有代码、配置、文档、示例都塞进一个 SKILL.md(312 行,含 6 个完整脚本),"一站式"交付。
实测现象:让 Agent"加载 sales.csv 并清洗数据",它可能:
- 直接执行 SKILL.md 里的示例代码(但示例里硬编码的是
data.csv,文件不存在,执行失败); - 把代码示例当成执行步骤的一部分,逻辑错乱;
- 在代码示例和执行指令之间反复横跳,不知道该做什么。
根本问题:Agent 无法区分哪些是"指令"、哪些是"参考资料"。
| 问题类型 | 具体表现 | 根本原因 |
|---|---|---|
| 结构混乱 | 代码、配置、文档混杂 | 缺乏关注点分离 |
| 执行混乱 | 分不清指令和示例 | 没有明确的执行边界 |
| 维护困难 | 改代码影响文档,改文档影响流程 | 耦合度过高 |
重构对照(用 Operator 范式,见第五章):
- 重构前:SKILL.md 387 行(含 6 个完整脚本),scripts/ 为空;
- 重构后:SKILL.md 仅 60 行(只保留"什么时候调用哪个脚本"的决策逻辑),6 个脚本全部独立放入 scripts/。
教训 → 规则 2:代码、配置、文档要分离,SKILL.md 只写执行流程。SKILL.md 负责"什么时候调用哪个脚本",不负责"脚本里写什么代码"。
4.3 案例 3:encyclopedia-translator(复制粘贴文档)——违反信息精炼
需求(设计者的初衷):做一个 API 翻译 Skill,把 Stripe、Twilio、SendGrid 等官方文档全部复制进 SKILL.md(共 2847 行),"把所有信息给 Agent,它自己学会怎么用"。
实测现象:
import time
start_time = time.time()
response = chat(agent, "帮我用 Stripe 创建一个 100 美元的支付订单")
print(f"总耗时: {time.time() - start_time:.2f} 秒") # 结果远超正常水平,可能超过 3 分钟
- 执行缓慢:Agent 要花大量时间阅读 2847 行文档,仅触发判断就可能耗时 18 秒以上;
- Agent 迷失:流式输出里,Agent 在大段复述文档内容(Authentication 说明、PaymentIntent 字段、可选参数……),而不是执行任务;
- 成功率低:关键信息被淹没,Agent 根本无法从海量文档中提取出"应该做什么"。
教训 → 规则 3:信息要精炼,详细文档通过链接引用。
4.4 三案例总览(从反面看本质)
| 案例名称 | 核心问题 | 症状表现 | 根本原因 | 对应设计原则 |
|---|---|---|---|---|
| ai-dev-assistant | 职责不清 | 触发混乱、执行低效 | 违反单一职责原则 | 一个 Skill 只做一件事 |
| code-bomb-deployer | 结构混乱 | 代码与文档混杂 | 缺乏关注点分离 | 代码、配置、文档要分离 |
| encyclopedia-translator | 信息过载 | Agent 迷失在文档中 | 没有提炼执行要点 | 信息要精炼,文档用链接 |
更深层的设计误区:很多人把 Skill 当成"给 AI 的知识库",而不是"给 AI 的执行指令",所以总想"塞进更多信息",而不是"提炼关键步骤"。记住:Skill 是可执行的流程规范,不是知识百科。
五、设计范式:拿到需求后怎么选型
5.1 七种范式全景
业界总结出 7 种设计范式,前 4 种覆盖约 85% 的实际场景,是必须掌握的核心范式:
| 范式 | 使用频率 | 一句话理解 | 典型场景 |
|---|---|---|---|
| Operator(工具链封装) | 35% | 让 AI 稳定地把确定的事做完 | 文档处理、数据转换、部署流程 |
| Scout(环境不确定任务) | 25% | 让 AI 先侦察再行动 | 代码分析、系统诊断、Bug 定位 |
| Partner(交互式任务) | 20% | 让 AI 和你一起做决定 | 需求澄清、设计评审、风险决策 |
| Navigator(路由和查找) | 15% | 让 AI 把问题送到正确的路上 | 多阶段搜索、条件分发、资源导航 |
| Philosopher(原则驱动) | 进阶 5% | 让 AI 当裁判,判断"做得合格吗" | 代码规范检查、质量门禁、安全审计 |
| Architect(系统设计) | 进阶 5% | 让 AI 先画路线图再动手 | 学习路径、架构规划、项目蓝图 |
| Orchestrator(多工具协调) | 高级 5% | 让 AI 组队干活 | 多模型协作、并行调度、复杂工作流 |
5.2 四种核心范式的设计要点
Operator(工具链封装)
- 适用判断:操作步骤确定、涉及工具链、需要严格验证、人工易出错 → 选它;
- 设计重点:脚本优先 / 严格验证(每步有成功标准)/ 错误处理(失败如何回滚)/ 幂等性(重复执行结果一致)。
Scout(侦察)
- 适用判断:环境不确定、需要多轮探索、证据驱动、可能要回溯 → 选它;
- 典型流程:探测(
ls/grep快扫)→ 分析(读文件提假设)→ 验证(跑测试/查日志)→ 报告(问题+证据+结论+建议)。四个阶段会随新证据回跳迭代; - 设计重点:侦察优先 / 证据驱动(每个结论都要有文件路径+行号)/ 多轮探索 / 状态记录(避免重复探索)。
Partner(协作)
- 适用判断:需求模糊、主观判断、风险决策、需要状态保持 → 选它;
- 设计重点:对话契约(每轮对话的目的和格式)/ 人工检查点(高危操作前暂停确认)/ 状态保持(用户选过的不再问)/ 渐进式澄清(从粗到细收敛);
- 核心难点——什么时候该问用户(AskUserQuestion):
| 该问 | 不该问 |
|---|---|
| 需求有多种合理解释 | 可以自己探测获取的信息(文件是否存在) |
| 风险操作需要确认 | 有明确最佳实践的(编码格式) |
| 只有用户知道的信息(API Key) | 过于细节的技术问题 |
Navigator(路由)
- 适用判断:多个子任务按条件选择、多阶段搜索、资源导航、强调快速失败 → 选它;
- 设计重点:强分支规则(条件清晰互斥可验证)/ 清晰引用导航(告诉用户下一步去哪)/ 快速失败 / 漏斗式筛选(100 候选 → 20 初筛 → 5 精选);
- 决策树四要求:互斥性、完备性、可验证性、早失败。
5.3 三种进阶范式(按需学习,不要过早升级)
- Philosopher:先定义可验证的原则,再做判断裁决("证据优先于断言")。升级信号:核心范式能把事做完,但你无法稳定判断结果是否达标。
- Architect:全局规划多阶段路径(阶段划分 + 依赖关系 + 里程碑)。升级信号:缺少一张完整的阶段地图。
- Orchestrator:协调多个工具/模型协同(任务分解 + 资源调度 + 状态同步 + 故障恢复)。升级信号:单一 Agent 无法兼顾速度、质量与协调成本。
5.4 选型决策表(从上往下,第一个"是"即答案)
| 判断问题 | 是 → 选用 | 层级 |
|---|---|---|
| 操作是否确定? | Operator | 核心 |
| 环境是否不确定? | Scout | 核心 |
| 是否需要人工确认? | Partner | 核心 |
| 是否需要条件路由? | Navigator | 核心 |
| 是否需要定义规则和验证合规性? | Philosopher | 进阶 |
| 是否需要规划多阶段路径? | Architect | 进阶 |
| 是否需要协调多个工具/模型? | Orchestrator | 进阶 |
三条选型原则:
- 优先核心范式,95% 的场景够用;
- 范式可混合但要有主导范式(如 Operator 为主,个别步骤引入 Partner 的确认机制);
- 避免过度设计:过早升级进阶范式会让任务更重、更慢、更难控制。
六、实战:从零创建 document-summarizer
本案例完整走一遍"需求分析 → 范式选择 → 资源规划 → 实现 → 验证"的创建流程,并演示 Agent 驱动的创建工作流。
6.1 第一步:需求分析与边界定义
需求:用户上传一个长文档(PDF/Word/Markdown),系统自动生成结构化摘要。
创建前必须回答四个关键问题:
| 关键问题 | 回答 |
|---|---|
| 它解决什么问题? | 从长文档中稳定提取结构化摘要 |
| 什么情况下触发? | 用户明确要求总结、提炼、压缩文档内容 |
| 什么情况下不触发? | 翻译、改写、问答、原文读取、复杂分析 |
| 怎样算成功? | 输出结构清晰、覆盖核心内容、明显压缩且可验证 |
触发边界比实现细节更重要。"帮我把文档翻译成英文"和"帮我总结文档"都和文档有关,但目标完全不同。如果不明确写 non_triggers,就会回到"大而全 Skill"的陷阱。
成功标准(v1):
- 能识别常见文档类型并成功读取内容;
- 能输出结构化摘要(不是散乱自由文本);
- 摘要覆盖原文主要章节、核心观点和关键结论;
- 输出长度明显压缩,但不丢失关键事实。
6.2 第二步:范式选择
任务特性分析:输入明确、流程确定、工具链固定、输出可预定义、每步可验证 → 天然是确定性流程。
| 范式 | 是否适合 | 原因 |
|---|---|---|
| Operator | 是 | 流程确定、工具稳定、可逐步验证 |
| Scout | 一般 | 不需要环境探索 |
| Partner | 一般 | 用户目标通常清晰,不依赖多轮确认 |
| Navigator | 一般 | 重点不是分流而是执行固定流程 |
| Philosopher / Architect / Orchestrator | 否 | 不是审查/规划/协作类任务 |
Operator 的四个落实点:脚本优先、流程明确、验证可见、幂等稳定。
6.3 第三步:资源规划(三层分离)
按"信息放哪一层"的决策规则规划:
- 决定何时触发、调用哪一步 → 放 SKILL.md(frontmatter + workflow + validation,约 85 行);
- 稳定执行的操作逻辑 → 放 scripts/:
extract_text.py(提取文本)、chunk_document.py(长文档分块); - 辅助判断的策略说明 → 放 references/:
summarization-strategies.md(总结策略,按需加载); - 重复使用的固定输出结构 → 放 assets/:
summary-template.md(输出模板)。
最终目录结构:
document-summarizer/
├── SKILL.md # 控制层(85 行)
├── scripts/
│ ├── extract_text.py # 提取文档文本
│ └── chunk_document.py # 分块处理大文档
├── references/
│ └── summarization-strategies.md
└── assets/
└── summary-template.md
6.4 第四步:Agent 驱动的创建流程(关键代码)
这个实战不是人手写 Skill,而是让 Agent 自己借助两个"元 Skill"完成创建:
skill-creator-pro:负责创建 Skill 的元技能(推荐范式 → 定边界 → 规划 → 生成骨架 → 结构审查);skill-benchmark:负责评估 Skill 的元技能(资格检查 → 跑基准 → 提取信号 → 出评分报告)。
准备环境并初始化 Agent:
import sys, os
from pathlib import Path
# 把包含 standalone_agent.py 的目录加入模块搜索路径
BASE_DIR = Path(".").resolve()
sys.path.insert(0, str(BASE_DIR))
# 前置断言:关键文件不存在就直接失败,避免后面莫名报错
assert (BASE_DIR / "standalone_agent.py").exists(), "找不到 standalone_agent.py"
assert (BASE_DIR / "skills/skill-creator-pro/SKILL.md").exists(), "找不到 skill-creator-pro"
assert (BASE_DIR / "skills/skill-benchmark/SKILL.md").exists(), "找不到 skill-benchmark"
# API Key 一律从环境变量读取(.env 已提前 load_dotenv)
API_KEY = os.getenv("DEEPSEEK_API_KEY") or os.getenv("OPENAI_API_KEY", "")
# 初始化创建用 Agent:temperature=0.3(偏低),因为"创建 Skill"需要输出稳定
agent = initialize_agent(
api_key=API_KEY,
base_url=BASE_URL,
model=MODEL,
temperature=0.3,
skills_dir=SKILLS_DIR,
base_dir=BASE_DIR,
)
流式对话助手(观察 Agent 的每一步动作):
async def stream_chat_response(agent, message, history=None):
"""流式打印 Agent 的回答与工具调用,便于观察 Agent 如何读取/执行 Skill"""
full_response = ""
async for event in chat_stream(agent, message, history=history):
if event["type"] == "token": # 模型输出的一个 token
print(event["content"], end="", flush=True)
elif event["type"] == "tool_start": # Agent 开始调用工具(如 read_file / terminal)
print(f"\n--- Tool Start: {event['tool']} ---")
print(event["input"]) # 工具入参(如要读的文件路径)
elif event["type"] == "tool_end": # 工具返回结果
print(event["output"])
elif event["type"] == "done": # 整轮对话结束
full_response = event["content"]
return full_response
Phase 0+1:让 Agent 读元技能 → 推荐范式 → 定边界:
# 注意这个 prompt 的结构:先指定用哪个 Skill,再描述需求边界(覆盖什么、不覆盖什么)
prompt_phase_01 = """
请使用 skill-creator-pro 帮我创建一个新的 Skill:document-summarizer。
这个 Skill 的用途是:
- 将长文档(PDF、DOCX、Markdown)压缩成结构化摘要
- 覆盖:总结、提炼要点、生成汇报版摘要
- 不覆盖:翻译、改写、全文问答、复杂决策分析
请先:
1. 读取 skill-creator-pro 的 SKILL.md 了解工作流
2. 运行 paradigm_recommender.py 推荐最合适的范式
3. 给出 Phase 1 的四个边界问题的答案
"""
response_01 = await stream_chat_response(agent, prompt_phase_01)
Phase 2:资源规划(只规划不落盘,避免单轮任务过重超时):
# 把上一轮对话加入 history,保持上下文连续
history = [
{"role": "user", "content": prompt_phase_01},
{"role": "assistant", "content": response_01},
]
prompt_phase_2 = """
范式已确认。现在请执行 Phase 2:
1. 规划 scripts/、references/、assets/ 各层需要哪些资源文件
2. 说明每个资源文件的用途和内容概要
3. 不要生成文件,只做规划说明
"""
response_2 = await stream_chat_response(agent, prompt_phase_2, history=history)
Phase 3:生成骨架(确定性操作直接用 Python 跑脚本,不走 Agent,又快又稳):
import subprocess, shutil
skill_target = BASE_DIR / "skills" / "document-summarizer"
init_script = BASE_DIR / "skills" / "skill-creator-pro" / "scripts" / "init_skill_pro.py"
# 幂等处理:重跑时先清理旧目录
if skill_target.exists():
shutil.rmtree(skill_target)
# 调用元技能自带的初始化脚本,生成标准骨架
result = subprocess.run(
["python3", str(init_script),
"document-summarizer", # Skill 名称
"--path", str(BASE_DIR / "skills"), # 目标目录
"--paradigm", "architect"], # 主导范式
capture_output=True, text=True
)
# 然后用真实内容覆盖模板占位的 SKILL.md(frontmatter 见 3.3 节)
(skill_target / "SKILL.md").write_text(skill_md_content.strip(), encoding="utf-8")
一个重要的工程判断:文件生成、脚本执行这类"确定性操作",直接用
subprocess调脚本比让 Agent 操作更快、更稳、更省 token。Agent 负责决策和编排,脚本负责执行——这正是 Operator 思想的应用。
Phase 4:结构验证(回到 Agent,让它审查并自修复):
prompt_phase_4 = """
请执行 Phase 4 验证:
1. 运行 skills/skill-creator-pro/scripts/review_skill.py ./skills/document-summarizer
2. 列出所有 high-severity 发现
3. 如果有问题,立即修复后重新验证
4. 最终打印 document-summarizer/SKILL.md 的完整内容
"""
response_4 = await stream_chat_response(agent, prompt_phase_4, history=history)
6.5 第五步:功能验证(能跑起来吗?)
用一段固定的测试文档验证 Skill 是否触发、是否输出结构化摘要:
TEST_DOCUMENT = """
人工智能(AI)正在以前所未有的速度改变各行各业。
在医疗领域,AI 模型检测癌症的准确率已超越部分放射科医生。
……
"""
# 触发式提示词:明确包含"总结"意图,检验路由是否命中
test_prompt = f"请帮我总结以下文档,输出关键要点和一句话摘要:\n\n{TEST_DOCUMENT}"
# 单独初始化一个测试 Agent,避免污染主流程的 history
agent_test = initialize_agent(api_key=API_KEY, base_url=BASE_URL, model=MODEL, skills_dir=SKILLS_DIR)
response_test = await stream_chat_response(agent_test, test_prompt, history=[])
# 自动判定:响应中出现摘要/总结类关键词即视为触发成功
if any(kw in response_test for kw in ["摘要", "总结", "要点", "summary"]):
print("[OK] document-summarizer Skill 触发成功")
else:
print("[警告] 未检测到摘要关键词,请检查 description 是否准确")
v1 的验收结论:能触发、能执行、能给出结构化结果 → 达到"基础可用"门槛。 但"基础可用"≠"真正好用"——到这里只是完成了 20% 的工作,真正让 Skill 成熟的是下一章的评估与进化。
七、评估与进化:创建完成只完成 20%
7.1 破除"自动进化"迷思
Skill 不会自己变聪明——它是一份流程规范,不是会自我训练的生命体。所谓"自主进化"其实是三层组合机制:
| 层级 | 作用 | 自动化程度 |
|---|---|---|
| 遥测采集 | 记录触发、失败、输出质量等数据 | 高 |
| 定期复盘 | 从数据中识别模式与问题(误触发集中在哪类请求?低质量输出出现在哪类文档?) | 中 |
| 实际升级 | 修改 frontmatter / 模板 / 策略(需人工判断优先级) | 低 |
真正决定质量跃迁的是第三层的人工判断。正确顺序:先采集 → 再复盘 → 后升级,跳过前两步直接优化,就是"凭感觉修补"。
7.2 五维度质量评估体系
评估回答三个目标:找出最影响体验的短板、为迭代排优先级、建立版本可比的标准。评估时机:创建后、每次迭代后、长期定期巡检。
| 维度 | 评估什么 | 高分特征(4-5 分) | 低分特征(1-2 分) |
|---|---|---|---|
| 1. 触发质量 | 该触发时触发、不该触发时不触发 | description 精准,含 triggers 和 non_triggers | 触发边界模糊,误触发/漏触发多 |
| 2. 路由质量 | 被触发后能否按流程走完 | 每步动作明确、分支有出口、无矛盾指令 | 步骤含糊("处理文档"vs"调用 extract_text.py") |
| 3. 上下文效率 | SKILL.md 信息密度 | 60-150 行,实现在 scripts/、策略在 references/ | 超 500 行、塞满代码 |
| 4. 复用与确定性 | 关键逻辑是否脚本化、输出是否稳定 | 全脚本化、模板驱动输出 | 靠 Agent 临时推断,"赌运气" |
| 5. 验证强度 | 有无成功标准和失败检查点 | 关键节点全覆盖、输出可量化检查 | 执行黑盒,无验证 |
每维度 1-5 分,满分 25 分。比总分更重要的是最低的那个维度——它就是优先改进对象。1 分 = P0 立即修复;2 分 = 列入下一轮迭代;3 分 = 规划改进;4 分 = 观察稳定性;5 分 = 定期巡检防退化。
7.3 用 skill-benchmark 做客观评估(工具链)
人工评估靠经验、易带主观偏好;工具评估把"我觉得它差"变成"数据证明它差"。评估流程五步:
# Step 1: 资格检查——Skill 是否满足基本可测条件
python ~/.claude/skills/skill-benchmark/scripts/candidate_check.py --skill-path ~/.claude/skills/document-summarizer
# Step 2: 选择评估模式(quick-check 快检 / benchmark-run 正式评估)
python .../benchmark_level.py --mode quick-check --skill document-summarizer
# Step 3: 运行基线对比测试,覆盖三类场景:应触发 / 不应触发 / 边界
python .../run_real_benchmark.py --skill document-summarizer \
--scenarios should-trigger,should-not-trigger,edge --runs 3
# Step 4: 提取触发证据信号(逐条列出每个请求的触发结果)
python .../extract_trace_signals.py --skill document-summarizer
# Step 5: 对结果打分,输出评估报告 v1-baseline.json
python .../judge_real_results.py --output-report v1-baseline.json
各脚本与五维度的映射:触发质量(extract_trace_signals + judge)、路由质量(run_real_benchmark)、上下文效率(candidate_check)、确定性(score_benchmark)、验证强度(aggregate_results)。
对 v1 评估的典型结果:
should-trigger: "总结这份 PDF" → triggered (正确)
should-trigger: "压缩汇报摘要" → not triggered (漏触发)
should-not-trigger: "翻译这篇文章" → triggered (误触发)
should-not-trigger: "分析这份报告的风险" → not triggered (正确)
edge: "帮我精简这段长文字" → triggered (正确)
人工 + 工具评估后的 v1 画像:触发质量 2.5/5(最差,P0)、路由 4/5、上下文效率 5/5、确定性 4/5、验证强度 3.5/5。
7.4 深度诊断与优先级
| 问题 | 典型表现 | 根因 | 优先级 |
|---|---|---|---|
| 触发准确性不足 | "翻译这篇 PDF"误触发总结;"提炼报告重点"漏触发 | frontmatter 描述过宽,缺乏正反示例约束 | P0 |
| 输出质量不稳定 | 内容空泛/漏关键数据/压缩不足 | 总结策略单一,缺输出质量检查 | P1 |
| 大文档处理慢 | 10MB 文档约 120 秒 | 串行处理、无缓存 | P2 |
7.5 最小进化闭环(v1 → v2)
① 读取 v1 证据(benchmark 失败样本)
│
▼
② 按 skill-creator-pro 更新
优先改 description / triggers / non_triggers
│
▼
③ 再次 review(确保仍符合规范)
│
▼
④ 重跑 benchmark(复用同一批测试集保证可比)
│
▼
⑤ 对比 v1 / v2 结果(数据证明改动是否有效)
核心代码逻辑(关键片段,注释补充):
# ① 从 v1 的 benchmark 报告中提取失败样本,作为 v2 修改的直接依据
baseline_failures = []
for run in baseline_data["runs"]:
expected = bool(run.get("expected_trigger", True)) # 测试集标注:本应触发吗?
actual = bool(run.get("with_skill", {}).get("trace_signals", {}).get("skill_triggered", False))
if expected != actual: # 期望与实际不符 = 失败样本
baseline_failures.append({...})
# 复用同一批 prompts 写入文件,保证 v1/v2 的 benchmark 结果可比
prompt_payload.append({"prompt_id": ..., "should_trigger": expected, ...})
# ② 让 Agent 基于证据定向修改(只改触发相关字段,禁止无关扩张)
prompt_evolution_apply = f"""
请更新 ./{skill_target_rel},把它从 v1 演化到 v2。
重点根据下面这些失败样本优化触发逻辑,优先修改 description、triggers、non_triggers 和示例表达;
如有必要再补 workflow、constraints、validation,但不要无关扩张。
失败样本如下:
{json.dumps(baseline_failures, ensure_ascii=False, indent=2)}
"""
注意 prompt 里的约束设计:限定"只能修改目标目录"、"不要无关扩张"、"出错要明确报告不要假装成功"——这些都是防止 Agent 进化时"跑偏"的护栏。
八、总结
8.1 一张图回顾 Skill 全生命周期
需求分析(四个关键问题)
→ 范式选型(Operator / Scout / Partner / Navigator)
→ 三层规划(SKILL.md / scripts / references / assets)
→ 创建 v1(Agent 驱动 + 脚本生成骨架)
→ 五维度评估(触发 / 路由 / 效率 / 确定性 / 验证)
→ 诊断与排序(P0 → P1 → P2)
→ 定向迭代 v2(基于失败样本修改)
→ 重跑基准对比(数据证明改进有效)
└── 评估 ← 迭代持续循环,直到各维度达标
8.2 三条核心认知(全文最值得记住的话)
- 创建完成 ≠ 好用,创建只完成了 20%。真正耗时且真正创造价值的部分在评估与迭代中。一个刚写完的 Skill 只解决了表面问题,触发准确性、输出质量、执行效率等深层问题必须靠评估暴露、靠迭代解决。
- 宁缺毋滥,Skills 不是越多越好。Skill 太多会带来触发冲突增加、维护成本上升、用户信任感下降。5 个精调的 Skill 通常优于 20 个没打磨过的 Skill。
- SKILL.md 是指挥官,不是士兵。它负责指挥流程(何时触发、调用哪个脚本、如何验证),代码、模板、参考资料各归各层,Skill 才真正可维护。
8.3 快速对照表(写 Skill 时随时翻)
| 场景/问题 | 答案 |
|---|---|
| Skill 的本质 | 可执行的流程规范(作战指令),不是知识百科 |
| Agent 调用 Skills 的机制 | 扫描 frontmatter → XML 快照注入 System Prompt → 语义匹配 → read_file 读全文 → 按步骤执行 |
| description 怎么写 | 做什么 + 触发场景 + 非触发场景,附 triggers / non_triggers 示例 |
| SKILL.md 内容公式 | 执行步骤 + 关键参数 + 异常处理 + 文档引用 |
| 长度红线 | 核心 100-200 行,复杂 200-500 行,超 1000 行必出问题 |
| 三条底线规则 | SRP(边界)> SoC(结构)> 信息精炼(内容) |
| 核心范式怎么选 | 确定执行 Operator / 探索 Scout / 协作 Partner / 路由 Navigator,按决策表从上往下 |
| 什么时候进阶范式 | 只有核心范式确实无法满足时(Philosopher/Architect/Orchestrator) |
| 怎么让 Skill 成熟 | 遥测采集 → 定期复盘 → 人工升级,评估驱动迭代闭环 |