Agent Skills 基础入门

为什么需要 Agent Skills

很多人使用 AI 助手的核心困境是：不是不知道怎么问，而是 AI 不知道怎么做。

任务	用户以为 AI 会做	实际还需要
补单元测试	写几个 test()	理解逻辑 → 设计边界用例 → 验证覆盖率
整理 Markdown	总结文字	统一格式 → 提取信息 → 生成目录 → 检查链接
找合适的 Skill	搜索文件名	评估适用场景 → 判断能力边界

共同特点：很多任务不是一句答案能结束的，而是需要稳定的、可复用的能力链。

真正缺的不是更多话术，而是：

可发现

AI 能知道”我有这个能力”

可执行

AI 能按结构化流程完成任务

可复用

同样的能力可跨场景持续使用

普通聊天的局限

普通聊天式 AI 会回答，用户容易误以为它已具备完整能力。但它不知道何时该调用外部能力，缺少模板、脚本、参考资料时稳定性明显下降。

因此，Skill 的本质不是”多一个工具”，而是把能力变成可发现、可执行、可复用的模块。

核心痛点

不是 AI 不会回答，而是真实任务需要稳定的能力链，普通聊天无法保证执行质量

根本原因

缺少可发现的能力、可执行的流程、可复用的结构三大要素

Skill 解决什么

把能力变成可发现、可执行、可复用的模块，让 AI 从”会说”走向”会做”

与长 Prompt 的区别

Skill 不是更长的提示词，而是有路由、有流程、有资源支撑的独立能力单元

---

什么是 Agent Skill

一句话定义

Agent Skill 是一个可被 Agent 在运行时发现、理解、调用和组合的能力模块。

手机类比：Agent 像手机（理解意图、调度能力），Skill 像 App（提供可调用功能 + 使用说明书），生态目录像应用商店（发现、安装、管理）。

1. 先被发现 — 路由不到，再好的能力也发挥不出来
2. 再被调用 — Skill 不是摆设，它要支撑任务推进
3. 还能被复用 — 这是它和一次性 Prompt 的关键差别

---

Skill 不是长 Prompt

常见误区

Skill 不是长 Prompt，也不是普通工具或插件换个名字。

类型	典型特征	局限
长 Prompt	一次性塞入大量指令，高度依赖当前上下文	跨场景复用弱，维护困难
工具 / 插件	强调执行动作	不一定天然可发现，常缺少教学式描述层
Skill	描述能力边界，告诉 Agent 什么时候该用	需要设计清楚触发、流程与资源层

Skill 多出来的关键价值：

可发现

Agent 能知道这个能力适合什么任务

可复用

同一份能力可以跨场景持续使用

可组合

多个 Skill 可以共同完成复杂任务

可治理

能力边界、触发条件和执行流程可被维护和优化

使用 Prompt vs 使用 Skill 的对比

Prompt 方式

用户："帮我给这个函数补充单元测试，要覆盖边界情况，
要用 Jest 框架，要检查覆盖率，要..."

问题：每次都要重新描述需求，容易遗漏细节；AI 可能理解偏差，执行不一致；下次遇到类似任务又要重新写一遍。

Skill 方式

用户："帮我补充单元测试"
Agent：识别到 test-driven-development Skill → 自动执行标准化流程

优势：一句话触发，无需重复描述；执行流程一致，结果可预期；下次遇到类似任务自动复用。

---

Agent 调用 Skill 的机制

所有机制设计都围绕可发现、可执行、可复用展开。Agent 调用 Skill 不是”想起了就用”，而是走一条完整的判断链。

调用五步

1. 识别任务 — 理解用户请求属于什么类型（测试、文档处理、Skill 搜索等）
2. 判断能力边界 — 任务是否需要结构化流程、多步骤执行、明确验证标准？如果只是总结/解释/改写，无需 Skill
3. 匹配 Skill — 根据 Skill 的 description 和触发条件，从候选列表中找到最合适的那一个
4. 执行 Skill — 加载 Skill 文件 → 注入 Agent 上下文 → 按 workflow 编排执行
5. 整合输出 — 将 Skill 产出整理成用户可直接使用的结果

