Agent Skills实战:27个脚本不进上下文,一句话完成RAG入库前文档扫描
Anthropic在25年12月18日宣布把Agent Skills 发布为开放标准,到现在刚一个多月时间里,Cursor、OpenCode、Antigrativy 等主流 AI 编程工具就已经完成了集成,GitHub 上星标也超过了 52k。
项目地址:https://github.com/anthropics/skills
刚发布那会儿我在忙着录制视频课程,一月初才来得及具体测试。起初先是跑了一遍 Reddit 和 X 上热议的几个开源项目,然后又在手头的知识库和数据治理项目里实际用了一段时间。目前用了两三周下来,整体感受是 Skills 解决的问题不新鲜(Prompt 管理、脚本复用),但它提供的抽象方式确实够简洁,一个文件夹、一份 Markdown、一套目录约定,就把让大模型记住怎么做某件事这个需求给标准化了。
市面上介绍Agent Skills 的文章不少,但大多停留在个人效率工具层面。这些玩法当然有用,但我更感兴趣的是另一个问题,就是 Skills 这套机制,在 2B 企业大模型应用里能怎么用?能不能把已有的业务脚本和工作流封装成 Skill,让非技术人员也能调用?
这篇试图说清楚:
Skill 的核心设计理念(渐进式披露)与文件规范、它与 MCP 及多 Agent 的本质区别、如何将现有项目(以数据治理工具包为例)进行 Skill 化改造,以及从投标书生成等长文档场景出发,探讨 Skill 在企业级交付中的产品化潜力。
以下,enjoy:
1
什么是 Agent Skills?
一句话定义:Agent Skills 是一套基于文件系统的 Prompt 工程化规范。说人话就是,它把让大模型记住怎么做某件事这个需求,抽象成了一个标准化的文件结构。核心我总结下来就三件事:
1、用一个文件夹来封装一个"能力";2、用 Markdown 来描述这个能力的调用方式;3、用 YAML 头部来做索引,让大模型知道什么时候该调用
规范本身很简单,没有复杂协议,不需要 SDK,任何支持文件读取的 Agent 都能实现。
1.1
为什么需要渐进式加载
渐进式加载是 Skill 设计里最核心的理念,也是它区别于传统 Prompt 管理方式的关键。
传统做法是把所有指令都塞进 System Prompt。问题在于上下文窗口是稀缺资源。假设你有 50 个 Skill,每个 2000 tokens,全塞进去就是 10 万 tokens,大模型还没干活,上下文就爆了。
但很多人聊上下文优化,第一反应是怎么压缩、怎么摘要、怎么用 RAG 只召回相关片段。这些当然有用,但从第一性原理出发,最有效的优化其实是"非必要不传入",也就是在源头上就把当前处理阶段模型不需要看到的内容排除掉。Skill 的渐进式加载,本质上就是这个思路的工程化落地。
Skill 的解决方案是三层按需加载:
第一层相当于一份目录索引,模型看完就知道"有哪些能力可用"。只有当用户的请求和某个 Skill 的 description 匹配的时候,大模型才会去读取完整的指令。这样 50 个 Skill 的索引加起来也就 2500-5000 tokens,完全可接受。
1.2
文件结构与 SKILL.md格式
一个Skill就是一个文件夹,核心是 SKILL.md 文件:
my-skill/├── SKILL.md # 核心:指令文件├── scripts/ # 可选:可执行脚本├── references/ # 可选:详细文档└── assets/ # 可选:配置文件、Schema 等
SKILL.md 的格式也很直接,开头是 YAML 头部,后面是 Markdown 正文:
---name: data-analysisdescription: 分析数据集并生成可视化报告,支持 CSV/Excel/JSON 格式。---# 数据分析 Skill## 使用场景...## 执行流程...
这里有个关键点:description 的质量直接决定模型能否正确匹配到这个Skill。写 description 要像写函数签名一样,说清楚输入输出和适用场景。
1.3
不只是Prompt 管理:scripts/references/assets 的价值
如果只看 SKILL.md,可能会有盆友觉得这不就是把 Prompt 放到文件里管理,意义也不是很大。确实,纯文本指令的场景下,Skill 和传统的 Prompt 模板没有本质区别。
但 Skill 的真正价值在于它可以封装完整的工作流,不只是一段提示词,而是提示词 + 可执行代码 + 参考文档 + 配置文件的组合。这让它能覆盖从简单到复杂的各种场景:
以上篇文章介绍的数据治理工具包为例,进行Skill化之后,scripts/ 里放了文档解析、格式识别、质量评估等脚本;references/ 里放了质量标签的详细说明文档;assets/ 里放了输出报告的 JSON Schema。用户只需要说"帮我扫描这个文件夹的文档质量",模型读取 SKILL.md后知道该怎么调用脚本、怎么解读结果,整个流程一气呵成。
这就是 Skill 区别于普通 Prompt 模板的地方,它不是把复杂逻辑都塞进提示词让大模型理解,而是把执行逻辑外置到脚本、把领域知识外置到 references、把配置参数外置到 assets,SKILL.md只负责告诉模型这些东西在哪、怎么用。
1.4
发现与激活机制
Skill 的发现机制说白了就是目录扫描。Agent 启动时遍历指定目录(全局目录和项目目录),找到所有包含 SKILL.md 的文件夹,解析 YAML 头部,构建索引。(不同平台的目录约定略有差异)
全局目录放跨项目通用的 Skill,比如代码审查、文档生成;项目目录放特定项目的 Skill,比如某客户的数据治理规则。
激活流程也很简单直接:用户发消息 → 模型根据 description 判断匹配哪个 Skill → 读取完整 SKILL.md→ 按指令执行。
但有一点需要强调,就是原则上脚本代码不进入上下文,只有执行结果进入。这是上下文优化的关键。比如我在上篇文章中介绍的 RAG 入库前的文档扫描工具包,其中有 27 个 Python 脚本,全塞进 Prompt 大家要 5 万 tokens;但通过 Skill 机制,上下文只需要 SKILL.md(2000 tokens 左右)加上脚本的执行结果。
1.5
两种集成方式
Skill 有两种集成方式,选哪种取决于 Agent 的运行环境:
方式一:文件系统直读
适用于 Cursor、Claude Code 这类本地 IDE 环境。模型直接用 Shell 命令读取文件:
cat ~/.claude/skills/data-analysis/SKILL.md
这是最灵活的方式,大模型可以自主决定读取哪些内容。
方式二:通过 Tool 调用
适用于 Web 应用(例如网页端的Claude)、API 服务等没有文件系统访问权限的场景。需要封装成 Tool 供模型调用,比如通过 MCP Server 提供 list_skills、get_skill_content 等接口。
两种方式的核心逻辑一样,只是访问路径不同。对于企业级应用,工具方式更常见,因为可以做权限控制、审计日志、远程 Skill 库等。
1.6
底层实现原理
虽然大家应该主要是在 IDE 里使用 Skill,但它的底层实现并不复杂,本质就是目录扫描 + 提示词注入 + 按需加载。核心代码逻辑大约 50 行:
# 1. 启动时:扫描目录,只读取 YAML 头部(name + description)def discover_skills(skills_dir):for folder in Path(skills_dir).iterdir():skill_md = folder / "SKILL.md"if skill_md.exists():metadata = parse_frontmatter(skill_md) # 只读头部skills.append(metadata)return skills# 2. 生成索引,注入到 System Promptavailable_skills_xml = generate_xml(skills) # <available_skills>...</available_skills># 3. 运行时:模型判断需要某 Skill 时,调用工具读取完整内容if tool_name == "view_text_file":content = Path(file_path).read_text() # 此时才加载完整 SKILL.md
特别解释一下这个底层的原理,是想说明 Skill 机制不依赖任何特定 IDE,可以嵌入到任何后端服务里。大家完全可以在自己的大模型应用中实现同样的逻辑:目录扫描、元数据索引、按需加载,把 Skill 作为模块化知识与能力的封装形态。
2
官方 Skill 案例拆解:以 docx 为例
聊完核心概念,来看一个真实的 Skill 长什么样。Anthropic 在发布规范的同时,官方仓库里提供了 16 个参考实现。除此之外,GitHub 上也涌现出不少开源 Skill 库项目,热度很高。这篇我就针对官方的这 16 个 skill 做些盘点,它们按用途大致可以分成四类:
从企业应用场景出发,文档处理类的 Skill 最有参考价值。我拿 docx(Word 文档处理)来做个拆解。
2.1
docx Skill 的文件结构
docx/├── SKILL.md # 主指令文件(约 200 行)├── docx-js.md # 参考文档:docx-js 库用法├── ooxml.md # 参考文档:OOXML 格式详解├── scripts/ # Python 脚本│ ├── document.py # 文档操作库(5 万字符)│ └── utilities.py # 工具函数└── ooxml/ ├── scripts/ # unpack.py、pack.py 等 └── schemas/ # XML Schema 定义
这是一个相对重度的 Skill 结构。主指令文件 SKILL.md负责告诉大模型什么场景用什么工具,具体的技术细节则外置到 references(这个skill官方包里实际没有这个文件夹) 和 scripts 里。
2.2
SKILL.md的设计思路
打开 SKILL.md,开头是 YAML 头部:
name: docxdescription: "Comprehensive document creation, editing, and analysis with suppo…