Agent Skills 是最近讨论度很高的一类 AI 工程概念。它并不是一个新的基础大模型，而是一套“技能封装 + 动态调度”的规范：把提示词、操作步骤、脚本和参考文档打包成一个技能目录，Agent 在遇到对应任务时按需读取并执行。以 Anthropic 在 Claude 中推出的 Agent Skills 为代表，现在很多自建 Agent 项目也在借鉴这套模式，来解决 prompt 过长、指令漂移、工具调用混乱、团队复用困难这些问题。
这个模式值得关注的核心点有 5 个：第一，技能按需加载，Agent 不用在所有对话里都背着整套说明书；第二，提示词与代码可以绑在同一个技能包内，既能约束模型行为，也能真实调用脚本完成处理；第三，适用面广，代码仓库分析、文档格式转换、数据报表生成、论文写作辅助流程都可以封装成技能；第四，团队可以通过项目目录共享技能包，做到 prompt 和工具的统一管理；第五，对端侧硬件不构成强约束，如果跑在云端推理场景，本地不需要 GPU，具体资源开销要看你的运行载体。
这篇文章会从三块展开：先讲技能封装，说清楚 SKILL.md 怎么写、脚本和参考文档怎么放；再讲 Agent 调度，理解模型是怎么根据描述命中技能、按需加载的；最后落到项目实战，给你一套最小技能包的搭建、触发验证、批量任务处理和问题排查流程。整个过程以可执行为主，你可以边看边在自己环境里复现。
适合阅读这篇文章的人：正在做 Agent 应用的工程师、希望规范 prompt 和工具调用的团队、需要把研究或工作流程固化成可复用技能的内容生产者，以及刚接触 Agent Skills、想搞清楚它到底能解决什么问题的开发者。
1. Agent Skills 核心能力速览
| 能力项 | 说明 |
|---|---|
| 项目类型 | Agent 技能封装与调度规范，不是独立基础模型 |
| 代表实现 | Anthropic Claude 的 Agent Skills 模式，具体以官方最新文档为准 |
| 常见运行载体 | Claude 桌面端、Claude Code、自建 Agent 框架 |
| 技能最小单元 | SKILL.md 文件 + scripts/reference/assets 等子目录 |
| 调度方式 | 模型根据用户任务与技能的 description 匹配，按需加载技能说明 |
| 硬件门槛 | 云端推理时本地无需 GPU；本地自建 Agent 需按所选模型评估显存与内存 |
| API 支持 | 可结合 Claude Code、Claude API 或自建 Agent 调用，接口细节需按官方文档确认 |
| 批量任务 | 可通过任务清单、循环调用技能脚本实现，建议配合日志和失败重试 |
| 典型场景 | 数据报表、文档转换、代码仓库分析、研究方法流程固化、团队 prompt 统一 |
| 主要风险点 | description 写得不准导致技能不触发；云端推理需要关注数据隐私与授权 |
从表里能看出，Agent Skills 的定位不是“又一个模型”，而是在现有模型之上加一层工程封装。它和 Function Calling、MCP 这类工具协议可以共存：工具负责单点能力，技能负责整块工作流。下面从最核心的“技能封装”开始拆。
2. Agent Skills 解决什么问题，适用场景与使用边界
2.1 核心痛点：prompt 和工具是分离的
没有技能封装时，工程项目里常见的情况是：prompt 写在代码里、工具函数散落在各个模块、示例输出存在文档里。要让模型正确完成任务，开发者必须把所有信息一次性塞进 context，导致 prompt 越来越长、越来越容易漂移。
Agent Skills 的做法是把“做什么、怎么做、调用什么脚本、参考什么格式”合并成一个自包含的技能包。模型在需要时才加载这个包，不使用时完全不占用上下文。这样有几个直接收益：prompt 可以按业务域拆分；脚本和处理逻辑能跟随技能包一起分发；新成员拿到技能包就能复用同一套行为标准。
2.2 典型场景：从数据报表到研究流程固化
比较适合落地的场景包括：
- 数据处理与报表：给定 CSV 或 JSON，调用技能脚本生成 Markdown 报表、图表数据或汇总摘要。
- 文档批量转换：把一种格式转换为另一种格式，例如 PDF 文本提取、CSV 转表格、代码片段格式化。
- 代码仓库分析：技能包内约定分析步骤，模型按步骤扫描仓库结构、生成说明文档或发现潜在问题。
- 流程化写作与研究方法辅助：结合“人文社科混合研究方法论文写作”这类场景，可以把文献整理、方法选择、写作规范、引用检查拆成多个技能包，让模型在每一个环节只加载对应技能，降低跑题风险。注意，这只适合做辅助草稿和格式整理，数据、引用和结论必须人工核对。
2.3 使用边界与合规提醒
Agent Skills 并不是万能的。实时交互要求很高的场景、需要多轮人工确认的敏感流程、超大上下文中一次性处理全部资料的需求，都不适合硬拆成技能。另外，如果使用云端 API 推理，注意不要直接把敏感数据、未授权素材或内部机密文件传给外部服务；企业落地前应该先做数据脱敏或私有化部署评估。凡是涉及人脸、声音、版权素材、学术引用和可能影响决策的生成结果，都必须在发布或商用前进行人工复核。
3. 技能封装：从 Prompt 到 SKILL.md
3.1 技能包的目录结构
一个技能包本质上就是一个目录。以 Claude 生态为例，技能目录一般放在用户级目录~/.claude/skills/或项目级目录.claude/skills/，项目级目录可以随代码仓库一起提交给团队共享。一个典型结构如下：
~/.claude/skills/csv-report/ ├── SKILL.md ├── scripts/ │ └── csv_to_md.py ├── reference/ │ └── format_example.md └── assets/SKILL.md是技能入口，包含技能名称、描述和执行说明。scripts/存放技能需要调用的脚本，例如 Python、Shell、Node 脚本。reference/存放参考文档、模板、格式示例。assets/存放图片、字体等静态资源，按需使用。
这个结构本身没有太多魔法，关键是模型会在用户任务与技能描述匹配时读取 SKILL.md，并在需要时进一步读取脚本和参考文档。因此，SKILL.md 的写法决定了技能能不能被正确触发。
3.2 SKILL.md 的字段与正文结构
SKILL.md 由两部分组成：YAML frontmatter 和 Markdown 正文。frontmatter 里至少要有name和description，其中description是模型判断“什么时候使用这个技能”的核心依据。它要写得具体、可匹配、避免含糊。
--- name: csv-report description: 将 CSV 数据整理为 Markdown 报表，适合做数据汇总和快速预览场景 --- # CSV 报表技能 在用户提供 CSV 文件并希望生成 Markdown 报表时使用。 执行步骤： 1. 定位 CSV 文件路径。 2. 运行下面的脚本生成 Markdown 表格。 3. 把生成的报表内容整理进最终回复。 脚本用法： python scripts/csv_to_md.py --input data.csv --output report.md正文部分建议按“何时使用、执行步骤、脚本用法、示例输入输出、注意事项”来组织。这样模型在加载技能后，能按固定流程完成任务，而不是自由发挥。需要强调的是：正文要写给模型看，不是写给用户看。所以每一步必须明确、可执行，脚本路径和参数都要写清楚。
4. Agent 调度：技能按需加载的工作原理
4.1 一次完整的技能调度过程
Agent Skills 的调度可以简化为四个阶段：
- 用户输入任务，例如“帮我把 data.csv 生成报表”。
- 模型根据已有上下文和候选技能的 description 做匹配，判断当前任务是否命中某个技能。
- 命中后，模型读取对应 SKILL.md，获取执行步骤。
- 模型按步骤操作，必要时运行脚本、读取 reference 文件，最后汇总结果返回给用户。
这里最关键的是第 2 步。技能是否被触发，主要看 description 与用户目标的匹配度。写得太泛，模型会在无关任务中错误加载；写得太窄，需要时又发现不了。所以 description 可以理解为技能包的“索引键”。
4.2 Agent Skills 与 MCP/Function Calling 的差异
| 维度 | Agent Skills | MCP / Function Calling |
|---|---|---|
| 粒度 | 整块工作流，包含说明、步骤、脚本 | 单点工具或函数，输入输出明确 |
| 上下文占用 | 按需加载完整说明，平时不占用 | 每次调用携带函数签名和参数 |
| 适合场景 | 多步骤数据处理、文档分析、流程化任务 | 查天气、调业务接口、读数据库 |
| 典型载体 | SKILL.md + 脚本 + 参考文档 | 工具定义 + 参数 schema |
两者不是互斥关系。技能内部完全可以调用 MCP 工具或普通函数，Agent Skills 负责“把任务拆成流程并指导执行”，MCP/Function Calling 负责“执行单个原子操作”。
4.3 自建 Agent 的调度模拟
如果你不在 Claude 生态里，而是想在自己写的 Agent 框架中实现类似调度，思路是可以复用的。先做一个技能注册表，再用规则或 LLM 匹配用户问题，最后把选中的技能说明注入模型上下文：
def load_skills(skill_root: str) -> list[dict]: """遍历技能目录，读取每个 SKILL.md 的 name 和 description。""" ... def select_skill(skills: list[dict], query: str) -> dict | None: """根据 query 与 description 的匹配度选择技能。实际可走 LLM 或向量检索。""" ... def run_skill(skill: dict, query: str) -> str: instructions = read_skill_md(skill) result = agent_complete(instructions + query) return result上面是伪代码，演示的是调度思想：注册、匹配、注入、执行。具体实现时，匹配环节可以用 embedding 检索，也可以让模型自己选，但始终要保留一层“人工可干预”的开关，避免技能误触发。
5. 环境准备与最小技能搭建
5.1 运行方案选择
Agent Skills 的试运行有两条路线。
路线 A：使用 Claude 桌面端或 Claude Code。这种方案下推理发生在云端 API 侧，本地不需要独立 GPU，配置重点是账号、模型可用状态和技能目录权限。需要留意的是，不同版本对技能目录的识别规则可能有差异，以官方最新文档为准。
路线 B：自建 Agent + 本地模型。这种方案完全自己控制调度逻辑，但显存和内存开销取决于你选择的模型及其量化版本。不同模型差异很大，不能一概而论，需要按实际测试结果评估。
5.2 创建技能目录
先确认现有技能目录：
ls -la ~/.claude/skills 2>/dev/null || echo "not exists" ls -la .claude/skills 2>/dev/null || echo "not exists in current project"创建最小技能包：
mkdir -p ~/.claude/skills/csv-report/scripts在~/.claude/skills/csv-report/下创建SKILL.md，内容用上面第 3 节的示例即可。然后创建脚本scripts/csv_to_md.py：
#!/usr/bin/env python3 import argparse import csv from pathlib import Path def csv_to_markdown(input_path: Path, output_path: Path) -> None: with input_path.open("r", encoding="utf-8") as f: rows = list(csv.reader(f)) if not rows: output_path.write_text("", encoding="utf-8") return lines = [ "| " + " | ".join(rows[0]) + " |", "| " + " | ".join(["---"] * len(rows[0])) + " |", ] for row in rows[1:]: lines.append("| " + " | ".join(row) + " |") output_path.write_text("\n".join(lines), encoding="utf-8") if __name__ == "__main__": parser = argparse.ArgumentParser() parser.add_argument("--input", required=True) parser.add_argument("--output", required=True) args = parser.parse_args() csv_to_markdown(Path(args.input), Path(args.output))如果是在本地手动验证脚本，可以先用一个测试 CSV 文件跑一遍：
python scripts/csv_to_md.py --input data.csv --output report.md脚本本身不依赖模型，可以先排除代码问题，再进对话测试技能触发。
6. 功能测试与效果验证
技能搭建完之后，最重要的不是“技能能跑”，而是“模型能不能在正确时机加载它”。下面是一组适合逐步执行的验证流程。
6.1 技能发现测试
准备一个 CSV 文件，在对话中输入：
请使用 csv-report 技能把 data.csv 生成 Markdown 报表。预期结果：模型主动读取 SKILL.md，按步骤调用脚本或自己生成表格，并在回复中给出report.md的处理结果。如果模型没有调用技能，而是直接凭空生成表格，说明 description 匹配失败或技能目录未被识别。
反向测试同样重要：输入一个与技能无关的问题，例如“今天天气怎么样”，观察模型是否错误加载 csv-report。正常情况下技能不应被触发。
6.2 脚本联动测试
把 CSV 中放入空行、特殊字符或多列数据，重新请求生成报表。这一步可以验证：
- 技能脚本是否能处理脏数据；
- 模型在脚本报错时能否读取错误信息并修正；
- 脚本输出格式是否满足预期。
如果脚本报错，优先检查脚本依赖的 Python 版本、路径权限和相对路径解析。技能脚本在模型环境中运行时，工作目录可能和手动运行时不同，建议在脚本里显式使用绝对路径或基于__file__定位资源。
6.3 项目级共享测试
将.claude/skills/提交到 Git 仓库，团队成员 clone 后直接测试同一个技能。这里要确认：
- 技能目录是否被 Git 正确跟踪；
- 团队成员环境是否安装了脚本依赖；
- SKILL.md 中的路径说明是否对所有机器都通用。
| 测试项 | 输入 | 预期结果 | 失败排查点 |
|---|---|---|---|
| 技能发现 | “把 data.csv 生成报表” | 模型主动加载 csv-report | description 太宽、目录放错、会话未重载 |
| 脚本联动 | 含空行的 CSV | 正常输出 Report.md | Python 路径、脚本权限、相对路径 |
| 负向测试 | “今天天气怎么样” | 不触发 csv-report | description 写得太泛导致误命中 |
| 项目共享 | clone 仓库后测试 | 其他成员也能使用 | 依赖缺失、目录未提交、路径硬编码 |
7. 接口调用与批量任务落地
7.1 API 调用思路
Agent Skills 本身不是一个 HTTP 服务，它是一种技能定义和调度规范。如果你希望在代码中调用并复用技能，通用的做法是：把 SKILL.md 的说明和用户任务一起构造进模型请求，同时在请求前后用脚本完成数据预处理和后处理。
下面是一个调用结构示例，注意 endpoint、model 名称和请求头需要按你所用的服务商正式文档替换：
import requests API_URL = "https://api.example.com/v1/messages" # 替换为真实接口 API_KEY = "your-api-key" # 替换为你的密钥 payload = { "model": "your-model-name", "max_tokens": 4096, "messages": [ { "role": "user", "content": "请使用 csv-report 技能处理 data.csv，并输出 Markdown 报表。" } ] } headers = { "x-api-key": API_KEY, "content-type": "application/json" } response = requests.post(API_URL, json=payload, headers=headers, timeout=120) print(response.json())如果你使用的是 Claude Code 这类交互式工具，也可以直接在会话中触发技能，不需要自己写 HTTP 客户端。对于生产系统，更推荐的做法是：脚本逻辑留在本地，模型只负责决策和生成说明文本，关键的数据处理由技能脚本完成，降低模型幻觉对结果的影响。
7.2 批量任务：用任务清单驱动技能脚本
批量处理的关键是让每个任务最小化、可重跑。一个实用做法是：把输入文件统一放在inputs/目录，用 Python 循环调用技能脚本，输出到outputs/，已经生成的跳过，保证断点续跑。
from pathlib import Path import subprocess import time input_dir = Path("./inputs") output_dir = Path("./outputs") output_dir.mkdir(exist_ok=True) for csv_file in sorted(input_dir.glob("*.csv")): out_file = output_dir / f"{csv_file.stem}.md" if out_file.exists(): print(f"skip {csv_file.name}") continue print(f"processing {csv_file.name}") subprocess.run( ["python", "scripts/csv_to_md.py", "--input", str(csv_file), "--output", str(out_file)], check=True, ) time.sleep(1)批量任务要注意三点：
- 幂等：每个任务的输出文件应能根据输入唯一确定，重跑不产生副作用。
- 日志：建议记录每个文件的处理状态、耗时和异常信息，方便定位失败任务。
- 失败隔离：某个文件报错不应该中断整批任务，可以在 subprocess 调用处增加 try/except，把异常写入
errors.log后继续下一个。
如果技能本身需要模型参与（例如生成摘要），批量场景更建议把“模型调用”和“文件处理”拆成两步：先用脚本完成格式转换，再对每个结果调用模型生成摘要。这样即使模型服务抖动，也不会影响整个批处理流程。
8. 资源占用与性能观察
Agent Skills 的资源占用与运行载体强相关，不能一概而论。
如果你使用云端 API 推理，本地端的显存压力基本为零，主要观察的是：
- API 延迟：单次请求响应时间。
- Token 消耗：SKILL.md 正文越长、reference 文件被读取越多，token 消耗越大。
- 上下文窗口：技能按需加载的好处是平时不占用上下文，但一旦技能被加载，SKILL.md 及其引用的参考文档都会进入当前上下文，需要控制单技能体量。
如果你使用本地自建模型，显存占用取决于模型本身。观察命令可以这样写：
nvidia-smi --query-gpu=memory.used,utilization.gpu --format=csv -l 1性能优化的重点同样有三个：
- description 要短而准。description 是模型做技能匹配的索引，写太长反而降低匹配准确率。
- 大文档放 reference，而不是塞进 SKILL.md。SKILL.md 只保留执行步骤，详细格式模板、长示例放进 reference 文件，按需读取。
- 脚本保持幂等和轻量。技能里的脚本尽量只做单一数据处理任务，不要在脚本里塞过多业务逻辑，否则后续维护会变成灾难。
9. Agent Skills 常见问题与排查方法
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
| 技能完全不触发 | description 与用户任务不匹配；技能目录放错位置 | 检查 SKILL.md 的 description；确认目录是否在~/.claude/skills/或项目级.claude/skills/ | 重写 description，用用户常用表达方式描述触发场景 |
| 触发了但模型不按步骤执行 | SKILL.md 正文步骤不明确；模型对脚本用法理解偏差 | 检查 SKILL.md 中是否给出脚本路径和参数示例 | 在正文中增加具体示例，写明“先执行什么、再执行什么” |
| 脚本执行报错 | 依赖缺失；路径问题；脚本权限不足 | 手动运行脚本，查看具体报错 | 在脚本开头增加依赖检查；使用绝对路径；补齐执行权限 |
| 修改技能后不生效 | 会话仍持有旧的技能缓存 | 重启会话或重新加载技能目录 | 修改技能后新建对话测试，而不是沿用旧会话 |
| 上下文过大 | SKILL.md 写得太长；加载了过多 reference 文件 | 检查 token 消耗和请求日志 | 精简 SKILL.md，把长内容拆到 reference 按需读取 |
| API 调用超时 | 单次任务处理时间过长；模型服务限流 | 查看响应耗时和重试日志 | 设置超时上限；增加重试；把大任务拆成多个小任务 |
| 团队共享后行为不一致 | 成员依赖环境不同；技能目录未同步 | 对比两边的技能目录和依赖 | 把依赖声明写入技能包说明；技能目录纳入 Git 管理 |
| 技能被误触发 | description 写得过于宽泛 | 输入负向测试问题，观察加载情况 | 细化 description，明确限定触发条件 |
排查时有一个通用原则：先脚本后模型。如果脚本本身不能在命令行跑通，就不要期望模型能帮你跑通。先保证脚本在纯命令行环境可执行，再进入 Agent 流程测试，能省下大量排查时间。
10. 从教程到项目落地：最佳实践
第一，先小范围验证一个最小技能。不要一上来就封装几十个技能。先选一个高频、边界清晰的任务，比如“CSV 转 Markdown”，跑通技能发现、脚本调用、反向测试这三个环节，确认整个链路稳定后再扩展。
第二，技能目录要规范。SKILL.md是唯一入口，scripts/只放脚本，reference/放模板和格式说明，assets/放静态资源。每个技能包内部不要混放无关文件。
第三，技能包纳入版本管理。.claude/skills/或自建 Agent 的skills/目录应该随代码一起提交到 Git。每次改动技能时，写清楚变更记录，方便团队成员同步。
第四，安全边界要提前约定。云端推理时不要直接把敏感数据传给外部模型；技能脚本里不要硬编码 API 密钥；技能输出的结果默认视为“未审阅内容”，尤其是涉及论文写作辅助、数据分析结论、新闻稿件生成时，必须有人工复核环节。
第五，涉及复杂任务时，把流程拆成多个技能包，而不是一个巨大技能包。例如“人文社科混合研究方法论文写作”场景，可以拆成文献整理、方法选择、数据清洗、引用检查等独立技能，模型在每一步只加载当前需要的技能，降低上下文污染和步骤漂移的风险。这里的底线是：AI 只负责生成辅助草稿和结构化内容，数据来源、引用真实性和最终结论必须由研究者本人确认。
11. 总结与下一步
Agent Skills 最值得尝试的地方，在于它把“模型行为约束”从长 prompt 中解放出来，变成一组可维护、可共享、可脚本化的技能包。真正值得你花时间验证的，不是复杂的工作流编排，而是一个最小技能包能否在真实会话里被正确触发、正确执行脚本、正确输出结果。
最容易踩的坑有三个：description 写得不准确导致技能不触发或误触发；技能目录放错位置导致模型根本读不到；修改 SKILL.md 后没有新开会话，旧上下文里继续测试造成误判。
下一步可以沿着三个方向扩展：一是把常用的文档处理、数据分析、写作规范流程逐步固化成技能库；二是把 Agent Skills 与 MCP、Function Calling 组合使用，技能负责流程，工具负责原子操作；三是把技能包接入批处理流水线，让定点任务能自动处理一批同类输入。从一个小技能开始，跑通后再迭代，这条路比一开始设计完整框架更稳。