记忆口诀

识别 → 判断 → 匹配 → 执行 → 整合。前两步决定”要不要用”，第三步决定”用哪个”，后两步负责”怎么用好”。

路由判断：什么时候该调用 Skill

路由的核心问题：Agent 如何从多个可用 Skill 中选出最合适的？

Agent 内部走的是一套简化决策树：

判断问题	结论
普通聊天就能完成？（总结、解释、改写）	不需要 Skill
需要结构化流程或外部能力？（批处理、环境依赖、多步验证）	需要 Skill
多个 Skill 都能匹配？	选语义最贴近当前语境的那个

当多个 Skill 都能匹配时，Agent 依据三个维度排序：

维度	判断内容
语义匹配度	description 与用户请求的语义相似度 + 关键词命中
能力边界覆盖	Skill 的能力范围是否完整覆盖当前任务需求
优先级规则	平台推荐、用户偏好或显式优先级标记

示例：

用户请求	判断结果
把函数写成中文解释	普通语言任务，无需 Skill
找出当前环境的 PDF 处理能力	触发发现类 Skill
帮我给这个函数补充单元测试	触发 test-driven-development Skill
把一批 Markdown 整理成课程大纲再转 HTML	需要多个 Skill 组合

Token 经济学：渐进式披露

Skill 的关键设计是按需加载：空闲时系统仅持有数百 Token 的 Skill 元数据（name + description），匹配后才注入完整 Skill 内容。

场景	全量注入	按需加载	节省
补充测试	~5000 tokens	~500 tokens	90%
代码审查	~4500 tokens	~450 tokens	90%
文档整理	~4000 tokens	~400 tokens	90%

一句话总结

动态路由让 Agent 只为当前任务需要的能力付费，而不是为所有可能的能力持续买单。

---

Skill 的内部三层结构

从使用者视角切换到创建者视角，Skill 可以拆成三层：

层级	组成	核心职责
路由层	frontmatter（YAML 元信息）	决定”能不能被找到、什么时候触发”
控制层	SKILL.md 正文（body）	决定”进来以后怎么做”
支撑层	references/、scripts/、assets/ 等	提供知识、脚本、模板，把能力做实

Tip

SKILL.md 是唯一必需文件。目录结构是扁平的，可选目录按需添加。

路由层：frontmatter

frontmatter 不是备注，是 Agent 路由系统的入口。它决定 Skill 能否被发现和调用。

---
name: test-driven-development
description: 在实现任何功能或修复 bug 前，先编写测试用例
---

字段	作用	设计要点
name	让能力可被识别和引用	kebab-case，简洁唯一
description	决定触发语义是否清晰	动词开头，说明适用场景和边界（做什么、什么时候用、什么时候不用）

控制层：SKILL.md body

body 决定 Agent 进入 Skill 后如何执行（怎么做）。不是普通文档，而是可执行的流程规范。

一个完整的 body 通常包含四个核心模块：

模块	回答的问题
Goal	这个 Skill 解决什么问题？（与 frontmatter description 一致）
Workflow	执行步骤是什么？遇到分支怎么走？
Constraints	什么不能做？什么必须遵守？验收标准是什么？
Examples	典型用法长什么样？

最佳实践

Workflow 要写具体可执行的步骤，不要写模糊建议。分支逻辑直接写在步骤里。

## Goal
引导使用 TDD 方法论实现功能

## Workflow
1. 阅读功能描述，识别验收标准
2. 设计测试用例（正常/边界/异常）
3. 编写测试代码，确认测试失败
4. 编写最小实现，让测试通过
5. 重构代码，确保测试仍然通过

## Constraints
- 不要在编写测试前编写实现代码
- 每个测试必须有清晰的断言
- 测试之间必须独立且可重复运行
- 验收标准：所有测试通过且覆盖率达标

## Examples
用户请求："给 calculateTotal 函数补充单元测试"
→ 识别函数签名 → 设计正常/空数组/负数三组用例 → 编写测试 → 验证通过

支撑层：可选资源目录

