Agent Skill 入门：把多步推理与工具调用固化为可复用流程

Agent Skill 入门：把多步推理与工具调用固化为可复用流程

摘要（先看结论）

Agent Skill 本质上是一套“可执行的工作流程封装”：把复杂任务的触发条件、执行步骤、输入输出格式、禁止事项，以及必要的脚本/资料，打包成一个可复用的技能包。它解决的不是“模型懂不懂”，而是“在你的团队里应该怎么做、怎么做到稳定可复现”。

如果你已经写过一堆 Prompt 但发现它越来越长、越来越不稳、越来越难复用，那么 Skill 往往是下一步。

Skill 是什么

Skill 通常以一个文件夹形式存在，包含三类内容：

<skill-name>/
├── SKILL.md # 必选：何时触发、怎么做、怎么输出
├── reference/ # 可选：长文规则/制度/模板，按需读取
└── scripts/ # 可选：确定性动作脚本，按需执行

把它理解成：给 Agent 的“工作说明书 + 参考资料库 + 工具箱”。

同样也可以用一个四格（ASCII 版）把“Skill 包里有什么、怎么跑”的直觉讲清楚：

┌──────────────────────────────┬──────────────────────────────┐
│ ① 这个技能包里都有啥？ │ ② 看 SKILL.md：先提取再调用 │
│ │ │
│ .-""""-. │ ┌──────────────────────┐ │
│ / o o \\\\ │ │ SKILL.md │ │
│ | ∩ | "这个技能包里" │ │ 1) 提取数据 │ │
│ | \\\\___/ | "都有啥？" │ │ 2) 调用脚本 │ │
│ \\\\_______/ │ │ 输出格式/边界/禁忌事项 │ │
│ | | │ └──────────────────────┘ │
│ [riding-skill] │ 提取数据 -> 调用脚本 │
├──────────────────────────────┼──────────────────────────────┤
│ ③ 运行脚本：马上得到结果 │ ④ 一看就会：封装=流程复用 │
│ │ │
│ $ python scripts/do_it.py │ ┌──────────────┐ │
│ … │ 完成 │ 可复用输出 │ ✓ │
│ result: 42 │ └──────────────┘ │
│ │ │
│ 关键点：确定性动作交给脚本 │ 关键点：规则+资料+脚本=技能 │
└──────────────────────────────┴──────────────────────────────┘

为什么需要 Skill

• 复用：把“团队 SOP”固化成可重复执行的流程，不用每次从头解释。
• 稳定：把输出格式、边界条件、禁止事项写死，减少随机漂移。
• 协作：新人/不同同学使用同一套能力封装，结果更一致。
• 降成本：把长上下文拆到 reference，按需读取；把确定性操作交给脚本。

用“人学会骑车”类比 Skill（更工程化的理解）

人从不会到会骑车，靠的不是每次都重新推理，而是把一套动作模式固化为“可自动执行”的能力。Agent Skill 做的也是类似的事：把多步决策与工具调用固化成流程，下一次遇到相似任务直接套用。

对应关系可以这样记：

你也可以把这个过程想象成下面这个四格（ASCII 版）：

┌──────────────────────────────┬──────────────────────────────┐
│ ① 指令（教练/规则） │ ② 失败（摔倒/纠错） │
│ │ │
│ 旁白：左脚踩下去！右脚跟上！ │ 旁白：啊！又摔倒了！再试一次！ │
│ 保持平衡！ │ │
│ │ │
│ o │ o │
│ /|\\\\ __o │ /|\\\\ __x │
│ / \\\\ /_\\\\_\\\\ │ / \\\\ /_\\\\_\\\\ │
│ O O │ O O │
├──────────────────────────────┼──────────────────────────────┤
│ ③ 学会（可重复） │ ④ 固化为技能（可复用流程） │
│ │ │
│ 旁白：耶！我会骑车啦！ │ 旁白：AI 也可以学会技能， │
│ │ 就像骑自行车一样！ │
│ o │ ┌──────────────┐ │
│ /|\\\\ __o │ │ SKILL.md │ │
│ / \\\\ /_\\\\_\\\\ │ │ reference/* │ │
│ O O │ │ scripts/* │ │
│ │ └──────────────┘ │
└──────────────────────────────┴──────────────────────────────┘

Skill 怎么跑起来（最小闭环）

你可以用下面这张“加载与执行”流程图理解 Skill 的运行方式：

用户请求
|
v
模型看到：所有 Skills 的 name/description（像目录）
|
v
命中某个 Skill
|
v
加载 SKILL.md 正文（规则/步骤/输出格式）
|
+–> 需要更长规则：按需读取 reference/*
|
+–> 需要确定性动作：按需执行 scripts/*
|
v
生成结果（遵守固定格式与质量规则）

一个最小例子：两数相加 Skill

这个例子只演示三件事：

• 何时触发（trigger）
• 怎么执行（steps）
• 用脚本做确定性计算（scripts）

目录结构

two-numbers-sum/
├── SKILL.md
└── scripts/
└── add_numbers.py

SKILL.md（示例）

—
name: two-numbers-sum
description: 两数之和计算工具。当用户需要计算两个数字的和时使用，支持整数/小数/负数。输出格式为“结果是{结果}”。
—

# 触发条件
– 用户明确表达“求和/相加/加法/计算 A + B”

# 输入提取
– 从用户输入中提取两个数字（允许小数与负数）
– 若只识别到一个数字或存在歧义：先追问，不要猜

# 执行步骤
1. 调用脚本 `scripts/add_numbers.py <number1> <number2>`
2. 读取脚本输出的数值结果

# 输出格式（必须遵守）
结果是{result}

scripts/add_numbers.py（示例）

import argparse

def add_two_numbers(num1: float, num2: float) –> float:
return num1 + num2

def main() –> None:
parser = argparse.ArgumentParser(description="Compute sum of two numbers")
parser.add_argument("num1", type=float)
parser.add_argument("num2", type=float)
args = parser.parse_args()

result = add_two_numbers(args.num1, args.num2)
print(result)

if __name__ == "__main__":
main()

本地运行（示例）

python3 scripts/add_numbers.py 5 3

写 Skill 的工程化约束（建议直接当检查清单）

• 明确触发条件：什么情况下用，什么情况下不用。
• 输入可校验：缺信息就追问，禁止臆测。
• 输出可验收：强制结构化输出，保证可读与可对比。
• 步骤可失败：每一步写清失败时怎么处理（重试/降级/停止）。
• 规则可拆分：SKILL.md 控制短，长文放 reference 按需加载。
• 动作可确定：确定性动作交给 scripts，不要让模型“算/猜”。
• 权限与脱敏：涉及账号/隐私/凭证，必须显式约束与红线。