第十二章: 建具备 Skills 调用能力的 Agent

0 阅读32分钟

构建具备 Skills 调用能力的 Agent —— 学习笔记

环境基准:LangChain 1.1 / Claude Code 2.1,示例模型为 DeepSeek(兼容 OpenAI 格式均可)。 本文主线回答三个问题:

  1. 需求说明:为什么 Agent 需要"Skills 调用能力"?
  2. 如何实现一个 Skill:一个 Skill 长什么样?怎么写才不踩坑?
  3. 如何让 Agent 调用 Skills:Agent 从"看到技能"到"执行技能"的完整机制是什么?

目录

  1. 需求说明:为什么要给 Agent 配 Skills
  2. 核心原理:Agent 是如何调用 Skills 的
  3. 如何实现一个 Skill
  4. 反面冲击:三个"坏 Skill"案例
  5. 设计范式:拿到需求后怎么选型
  6. 实战:从零创建 document-summarizer
  7. 评估与进化:创建完成只完成 20%
  8. 总结

一、需求说明:为什么要给 Agent 配 Skills

1.1 问题背景

Agent(智能体)本身只会"对话 + 调工具"。当任务变复杂(如"把这份 PDF 总结成汇报摘要"、"帮我部署这个服务")时,如果每次都靠模型临场发挥,会出现三类问题:

问题表现
每次都要重新"教"相同任务每次都重复一遍操作步骤,浪费 token 且结果不稳定
知识散落、无法复用好的流程沉淀在聊天记录里,换一个会话就丢了
Skills 一多就"爆炸"当 Agent 拥有 10 个以上技能时,若缺乏设计规范,会出现触发混乱、维护困难、无法复用的"技能爆炸"状态

1.2 Skill 是什么(一个比喻先讲清楚)

Skill 的本质:一份"可执行的流程规范",而不是"知识百科"。

  • 好的 Skill 像"作战指令":清晰、简洁、可执行。
  • 坏的 Skill 像"参考手册":详尽、冗长、需要理解。

一个 Skill 的价值判断标准(什么时候值得做成 Skill):

  • 任务会重复出现;
  • 操作步骤相对稳定;
  • 手工执行成本高、易出错;
  • 输出质量可以被验证。

1.3 需求归纳

我们要构建的 Agent 需要:

  1. 自动发现技能:不需要硬编码,把 Skill 文件放进目录就能被识别;
  2. 按需触发:根据用户请求,判断该不该用某个 Skill(该触发时触发、不该触发时不触发);
  3. 读取并执行:触发后能读取 Skill 的定义文件,按其中步骤调用工具完成任务;
  4. 可维护、可进化: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 内容 = 执行步骤 + 关键参数 + 异常处理 + 文档引用

从冗长文档提炼要点用"三步过滤法":

  1. 识别执行路径:只留"完成任务需要执行哪些步骤",删掉背景介绍、原理解释;
  2. 提取关键参数:只留必需参数和影响结果的参数,删掉可选参数和默认值;
  3. 标注异常情况:只留"哪些情况会失败、如何处理",删掉边缘情况和理论分析。

嵌入还是引用的选择标准:

信息类型执行必需?处理方式
执行步骤 / 关键参数 / 异常处理是嵌入 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 并清洗数据",它可能:

  1. 直接执行 SKILL.md 里的示例代码(但示例里硬编码的是 data.csv,文件不存在,执行失败);
  2. 把代码示例当成执行步骤的一部分,逻辑错乱;
  3. 在代码示例和执行指令之间反复横跳,不知道该做什么。

根本问题: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进阶

三条选型原则:

  1. 优先核心范式,95% 的场景够用;
  2. 范式可混合但要有主导范式(如 Operator 为主,个别步骤引入 Partner 的确认机制);
  3. 避免过度设计:过早升级进阶范式会让任务更重、更慢、更难控制。

六、实战:从零创建 document-summarizer

本案例完整走一遍"需求分析 → 范式选择 → 资源规划 → 实现 → 验证"的创建流程,并演示 Agent 驱动的创建工作流。

6.1 第一步:需求分析与边界定义

需求:用户上传一个长文档(PDF/Word/Markdown),系统自动生成结构化摘要。

创建前必须回答四个关键问题:

关键问题回答
它解决什么问题?从长文档中稳定提取结构化摘要
什么情况下触发?用户明确要求总结、提炼、压缩文档内容
什么情况下不触发?翻译、改写、问答、原文读取、复杂分析
怎样算成功?输出结构清晰、覆盖核心内容、明显压缩且可验证

触发边界比实现细节更重要。"帮我把文档翻译成英文"和"帮我总结文档"都和文档有关,但目标完全不同。如果不明确写 non_triggers,就会回到"大而全 Skill"的陷阱。

成功标准(v1):

  1. 能识别常见文档类型并成功读取内容;
  2. 能输出结构化摘要(不是散乱自由文本);
  3. 摘要覆盖原文主要章节、核心观点和关键结论;
  4. 输出长度明显压缩,但不丢失关键事实。

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 三条核心认知(全文最值得记住的话)

  1. 创建完成 ≠ 好用,创建只完成了 20%。真正耗时且真正创造价值的部分在评估与迭代中。一个刚写完的 Skill 只解决了表面问题,触发准确性、输出质量、执行效率等深层问题必须靠评估暴露、靠迭代解决。
  2. 宁缺毋滥,Skills 不是越多越好。Skill 太多会带来触发冲突增加、维护成本上升、用户信任感下降。5 个精调的 Skill 通常优于 20 个没打磨过的 Skill。
  3. 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 成熟遥测采集 → 定期复盘 → 人工升级,评估驱动迭代闭环