目录	放什么	解决什么问题
references/	深入知识、变体细节	让主 Skill 保持轻量，按需引用
scripts/	重复或脆弱的确定性动作	降低手工失误，保证执行一致
assets/	模板、结构骨架、可复用产物	提供起点，提升输出质量

Caution

没有支撑层的 Skill 在复杂任务里容易退回泛化回答。资源层越完善，Skill 越接近可复用的领域能力。

三层协同：不同场景下的配合

三层不是各自独立的文件集合，而是在不同运行场景中各有侧重：

场景	路由层重点	控制层重点	支撑层重点
能力发现	触发语义能否被 Agent 读懂	—	—
执行任务	判断”是不是 Skill 问题”	把任务拆成步骤和验证	脚本执行 + 模板输出
持续维护	边界是否仍然清晰	流程和分支是否需要更新	资源是否需要补强

---

Skill 目录结构示例

目录结构不是固定模板，而是按任务复杂度组织。SKILL.md 是唯一必需文件，其余按需添加。

单文件型

• Directorytest-driven-development/

  • SKILL.md

所有内容（Goal、Workflow、Constraints）都在 SKILL.md 正文中。适合单一任务或标准化流程，创建成本低。

资源依赖型

• Directorylesson-interaction-architect/

  • SKILL.md
  • Directoryreferences/

    • interaction-lenses.md
    • pattern-catalog.md
    • pattern-stack-recipes.md
    • output-contracts.md

需要外部参考资料支撑判断和输出。适合领域知识密集的专业任务。

脚本驱动型

• Directorypdf/

  • SKILL.md
  • Directoryscripts/

    • merge_pdfs.py
    • extract_text.py
    • add_watermark.py
  • forms.md
  • reference.md

有确定性执行动作需要脚本化。注意：参考文件不必放在 references/ 目录里，组织方式可以灵活。

完整复杂型

• Directoryskill-creator/

  • SKILL.md
  • Directoryagents/

    • …
  • Directoryreferences/

    • …
  • Directoryscripts/

    • …
  • Directoryassets/

    • …
  • Directoryeval-viewer/

    • …

包含子 Agent、评估系统和模板资产。适合创建和管理其他 Skill 的元级能力。

---

Skills vs Function Calling vs MCP

维度	Function Calling	MCP	Agent Skills
核心定义	代码级接口（JSON Schema）	通讯协议标准	业务逻辑封装（Markdown）
擅长	单点执行、精确动作	稳定接入外部系统	组织工作流、封装判断
局限性	不够灵活，需要编程	实现复杂，学习成本高	精确度相对较低
开发方式	JSON Schema + Python/Node.js	TypeScript/Python SDK	Markdown / 自然语言
适用人群	后端工程师	全栈工程师	技术与非技术人员均可

三者不是互斥关系

Skill 更像策略层/工作流层，MCP 更像能力源和接入层，Function Calling 更像执行层。成熟系统往往组合使用：高层工作流用 Skill，底层精确操作用 Function Calling，跨平台能力用 MCP。

快速原型 / 非技术团队

优先 Agent Skills — Markdown 编写，修改即生效，低门槛

精确控制

优先 Function Calling — 确定性执行，结构化数据，可监控

生产级跨平台集成

优先 MCP — 标准化协议，稳定可复用

---

什么时候 Skill 会失效

Skill 失效 = 某一层设计不清楚。按层排查：

失效层	症状	修法
路由层	Agent 触发不到或误触发	明确适用场景、非适用场景、典型对象
控制层	进入后仍在自由发挥	Goal + Workflow + Constraints 都写清楚
支撑层	复杂任务退回泛化回答	补齐 references / scripts / assets
运行时	设计没错但执行失败	检查平台依赖和上下文是否满足

---

小结

一句话记住 Skill

Skill 是可被 Agent 发现、判断、调用、组合，并能持续维护的能力模块。

你需要记住的	核心要点
解决什么问题	能力边界——让 AI 从”会说”走向”会做”
调用五步	识别 → 判断 → 匹配 → 执行 → 整合
内部三层	路由层（能不能找到）+ 控制层（怎么执行）+ 支撑层（靠什么做实）
失效排查	按层查：触发不到？流程太浅？资源缺失？环境不支持？