夜雨聆风学习资料网

ARTICLE · 1374483

十分钟全面了解 Skill 的 md 文档:一个文件夹、一个 SKILL.md,教会 AI 你的独门手艺

十分钟全面了解 Skill 的 md 文档:一个文件夹、一个 SKILL.md,教会 AI 你的独门手艺
2026 年教 AI 干活的默认方式,越来越像是给它写一份 Markdown 文件。上次说的是 AGENTS.md(项目说明),这次说它的兄弟:SKILL.md——教智能体"怎么做某件具体的事"。

一、Skill 是什么?一句话版

一个 Agent Skill,就是一个装着SKILL.md的文件夹。
SKILL.md分两半:上面是一小段YAML 元数据(这个技能是干嘛的、什么时候用),下面是Markdown 正文(具体怎么干的步骤)。
智能体启动时会扫一眼所有已安装技能的元数据,当你的请求和某个技能对上号,它就把那个技能的正文加载进来,照着做。
就这么简单。没有 SDK,没有注册中心,一个文件夹拷走就带走。
它的出身:Agent Skills 最早由Anthropic提出,2025 年 12 月在agentskills.io发布为开放标准,此后被 OpenAI Codex、Cursor、GitHub Copilot、VS Code、Gemini CLI 等 25+ 平台采纳。你写的技能可以在这些工具之间直接通用——这是它和各家私有 prompt 体系最大的区别。

二、为什么需要 Skill?看看它取代了什么

在 Skill 出现之前,教智能体一套固定流程只有两条路,都不好用:
每天往对话框里粘贴同一段 40 行的操作说明
—— 重复劳动,还容易粘漏
把所有流程塞进一个常驻说明文件
—— 每条消息都为这些内容付 token 成本,哪怕今天根本用不上
Skill 把两个问题一起解决了:说明住在文件里(不用重复粘贴),且在被用到之前几乎零成本(不常驻上下文)。

三、解剖一个 Skill

标准结构长这样:
pdf-table-extract/├── SKILL.md        必需:元数据 + 操作说明├── scripts/        # 可选:可执行脚本(运行,不读入上下文)├── references/     # 可选:参考文档(按需读入上下文)└── assets/         # 可选:模板、图片等静态资源(用于输出)
SKILL.md 长这样:
---name: pdf-table-extractdescription: "Extracts tables from PDF files into CSV or JSON, handling  multi-page tables and merged headers. Use when a task needs structured  data pulled out of a PDF report, invoice, or form."license: MIT---Steps1. 找出所有包含表格的页面2. 提取行列,保留表头3. 跨页表格要做合并4. 输出前统一空白和货币格式## Error handling如果某页是扫描件、没有文本层,如实说明,不要瞎猜。

四、核心机制:渐进式披露(Progressive Disclosure)

这是整个设计里最聪明的一环,Skill 便宜就便宜在这——加载分三级:
算笔账:装50 个技能,常驻成本大约相当于一段普通文本。对比"所有流程塞一个常驻文件"的方案,这基本是降维打击。有社区实测,同样的流程用渐进式元数据写法能省约84% 的 token。
而 Codex 把预算挑明了:初始技能清单上限是模型上下文窗口的2%(窗口未知时按 8000 字符封顶)。其他工具没公布数字,但原则相同。

五、description 是全文最重要的一个字段

三级加载意味着:模型在决定用不用你的技能之前,只能看到 description。这个字段写得差,技能写得再好也没人用。
好坏对比:
差 —— 模糊,没有触发词description:        Helps with documents# 好 —— 具体动作 + 使用场景 + 触发词description: Extract text and tables from PDF files, fill forms, merge  documents. Use when working with PDF files, forms, or document  extraction.
写法要点:
第三人称:"Processes Excel files…",别写 "I can help you…"
结构 = 做什么 + 什么时候用 + 用户会打什么词
有明确文件类型就写上(.xlsx、.pdf)
会被误触发的技能加反向触发:"Do NOT use for simple data exploration; use the data-viz skill instead."
调试技巧:直接问智能体"你什么时候会用到这个技能?"——它答不上来,就是 description 的问题。

