Agent Skills 基础入门

为什么需要 Agent Skills

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

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

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

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

可发现

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

可执行

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

可复用

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

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

核心痛点

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

根本原因

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

Skill 解决什么

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

与长 Prompt 的区别

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

什么是 Agent Skill

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

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

Skill 不是长 Prompt

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

Skill 多出来的关键价值：

可发现

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

可复用

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

可组合

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

可治理

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

使用 Prompt vs 使用 Skill 的对比

Prompt 方式
Skill 方式

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

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

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

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

Agent 调用 Skill 的机制

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

调用五步

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

Skill 的内部三层结构

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

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

路由层：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	典型用法长什么样？

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

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

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

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

支撑层：可选资源目录

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

契约式引用

引用辅助文件时，不要只写路径——要写契约，告诉 Claude 何时加载、加载后得到什么：

# ❌ 弱引用（Claude 不知道何时加载）
See `reference/revenue.md` for more details.

# ✅ 契约式引用
## 收入分析
当用户询问收入增长、ARPU 或收入构成时：
→ 加载 `reference/revenue.md` 获取计算公式和行业基准

三要素：触发条件（什么情况下）+ 文件路径（去哪里找）+ 内容预期（加载后得到什么）。

文件命名原则

Claude 根据文件名判断是否需要加载，命名要有描述性：

# 好的命名              # 差的命名
reference/revenue.md   reference/ref1.md
templates/quarterly_report.md   docs/misc.md

脚本适用场景

脚本适合封装确定性逻辑，让 Claude 执行而不需要“理解”，节省 token：

# 适合脚本              # 不适合脚本
财务比率计算（公式固定）  开放性分析（需要判断）
数据格式转换（规则明确）  创意性任务（需要灵活性）
文件批量处理（重复性高）  交互式决策（需要反馈）

脚本还能生成可视化 HTML，Claude 只需知道“运行什么命令”（10 tokens），而非“如何生成 HTML”（2000+ tokens）——这是渐进式披露的极致形态。

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

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

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

Skill 目录结构示例

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

Directorytest-driven-development/
- SKILL.md

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

Directorypdf/
- SKILL.md
- Directoryscripts/
  - merge_pdfs.py
  - extract_text.py
  - add_watermark.py
- forms.md
- reference.md

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

Skill 设计的四种模式

模式概览

模式	解决的问题	核心手段
模板驱动	输出不稳定	`templates/` 统一格式
脚本增强	结果不稳定	`scripts/` 确定性执行
知识分层	上下文膨胀	渐进加载 + 契约引用
工具隔离	越权风险	`allowed-tools` 最小权限

生产级 Skill 通常组合多种模式，按需叠加。

模板驱动

适用报告生成、文档输出等需要格式一致的场景。模板负责呈现，不负责决策，逻辑应放在 SKILL.md。

report-generating/
├── SKILL.md              # 路由 + 流程
└── templates/
    ├── weekly_report.md   # 周报模板
    ├── incident.md        # 事故报告模板
    └── review.md          # 评审报告模板

## Output Rules
- ALWAYS use the template from `templates/` that matches the request type
- Fill ALL placeholders — do not leave {placeholder} unfilled
- Do NOT add sections beyond what the template defines

反模式警告：

模板超过 100 行 → 职责混乱，应拆分
模板含逻辑判断 → 边界被打破，逻辑移入 SKILL.md

脚本增强

适用公式计算、正则匹配、指标统计等确定性场景。把概率型推理替换为确定性执行。

data-analyzing/
├── SKILL.md              # 路由 + 流程
└── scripts/
    ├── parse_csv.py       # 数据解析
    ├── calculate.py       # 指标计算
    └── visualize.py       # 生成图表 HTML

脚本规则：

优先使用标准库，有外部依赖须明确声明
不包含交互式输入，一次性可执行
只放确定性、可验证的逻辑；判断和策略决策留给 Claude

知识分层

适用规则多、领域复杂的 Skill（SKILL.md 超过 500 行时）。通过渐进加载控制认知复杂度。

security-reviewing/
├── SKILL.md              # 核心检查清单（~200 行，80% 请求够用）
├── QUICKREF.md           # 常见漏洞速查（中频）
├── reference/
│   ├── xss.md           # XSS 防护详解（按需）
│   ├── sqli.md          # SQL 注入详解（按需）
│   └── auth.md          # 认证问题详解（按需）
└── examples/
    └── bad_patterns.md   # 反模式示例（按需）

分层策略：SKILL.md 内联高频内容（80/20 法则）→ 契约式引用中频内容 → 文件名描述性命名供按需加载。

工具隔离（allowed-tools）

allowed-tools 的核心价值在于明确不能做什么，把安全约束前置为结构设计：

# 审计类：只读
allowed-tools: [Read, Grep, Glob]

# 生成类：只写不改
allowed-tools: [Read, Grep, Glob, Write]

# 分析类：只读 + 脚本
allowed-tools: [Read, Grep, Glob, Bash(python:*)]

# 执行类：受控执行
allowed-tools: [Read, Bash(npm test:*), Bash(pytest:*)]

模式组合决策树

