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.md3.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 SkillsMCP / 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, encodingutf-8) as f: rows list(csv.reader(f)) if not rows: output_path.write_text(, encodingutf-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), encodingutf-8) if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(--input, requiredTrue) parser.add_argument(--output, requiredTrue) 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-reportdescription 太宽、目录放错、会话未重载脚本联动含空行的 CSV正常输出 Report.mdPython 路径、脚本权限、相对路径负向测试“今天天气怎么样”不触发 csv-reportdescription 写得太泛导致误命中项目共享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, jsonpayload, headersheaders, timeout120) 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_okTrue) for csv_file in sorted(input_dir.glob(*.csv)): out_file output_dir / f{csv_file.stem}.md if out_file.exists(): print(fskip {csv_file.name}) continue print(fprocessing {csv_file.name}) subprocess.run( [python, scripts/csv_to_md.py, --input, str(csv_file), --output, str(out_file)], checkTrue, ) time.sleep(1)批量任务要注意三点幂等每个任务的输出文件应能根据输入唯一确定重跑不产生副作用。日志建议记录每个文件的处理状态、耗时和异常信息方便定位失败任务。失败隔离某个文件报错不应该中断整批任务可以在 subprocess 调用处增加 try/except把异常写入errors.log后继续下一个。如果技能本身需要模型参与例如生成摘要批量场景更建议把“模型调用”和“文件处理”拆成两步先用脚本完成格式转换再对每个结果调用模型生成摘要。这样即使模型服务抖动也不会影响整个批处理流程。8. 资源占用与性能观察Agent Skills 的资源占用与运行载体强相关不能一概而论。如果你使用云端 API 推理本地端的显存压力基本为零主要观察的是API 延迟单次请求响应时间。Token 消耗SKILL.md 正文越长、reference 文件被读取越多token 消耗越大。上下文窗口技能按需加载的好处是平时不占用上下文但一旦技能被加载SKILL.md 及其引用的参考文档都会进入当前上下文需要控制单技能体量。如果你使用本地自建模型显存占用取决于模型本身。观察命令可以这样写nvidia-smi --query-gpumemory.used,utilization.gpu --formatcsv -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 组合使用技能负责流程工具负责原子操作三是把技能包接入批处理流水线让定点任务能自动处理一批同类输入。从一个小技能开始跑通后再迭代这条路比一开始设计完整框架更稳。