六、写正文的几条铁律

来自 Anthropic 官方最佳实践:
保持简短——模型本来就聪明,只写它没有的信息。别把常识教程写进去
祈使句:"执行 X 得到 Y",而不是"你应该……"
写"这样做、别那样做",别写功能介绍
超过 500 行就拆——细节挪进 references/,从正文一层引用(引用链别超过一层,深链会让智能体只读文件开头就放弃)
超过 100 行的参考文件,开头加目录
6. 脚本和文档分开表达意图:"Run scripts/extract.py 提取字段"(执行)和 "See scripts/extract.py 看算法"(阅读)是两种指令
7. 一个技能一个概念——别做万能技能

七、装在哪、怎么装

不同工具的存放位置:
安装第三方技能基本就是克隆进目录,或用市场方式:
npx skills add owner/repo        从技能市场仓库安装npx skills list owner/repo       # 查看可用技能
写完想校验?官方有验证器:
pip install skills-refagentskills validate path/to/my-skill

八、别搞混:SKILL.md vs AGENTS.md vs MCP

这是问得最多的一组对比,一张表说清:
一个实用的记忆法:
AGENTS.md 是给新同事的项目交接文档
SKILL.md 是发给新同事的标准作业程序(SOP)手册,一页一个 SOP,随手翻
MCP 是办公室的门禁和工位系统,让智能体够得着外面
三者互补不冲突:项目规范写 AGENTS.md,可复用流程做成 Skill,外部系统接 MCP。

九、安全提醒:Skill 是智能体会照做的指令

这一点官方反复强调,值得单独一节:
Skill 本质上是"智能体将会遵照执行的指令",所以一个恶意技能可以让智能体执行与表面用途不符的工具调用、代码执行,甚至数据外泄。
✅ 只装可信来源:自己写的,或官方发布的
⚠️ 用第三方技能前逐文件审计:SKILL.md、scripts、references 全看一遍,警惕异常的网络请求、文件访问模式
⚠️ 拉取外部 URL 的技能风险尤其高——外部内容可能被投毒,而且今天可信的依赖明天可能变质
把装 Skill当作装软件对待,生产环境里尤其如此
这和上次说 Hermes 的 prompt 注入扫描是同一个问题的两面:给智能体注入的每一份文本,既是能力,也是攻击面。

十、动手:写你的第一个 Skill

十分钟剩最后三分钟,抄这个模板就能开工:
mkdir -p .claude/skills/commit-message-writer
# .claude/skills/commit-message-writer/SKILL.md---name: commit-message-writerdescription: Generates conventional commit messages from staged git  changes. Use when the user asks to write a commit message, commit  staged files, or mentions "commit".---# Commit Message Writer## Instructions1. 运行 `git diff --staged --stat` 和 `git diff --staged` 查看变更2. 判断变更类型:feat / fix / refactor / docs / chore3. 第一行 ≤50 字符,用祈使句,不加句号4. 正文空一行后写"为什么改",不罗列"改了什么"(diff 自己会说话)## Guidelines- 变更跨多个不相关主题时,建议拆分提交,而不是写一条大杂烩- 只涉及一个文件的小改动,写单行信息即可
写完用一个真实任务试一遍——别用测试场景测,用真实工作测,观察智能体哪里犹豫了,回头改 description 或正文。这个迭代循环本身就是写好 Skill 的全部秘密。

写在最后

AGENTS.md、SKILL.md、SOUL.md——2026 年的 Agent 生态,正在用最朴素的格式(Markdown + YAML)解决最复杂的问题(让 AI 稳定地、可复用地替你干活)。没有黑魔法,就是把"教人做事"的老手艺平移给了机器: 说清楚它是什么 → 说清楚什么时候用它 → 说清楚怎么一步步做 → 细节按需给。

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料