你的 Skill 需要……
│
├─ 标准化输出格式？ → 加 templates/（模板驱动）
├─ 确定性计算/匹配？ → 加 scripts/（脚本增强）
├─ 知识量 > 500 行？ → 拆分 reference/（知识分层）
└─ 安全边界控制？ → 配置 allowed-tools（工具隔离）

Skills 能力进化的三个阶段

阶段	名称	特征	适用场景
第一级	SOP	单一 SKILL.md，流程清晰	标准化、可复现的操作
第二级	专家系统	知识库 + 模板 + 脚本 + 权限控制	复杂变体处理
第三级	组织智能	多 Skills + SubAgents + Hooks	大规模多智能体协作

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

快速原型 / 非技术团队

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

精确控制

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

生产级跨平台集成

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

Skills × Tools 协作关系

Skills（知识/经验）和 Tools（执行手段）之间有三层关系：

关系	说明	实现方式
Skills 约束 Tools	最小权限原则	`allowed-tools` 精确到操作类型
Skills 编排 Tools	脚本是预编译的 Tool 调用序列	`scripts/` 固化确定性逻辑，Claude 执行但不理解
Tools 反哺 Skills	Tool 输出在 Skill 加载前注入上下文	!`command` 语法预处理

# Tools 反哺 Skills 示例
---
name: pr-summary
---

## Context
- PR diff: !`gh pr diff`
- Changed files: !`git diff --name-only`

Shell 命令在 Skill 加载之前执行，Claude 收到的是已包含实时数据的知识——这就是动态上下文注入的底层机制。

什么时候 Skill 会失效

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

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

Skill 传参机制

Skill 支持接收用户传入的参数，使同一个 Skill 能处理不同输入。

传参方式

方式	语法	适用场景
整体传参	`$ARGUMENTS`	接收全部参数作为一个字符串
位置传参	`$1`、`$2`、`$3`	按位置拆分多个独立参数（从 1 开始）

示例：

---
name: 计算器
description: 简单四则运算。用法：/计算器 数字 运算符 数字，例如 /计算器 10 + 5
---

计算 $1 $2 $3 = ?

直接输出结果，不要输出任何其他内容。

$1 和 $3 必须是数字，$2 必须是 + / - / * / / 之一，否则给出友好提示。

调用 /计算器 30 + 20 时，$1=30、$2=+、$3=20，输出 50。

动态上下文注入

Agent 进入 Skill 时并不自动感知环境。如果 Workflow 不明确要求收集状态，Agent 会边做边探索，产生多轮无效工具调用。

解法：在 Workflow 的第一步显式要求运行脚本或读取文件，把环境状态收集前置。

## Workflow
1. 运行 `scripts/gather-context.sh`，获取当前分支、未合并 commit 数、改动文件列表。
2. 根据上一步输出判断风险等级。
3. 按风险等级执行对应操作。

对比没有注入的写法：

## Workflow
1. 判断风险等级。   ← Agent 不知道从哪里取数据，开始自由探索
2. 执行对应操作。

适用场景：凡是 Skill 依赖运行时状态（git 状态、文件是否存在、环境变量、API 返回值），都应在 Workflow 第一步明确收集，而不是依赖 Agent 自行发现。

Skill 设计方法论

设计清单

设计一个 Skill 时，按顺序回答这些问题：

做什么动作？ → 决定命名（简洁、动词化）
谁能触发？ → Agent 自动触发 or 用户手动调用
需要什么权限？ → 精确到最小必要工具集
启动时需要什么上下文？ → 预注入环境状态
执行过程有副作用吗？ → 是否需要安全检查
输出量大不大？ → 大输出考虑分段或独立上下文

设计原则

原则	正确做法	错误做法
单一职责	一个 Skill 做一件事	一个 Skill 包揽所有
清晰命名	从名字就知道做什么	模糊命名（do-stuff、cmd1）
参数语义化	提示含义（[commit message]）	无意义提示（[args]）
权限最小化	只授权必需的工具/命令	授权所有权限
显式错误处理	Workflow 中写明失败路径	只写正常流程

三条核心认知

创建完成 ≠ 好用，创建只完成了 20% — 一个写完的 Skill 只解决了表层触发问题，真正耗时的价值在后续评估与迭代
宁缺毋滥，Skills 不是越多越好 — 触发冲突增加、维护成本上升、用户信任下降。5 个精调的 Skill 优于 20 个没打磨的
SKILL.md 是指挥官，不是士兵 — SKILL.md 负责指挥流程，代码/模板/参考资料应放在各自的层次，Skill 才可维护

错误处理

在 Workflow 中显式覆盖失败分支，不要只写正常路径：

## Steps
1. 检查前置条件是否满足
   - 不满足 → 告知用户原因并停止
2. 检查是否有可操作的对象
   - 没有 → 告知用户当前状态
3. 条件满足，执行核心操作

小结

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

在企业级应用场景下，同一个任务往往需要在不同时间、由不同用户高频触发。如果系统行为依赖动态的上下文生成或临时的短提示词，系统输出将展现出极大的随机性。工程化系统要求的是确定性和高可靠性，需要一种机制能够将资深专家的“隐性知识”转化为大模型可理解的“标准操作流程（SOP）”