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 化使用效果
做了十几个知识库项目后,我把入库前的文档摸底流程产品化了

这篇试图说清楚:

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 的解决方案是三层按需加载:

层级
加载时机
内容
Token 消耗示例
第 1 层
Agent 启动时
YAML 头部的 name + description
每个 50-100 tokens
第 2 层
用户请求匹配时
SKILL.md 正文(完整指令)
1000-2000 tokens
第 3 层
执行过程中按需
references/ 里的详细文档
视情况而定

第一层相当于一份目录索引,模型看完就知道"有哪些能力可用"。只有当用户的请求和某个 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.md 
代码风格规范、PR 审查清单、文档模板
中等
SKILL.md+ references
产品知识库问答(references 里放产品文档)
重度
完整结构
数据治理工具包(27 个 Python 脚本 + 质量标签说明 + 阈值配置)

以上篇文章介绍的数据治理工具包为例,进行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 做些盘点,它们按用途大致可以分成四类:

类别
Skills
设计与艺术
algorithmic-art、canvas-design、frontend-design、theme-factory
文档与办公
docx、pdf、pptx、xlsx、doc-coauthoring
软件开发
web-artifacts-builder、webapp-testing、mcp-builder、skill-creator
内容与沟通
internal-comms、brand-guidelines、slack-gif-creator

从企业应用场景出发,文档处理类的 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…
— 以上为试看内容(约 40%),开通会员后阅读全文 —