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 看的执行步骤、使用指引、示例 | 触发匹配成功后才加载 |
--- 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 Markdown正文(指令部分)
Frontmatter结束后,写Markdown,用来告诉AI具体执行步骤,推荐划分模块:
Frontmatter 结束后,写 Markdown 用来告诉 AI 具体执行步骤,推荐划分以下模块:
| 模块 | 作用 |
|---|---|
| ## 使用场景 | 进一步细化适用、不适用场景 |
| ## 使用指引 | 分步骤、逐条的行为指令 |
| ## 输出规范 | 约束输出格式 |
| ## 示例 | 输入输出样例,帮助 AI 理解用法 |
--- 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(最少代码跑通)
--- name: demo-skill description: 演示技能,用户需要简单文本格式化的时候触发。 --- # Demo技能 ## 使用指引 将用户输入文本按段落整理,去掉多余空行。
3. Skill存放位置
分两种部署模式:
- 全局Skill:存放于
~/.claude/skills/,本机所有项目都可以使用; - 项目局部Skill:项目目录下
.claude/skills/,仅当前项目生效,适合团队业务SOP沉淀。
创建目录示例(终端)
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自动识别任务、自动加载对应工作流,适合个人提效、团队沉淀业务规范。
到此这篇关于AI Agent Skills从原理到上手编写SKILL.md实战教程的文章就介绍到这了,更多相关AI Agent Skills实战内容请搜索脚本之家以前的文章或继续浏览下面的相关文章,希望大家以后多多支持脚本之家!
相关文章
本文梳理AI Agent高频面试考点,覆盖基础概念、架构、推理规划、工具调用、记忆、RAG融合、多智能体与工程落地,具有一定的参考价值,感兴趣的可以了解一下2026-09-23
DeepSeek Harness部署指南:5分钟上手AI Agent 工作台
本文介绍了如何快速上手运行DeepSeekHarness,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧2026-08-19
DeepSeek Harness搭建完整的AI Agent本地开发环境的实战指南
告别与AI对话却无法实践操作的困扰,本文教你将DeepSeek Harness框架与ServBay结合,快速搭建可执行真实开发任务的AIAgent环境,无需复杂命令,轻松实现数据库配置、SSL证书签2026-08-19
Harness Engineering让AI Agent从跑偏到可控
本文深度拆解模型约束、反馈校验与可观测三大核心支柱,教你搭建防跑偏系统,把模型威力锁进业务规则, 需要的朋友们下面随着小编来一起学习学习吧2026-08-13
DeepSeek v4 Flash与Pi Agent本地部署指南:打造私有化AI编程助手
本文主要介绍了DeepSeek v4Flash与PiAgent如何组成终极AI开发组合,助你本地部署高性价比编程助手,感兴趣的可以了解一下2026-08-10
AI Agent Context 压缩策略选型核心在于根据任务连续性、信息敏感度与成本约束,在“无损外部化(Offload)”、“有损摘要(Summarize)”、“规则修剪(Prune)”与“结构2026-07-21
AI Agent Harness它是一套系统化工程方法论,专门设计、搭建、运维这套 AI 管控运行体系,解决 AI 干活不稳定、越权、失忆、失控问题,简单来说它让AI智能体既跑得快,又跑2026-06-25
如何使用 AI Agent 做一个前端小游戏(从提示词到可运行Demo)
这段文章介绍了使用AI编程工具AIAgent制作一个简单前端小游戏的过程,并分享了完整代码和优化建议,适合前端初学者和开发者学习和参考,感兴趣的朋友跟随小编一起看看吧2026-06-24
CI/CD中的AI如何用Agent自动生成Release Note
这篇教程教你如何使用GitHub Actions和AI工具daily-report-agent自动生成ReleaseNote,省时,提高效率,本文介绍的非常详细,感兴趣的朋友一起看看吧2026-06-23
Hermes Agent vs OpenClaw:2026年两大AI Agent框架深度对比分析
OpenClaw作为开源社区宠儿,Hermes Agent作为企业级解决方案,两者在设计理念、架构实现和适用场景上存在根本性差异,本文就对二者进行了深度的对比分析,需要的朋友可以参考2026-04-21











最新评论