AI Agent Skills实战教程：从原理到上手编写SKILL.md
摘要
传统复制粘贴 Prompt 复用效率低、Token 开销大。Skills 是面向 AI 智能体的模块化能力封装，以 SKILL.md 为核心，采用 YAML 元数据 + Markdown 指令，实现按需渐进加载，把业务 SOP 沉淀为可自动触发、跨项目复用的 AI 技能包。本文讲解 Skills 背景概念、核心结构、字段规范、目录组织、完整示例以及避坑实践，帮助你快速上手编写自己的 Skill。
0. 前言：为什么需要Skills
日常使用大模型时，经常遇到这些痛点：
日常使用大模型时，经常遇到这些痛点：
| 痛点 | 具体表现 |
|---|---|
| 重复输入 | 复杂任务每次都要复制一大段 Prompt，容易遗漏条件 |
| Token 消耗高 | Prompt 全部塞进上下文，长对话容易被遗忘 |
| 规范难沉淀 | 团队内部 SOP、业务规范难以统一，每个人写出来结果不一致 |
| 共享困难 | 不同项目之间的提示逻辑无法便捷共享与版本维护 |
✨关键特性：按需、渐进式加载
系统启动只加载Skill简短元数据（name+description）；只有判断任务匹配后，才读取完整SKILL.md正文，大幅节省上下文Token，解决长Prompt臃肿的问题。
Skills vs 普通Prompt对比表
| 对比项 | 普通Prompt | Skills机制 |
|---|---|---|
| 使用方式 | 每次对话粘贴输入 | 编写一次，自动匹配触发 |
| Token消耗 | 全部内容一次性载入 | 仅匹配成功才加载完整指令 |
| 复用能力 | 手动复制粘贴 | 项目/全局目录存放，可共享分发 |
| 维护修改 | 每个对话重新写 | 修改SKILL.md文件，全部地方即时生效 |
| 输出一致性 | 依赖单次提示词质量 | 固定SOP，输出稳定可控 |
1. Skill整体架构
一个Skill就是独立文件夹 + SKILL.md主文件 。SKILL.md是强制必需文件，其余脚本、模板、参考资料全部为可选资源。
基础最简目录：
my-skill/
└── SKILL.md # 唯一必需文件完整推荐工程目录：
my-skill/
├── SKILL.md # ✅必须：YAML元数据 + AI执行指令
├── scripts/ # 可选：存放可执行脚本（python/shell）
├── references/ # 可选：详细参考文档、业务规范
└── assets/ # 可选：模板、静态资源文件各目录职责说明：
| 目录 | 作用 | 说明 |
|---|---|---|
scripts/ |
存放自动化脚本 | SKILL.md 内通过相对路径引用 |
references/ |
存放大段参考文档 | 避免把全部资料塞进 SKILL.md 造成臃肿 |
assets/ |
存放静态资源 | 报告模板、docx/markdown 模板、配置文件等 |
SKILL.md分为两大部分： |
||
SKILL.md 分为两大部分： |
| 部分 | 作用 | 加载时机 |
|---|---|---|
| YAML Frontmatter 头部元数据 | Skill 的身份证，决定 AI 能否识别、触发该技能 | 系统启动即读取 |
| Markdown 正文 | 给 AI 看的执行步骤、使用指引、示例 | 触发匹配成功后才加载 |
yaml
---
name: csv-data-analyze
description: 当用户上传csv表格，需要做数据探索、统计、可视化分析时使用，支持数据清洗、统计指标输出、绘图。
license: MIT
compatibility: "Claude Code、Agent运行环境"
metadata:
author: demo
version: "1.0.0"
---| 字段 | 是否必填 | 约束与说明 |
|---|---|---|
name |
✅是 | 唯一标识符；kebab‑case短横线命名；仅小写字母、数字、-；最多64字符；不能以连字符开头结尾；建议动名词，和文件夹同名，供斜杠命令调用。示例：pdf‑processing |
description |
✅是 | 最重要字段，最多1024字符；必须写两件事：①这个Skill能干什么；②什么场景触发。只有元数据里的描述会参与预匹配；正文里写的触发条件AI看不到！ |
license |
❌否 | 开源协议 |
compatibility |
❌否 | 写明兼容Agent环境、依赖包、权限要求 |
metadata |
❌否 | 自定义键值，版本号、作者等扩展信息 |
⚠️高频踩坑：触发条件不要只写在Markdown正文
##使用场景中。AI判断要不要启用Skill，只会读取Frontmatter的description，正文只有匹配后才会载入上下文，写正文里不会触发！
✅好示例description
description: >
处理PDF文档，提取文本表格、合并拆分PDF。当用户提到pdf、提取表格、合并文档、pdf表单填充时触发。❌差示例（太笼统，容易误触发）
description: PDF工具，处理文件。name命名规范：
✅推荐：
pdf-processing、csv-data-analyze（动名词，短横线小写）❌禁止：
PdfTool大写、pdf tool空格、pdf_tool下划线、tool过于模糊名称。
2.2 Markdown正文（指令部分）
Frontmatter结束后，写Markdown，用来告诉AI具体执行步骤，推荐划分模块：
Frontmatter 结束后，写 Markdown 用来告诉 AI 具体执行步骤，推荐划分以下模块：
| 模块 | 作用 |
|---|---|
## 使用场景 |
进一步细化适用、不适用场景 |
## 使用指引 |
分步骤、逐条的行为指令 |
## 输出规范 |
约束输出格式 |
## 示例 |
输入输出样例，帮助 AI 理解用法 |
markdown
---
name: pdf-processing
description: 对PDF文档操作，提取文本表格，合并拆分PDF，填充表单；用户提到pdf、提取表格、合并pdf、pdf表单填充触发本技能。
metadata:
version: "1.0"
author: demo
---
# PDF文档处理技能
## 使用场景
### 适用
1. 提取PDF文本、表格内容
2. 多个PDF文件合并、拆分
3. PDF表单字段填充生成新文档
### 不适用
1. PDF图片OCR识别扫描件（需要额外OCR工具）
2. PDF密码解密
## 使用指引
1. 如果是扫描版PDF，告知用户需要OCR工具协助；
2. 提取表格优先调用pdfplumber工具读取；
3. 合并PDF按用户指定顺序拼接；
4. 输出结果告知用户生成文件路径。
## 输出格式
- 提取表格输出markdown表格；
- 文件操作结束打印执行摘要。
## 使用示例
- 用户指令：提取报告.pdf的表格
- 用户指令：把a.pdf、b.pdf合并输出all.pdf最小可用SKILL.md（最少代码跑通）
markdown
---
name: demo-skill
description: 演示技能，用户需要简单文本格式化的时候触发。
---
# Demo技能
## 使用指引
将用户输入文本按段落整理，去掉多余空行。3. Skill存放位置
分两种部署模式：
- 全局Skill ：存放于
~/.claude/skills/，本机所有项目都可以使用； - 项目局部Skill ：项目目录下
.claude/skills/，仅当前项目生效，适合团队业务SOP沉淀。
创建目录示例（终端）
bash
mkdir -p .claude/skills/pdf-processing
# 在这个文件夹创建SKILL.md文件4. 编写Skill最佳实践&避坑清单
- 单一职责原则：一个Skill只做一类事情，不要把PDF处理+数据分析+代码审查全部塞在同一个Skill，拆分成多个小Skill，提升触发准确率。
- description必须写清楚：能力 + 触发关键词；不要笼统描述。
- 大段参考资料不要全部写进SKILL.md，放到
references/文件夹，通过相对路径引用，控制主文件token大小。 - scripts脚本放单独目录，SKILL.md中只写调用指引，不粘贴大段代码。
- name严格遵循kebab‑case小写+短横线命名，文件夹名与name完全一致。
- 区分「适用场景」与「不适用场景」，减少误触发。
- 多写输入输出示例，示例可以显著提升AI执行准确率。
常见问题
Q：为什么写好了Skill，AI不会自动调用？
A：优先检查Frontmatter的description，是否写清楚触发关键词；name命名是否规范；确认Skill文件夹路径放置正确。
Q：Skill会不会占用大量token？
A：不会。系统只预加载简短元数据，只有语义匹配成功，才加载完整Markdown指令，实现按需加载。
Q：Skill和MCP工具区别？
Skill侧重业务流程、SOP、提示指令，纯文件；MCP偏向外部API、服务器工具调用，需要服务运行，两者可以配合使用。
5. 总结
Skills把口头的业务SOP转化成标准化文件，解决传统Prompt难以维护、Token开销大、复用困难的痛点。核心就三件事：
- 创建文件夹，固定文件名
SKILL.md； - 顶部YAML填写必填
name、description，写清楚"做什么，什么时候触发"； - Markdown正文编写分步指令与示例，按需补充scripts、references、assets资源。
写好Skill之后，即可实现AI自动识别任务、自动加载对应工作流，适合个人提效、团队沉淀业务规范。