playbook/AGENT_PRIMER.md

Agent 科普：Skill、Prompt 与 Loop

读懂 TSL Playbook 前的 5 分钟预备知识

很多人已经会用 AI 对话：输入一个问题，等待模型回答。但 Agent（智能代理）不只是“更会聊天的模型”。它能够读取资料、调用工具、观察结果，并根据任务进度继续行动。

要理解这种工作方式，先认识三个概念：

• Skill：Agent 处理某类任务时会打开的“说明书”。
• Prompt：某一次模型调用收到的任务、规则和上下文。
• Loop：让 Agent 根据真实反馈持续行动的控制机制。

---

第一部分：Skill —— 给 Agent 一套专业工作方法

什么是 Skill？

先看一个生活中的例子。

你让一个会做饭的人做红烧肉。如果只告诉他菜名，他可能会凭经验去做；如果再给他一张可靠的菜谱，上面写着要准备什么、先做什么、火候多大以及出问题时怎么办，他就更容易稳定地做好这道菜。

对 Agent 来说，Skill 就像这张菜谱。 它不是任务的最终答案，而是一份“怎样完成这类任务”的说明。它通常会告诉 Agent：

• 哪类任务要打开它；
• 第一步做什么，接下来做什么；
• 不确定时去哪里查；
• 可以使用哪些工具；
• 什么情况下应该停下来询问用户。

Skill 不会让模型突然变得更聪明，也不会改变模型本身。它只是让 Agent 在处理某类任务时有步骤可循、知道去哪里查，尽量少靠猜。

Agent 什么时候会使用 Skill？

Agent 不会把所有 Skill 一直“摊在桌面上”。它通常先看一份简短目录，知道有哪些 Skill、每个 Skill 适合做什么。收到任务后，如果出现下面的情况，才会打开对应的 Skill：

• 用户明确点名某个 Skill；
• Agent 发现当前任务正好符合某个 Skill 的用途；
• 系统或项目规则要求这类任务必须使用指定 Skill。

这个动作发生在 Agent 真正回答或开始操作之前。同一个任务做到不同阶段时，也可能需要打开不同的 Skill。

打开 Skill 后，Agent 会照着里面的步骤工作，需要时再去查询资料或使用工具。

Skill 如何工作？

flowchart LR
    A([用户提出任务]) --> B[看看有哪些 Skill]
    B --> C{找到合适的<br/>Skill 了吗}
    C -->|用户点名 / 任务匹配 / 规则要求| D[打开对应 Skill]
    D --> E[按照步骤工作]
    E --> F[需要时查资料<br/>或使用工具]
    F --> G([完成任务])
    C -->|没有| H[用通用能力处理]
    H --> G

    classDef start fill:#e8f3f8,stroke:#2b7489,color:#173b48,stroke-width:2px;
    classDef decision fill:#fff4dc,stroke:#c88719,color:#5b3a00,stroke-width:2px;
    classDef skill fill:#f0eafd,stroke:#8250df,color:#3f2675,stroke-width:2px;
    classDef action fill:#eaf2fd,stroke:#3178c6,color:#173f73,stroke-width:2px;
    classDef done fill:#e8f6ec,stroke:#2ea043,color:#175c2d,stroke-width:2px;

    class A start;
    class C decision;
    class B,D skill;
    class E,F,H action;
    class G done;

以 TSL Playbook 中的 tsl-syntax-reference 为例：当用户要求编写或解释 TSL 代码时，Agent 会先打开这个 Skill，按照里面的说明查询 TSL 语法资料，确认正确写法后再生成代码，而不是因为“TSL 看起来像 Pascal”就凭经验猜。

这个例子体现了 Skill 的核心价值：

Skill 不替 Agent 完成任务，而是告诉 Agent 如何更可靠地完成某一类任务。

简单来说，Skill 负责告诉 Agent“这类事情应该怎么做”。任务发生变化时，Agent 可以在后续步骤中再使用新的 Skill。

---

第二部分：Prompt + Loop —— 从一次回答到持续完成任务

Prompt 是什么？

Prompt 是一次模型调用所接收的输入，可能包括：

• 用户当前提出的任务；
• 系统规定的角色与行为边界；
• 已有的对话和执行历史；
• 工具返回的结果；
• 当前任务状态和剩余目标。

因此，Prompt 不是模型调用本身，而是这次调用所使用的任务说明和上下文。

一次性的 Prompt 通常是：用户输入任务，模型给出回答，然后结束。如果任务需要读取文件、修改代码、运行测试并根据报错继续修复，仅靠一次回答往往不够，这时就需要 Loop。

一次性 Prompt 与 Loop 有什么不同？

flowchart TD
    subgraph ONE[一次性 Prompt]
        direction LR
        P1[输入任务] --> P2[模型回答] --> P3([结束])
    end

    subgraph LOOP[Loop]
        direction LR
        L1[设定目标] --> L2[观察当前状态]
        L2 --> L3[决定下一步]
        L3 --> L4[行动或调用工具]
        L4 --> L5[更新状态]
        L5 --> L6{目标完成了吗}
        L6 -->|完成| L7([输出结果])
        L6 -->|没有| L2
    end

    classDef prompt fill:#eaf2fd,stroke:#3178c6,color:#173f73,stroke-width:2px;
    classDef loop fill:#f0eafd,stroke:#8250df,color:#3f2675,stroke-width:2px;
    classDef decision fill:#fff4dc,stroke:#c88719,color:#5b3a00,stroke-width:2px;
    classDef done fill:#e8f6ec,stroke:#2ea043,color:#175c2d,stroke-width:2px;

    class P1,P2,L1 prompt;
    class L2,L3,L4,L5 loop;
    class L6 decision;
    class P3,L7 done;

Loop 可以由用户手动推进，例如模型回答后，用户再说一句“继续”。在真正的 Agent 系统中，Loop 通常由外部程序管理：程序反复调用模型、执行工具并更新状态，直到任务完成、需要用户确认、发生错误或达到执行上限。

Loop 如何工作？

这里最容易误解的一点是：Prompt 和 Loop 不是二选一，Prompt 就在 Loop 里面。

Agent 每执行一轮，都会把新的观察结果和任务状态加入上下文，再组装下一轮 Prompt：

Prompt 1 → 模型决策 → 执行工具 → 获得结果
                                      ↓
Prompt 2（加入新结果）← 更新任务状态

模型负责判断“下一步做什么”，外部程序负责真正运行 Loop、执行工具、保存状态和检查停止条件。模型本身不会在没有再次调用的情况下无限运行。

---

最后记住三句话

概念	一句话理解
Skill	为 Agent 提供某个领域可重复使用的专业工作方法。
Prompt	告诉模型这一轮知道什么、遵守什么、要做什么。
Loop	让 Agent 根据执行反馈不断决定下一步，直到停止。

三者组合起来，Agent 才能从“回答一个问题”进化为“持续完成一个任务”：

Skill 提供专业方法，Prompt 描述当前一步，Loop 推动任务向前。