1. 从提示词工程到技能封装Agent Skill 到底在解决什么问题如果你最近在折腾 Claude、Claude Code 或者各类智能体框架大概率会频繁刷到 Agent Skill 这个词。很多人第一反应是这不就是换个说法的提示词模板吗我一开始也这么想直到真正把一个重复性任务拆成 Skill 跑通之后才发现它和传统提示词根本不是一个层级的东西。先说结论Agent Skill 是把一套可复用的工作方法封装成智能体能自动识别、按需加载、稳定执行的能力单元。它的核心载体通常是一个叫SKILL.md的 Markdown 文件配合若干辅助脚本、模板、参考资料组成一个目录。智能体在运行时会根据当前任务判断我需不需要调用某个技能需要就加载对应 Skill 的说明和资源然后照着执行。这解决了一个非常现实的痛点。以前我们用提示词是把所有规则、格式、步骤一股脑塞进对话里上下文越堆越长模型还容易选择性失忆。而 Skill 的思路是按需加载、渐进披露平时只暴露一句简短描述真正触发时才把完整流程读进来。这就像公司里的岗位手册——你不需要背下全公司所有流程只要知道遇到报销找财务手册、遇到部署找运维手册需要时再翻。从关键词热度也能看出来大家关心的其实是很具体的东西SKILL.md怎么写、Markdown 语法怎么用、Claude Code 怎么装、怎么把网页保存成 Markdown、怎么用 Agent 做一个 Rational Rose 建模的 Skill。这些问题的背后是同一件事——如何把零散的操作经验沉淀成智能体可以稳定复现的技能。这篇文章我会从零讲清楚 Agent Skill 的结构、SKILL.md的写法、Markdown 在其中的关键作用、Claude Code 环境下的落地方式以及我在实操中踩过的坑。不管你是刚听说这个概念的新手还是已经写过几个 Skill 想优化的人都能找到能直接抄作业的部分。2. 拆开一个 SkillSKILL.md 的骨架与渐进披露机制2.1 为什么是 Markdown而不是 JSON 或 YAML很多人第一反应是用结构化配置来定义技能但主流方案偏偏选了 Markdown。原因其实很朴素Skill 的主体是给模型看的自然语言指令而不是给程序解析的配置。JSON 适合机器读但写起流程说明、注意事项、示例来极其别扭Markdown 既能写标题分层、列表、表格、代码块又能保持纯文本的可读性人和模型都能顺畅理解。更关键的是 Markdown 的层级结构天然适合渐进披露。你可以把最核心的触发条件放在文件顶部把详细步骤放中间把边缘情况的处理放最后。模型加载时可以先读概要需要细节再往下看。这种分层可裁剪的特性是 JSON 那种扁平结构给不了的。提示Skill 目录里除了SKILL.md通常还会有scripts/、references/、assets/这类子目录。主文件负责说清楚怎么做脚本负责真正去执行参考资料负责需要时再查。不要把几百行脚本全塞进 Markdown那样反而拖慢加载。2.2 一个 SKILL.md 的最小可用结构下面是我实际在用的一个骨架你可以直接拿去改。注意 frontmatter 里的name和description是最重要的两个字段因为智能体就是靠这两项判断要不要用这个技能。--- name: web-to-markdown description: 将指定网页内容抓取并转换为结构化的 Markdown 文件保留标题层级、代码块和表格。当用户要求保存网页转成 markdown归档文章时使用。 --- # 网页转 Markdown 技能 ## 何时使用 - 用户提供 URL 并要求保存为 Markdown - 用户要求归档技术文档、博客文章 ## 执行步骤 1. 确认目标 URL 可访问 2. 抓取正文剔除导航、广告、页脚 3. 按原层级还原标题# / ## / ### 4. 代码块标注语言类型 5. 表格转为 Markdown 表格语法 6. 输出到指定路径默认 ./output/ ## 注意事项 - 图片默认保留原始链接不下载 - 遇到付费墙内容直接告知用户不要伪造这个结构看起来简单但每一块都有讲究。description写得好不好直接决定技能会不会被正确触发。我见过太多人把 description 写成一个很有用的工具结果模型根本不知道什么时候该用它。2.3 渐进披露别让模型一次吞下所有细节渐进披露progressive disclosure是 Skill 设计里最容易被忽略、却最影响效果的一环。核心思想是主文件只放决策所需和主干流程把大段参考资料、长脚本、边界案例拆到子文件里用链接或路径引用。举个实际例子。我做过一个生成 Rational Rose 风格 UML 图的 Skill如果把所有图形语法、每种关系的画法、几十个示例全写进SKILL.md文件轻松上千行模型每次加载都浪费上下文。我的做法是SKILL.md只写什么时候用、支持哪几类图、调用哪个脚本、输出格式references/uml-syntax.md放详细的语法规则scripts/render.py负责实际渲染assets/templates/放常用模板这样主文件保持在 100 行以内模型判断快、加载轻需要细节时再去读引用文件。实测下来触发准确率和执行稳定性都明显更好。3. 触发、加载、执行Skill 在智能体里是怎么跑起来的3.1 触发判断description 决定生死智能体拿到用户请求后第一步是我该不该用某个技能。这个判断几乎完全依赖description。所以写 description 有个实用原则用当用户……时使用的句式把典型触发场景列出来。对比一下两种写法写法示例效果模糊型description: 处理文档模型不知道何时用经常漏触发或误触发场景型description: 将网页保存为 Markdown。当用户要求保存网页归档文章转 markdown时使用触发准确边界清晰我踩过的坑是description 写得太宽泛结果模型在完全不相关的任务上也去加载这个技能白白消耗上下文。后来我把触发词收窄只在明确场景下才触发稳定性立刻上来了。3.2 加载按需读取而不是全量注入触发之后智能体会读取SKILL.md的正文。这里有个关键点加载是分层的。主文件先读如果流程里提到详见 references/xxx.md模型会在需要那一步时再去读。这就是为什么前面强调要把重内容拆出去。你可以把 Skill 想象成一个工具箱。SKILL.md是贴在箱子外面的标签和说明书目录scripts/是里面的电动工具references/是厚厚的手册。你干活时不会把整本手册背下来而是要用冲击钻了翻到第 12 页看怎么装钻头。3.3 执行脚本负责确定性模型负责判断Skill 执行时模型负责理解意图、选择路径、组织输出脚本负责确定性操作。比如格式转换、文件读写、调用外部命令这些交给脚本比让模型手算靠谱得多。一个典型的执行链路是这样的模型读取SKILL.md确认任务匹配按步骤调用scripts/convert.py传入参数脚本返回结果或错误模型根据结果决定下一步或向用户汇报注意脚本的输入输出要设计得对模型友好。比如错误信息要写清楚哪个参数错了、期望什么格式而不是抛一个裸的异常堆栈。模型看到清晰错误才能自我纠正。3.4 一个完整例子网页保存成 Markdown 的 Skill把前面几节串起来看一个端到端的例子。用户说帮我把这篇文章保存成 markdown。智能体扫描可用技能命中web-to-markdown因为 description 里有保存网页转 markdown加载SKILL.md读到执行步骤调用scripts/fetch_and_convert.py --url URL --out ./output/脚本抓取、清洗、转换输出.md文件模型检查输出若发现代码块没标语言按SKILL.md里的规则补上向用户报告保存路径整个过程里模型没有即兴发挥去猜怎么转换而是严格照着 Skill 定义的流程走。这就是 Skill 相对裸提示词的最大优势——可复现、可维护、可迭代。4. Markdown 在 Skill 里的硬功夫语法细节决定成败4.1 换行、空行与列表缩进这些小事Markdown 看着简单但在 Skill 场景里语法细节直接决定输出质量。最常见的坑是换行。很多人以为回车就是换行结果渲染出来全挤在一行。标准做法是段落之间空一行行内强制换行用行尾两个空格或反斜杠。列表缩进也是重灾区。嵌套列表必须用一致的缩进通常 2 或 4 个空格混用 Tab 和空格会导致层级错乱。我在 Skill 里会明确写一句嵌套列表统一使用 2 个空格缩进避免模型自由发挥。4.2 代码块、表格与 callout代码块一定要标语言类型否则高亮和后续处理都会出问题def convert(html: str) - str: # 转换逻辑 return markdown_text表格在 Skill 里常用于参数说明和对照写法要规范表头分隔行不能省参数类型说明--urlstring目标网页地址--outstring输出目录默认./output/GitHub 风格的 callout提示块在 Skill 文档里很好用能突出关键信息提示callout 语法在不同渲染器里支持度不一写 Skill 时优先用普通引用块兼容性最好。4.3 数学公式行内与多行技术类 Skill 经常要处理公式。行内公式用单美元符号包裹独立公式用双美元符号。多行公式比如大括号方程组需要用aligned环境$$ \begin{aligned} f(x) ax^2 bx c \ f(x) 2ax b \end{aligned} $$这里有个实操经验不同 Markdown 渲染器对公式的支持差异很大。如果你的 Skill 输出要跨平台使用最好在SKILL.md里注明公式使用标准 LaTeX 语法渲染依赖目标平台。我遇到过在某个编辑器里公式正常、换到另一个工具就变成纯文本的情况排查半天才发现是渲染器不支持。4.4 图片路径相对还是绝对Skill 里引用图片路径写法很关键。相对路径./assets/diagram.png可移植性好但依赖工作目录绝对路径稳定但换机器就失效。我的建议是Skill 内部资源用相对路径用户产出物用绝对路径或明确说明。同时在SKILL.md里写清楚图片默认保留原始链接不自动下载避免模型擅自去抓图。5. 在 Claude Code 里落地环境、安装与常见报错5.1 安装与环境准备Claude Code 是很多人接触 Agent Skill 的入口。安装方式因平台而异核心是确保运行环境完整。Windows 上常见的一个报错是提示需要启用虚拟机平台相关组件这通常和底层运行依赖有关按提示在系统设置里开启对应功能即可。Linux 和 macOS 上相对顺畅用包管理器或官方脚本安装后验证命令能正常返回版本号就算成功。安装完成后第一件事是确认它能正常调用终端命令、能读取本地文件。这两项是 Skill 执行的基础能力如果这两步不通后面写再多 Skill 也跑不起来。5.2 常见报错与排查思路我把高频问题整理成一张表方便对照排查报错关键词可能原因处理方向native binary not installed安装后置脚本未执行重新执行安装检查网络与权限connection dropped网络中断或服务端限流检查网络稳定性稍后重试organization disabled subscription账号权限或订阅状态问题核对账号状态与可用范围桌面版安装失败系统组件缺失或权限不足检查系统依赖以管理员权限重试排查这类问题的通用思路是先看报错原文定位是环境问题、权限问题还是网络问题再对症处理。不要一上来就重装很多时候只是某个组件没启用。5.3 接入本地模型与自定义配置有些场景下你会想让 Claude Code 调用本地模型或自定义服务。这通常通过配置文件指定服务地址和模型名来实现。配置时要注意接口协议要匹配模型名要写对超时时间要留够。我见过因为超时设太短、大任务直接断掉的情况把超时调大之后就稳定了。另外VS Code 里集成 Claude Code 也是高频需求。装好扩展后关键是让工作区能正确识别 Skill 目录。我的做法是把 Skill 放在项目根目录下的固定文件夹里并在配置中显式声明路径避免找不到技能的问题。6. 从零写一个能用的 Skill我的实操流程与避坑清单6.1 先想清楚这个技能解决什么重复劳动写 Skill 之前先问自己这个任务我是不是要反复做步骤是不是相对固定如果只是一次性任务写 Skill 反而浪费时间。真正值得封装的是那些每周都要做、每次步骤差不多、但手动做很烦的事。比如把网页保存成 Markdown把 Markdown 表格转成 Excel生成固定格式的 UML 图这些都是典型的可封装场景。判断标准很简单如果你能写出稳定的步骤清单它就适合做成 Skill。6.2 写 description 的三个实用技巧第一用动词开头描述动作比如转换抓取生成而不是关于……的工具。第二列出触发短语把用户可能说的原话写进去。第三划清边界明确不做什么避免误触发。我一般会写两版 description一版给自己看逻辑一版精简后放进 frontmatter。精简版控制在两三句话既说清用途又列出触发场景。6.3 把重内容拆出去主文件保持轻量前面反复强调的渐进披露落地时就是一条规则SKILL.md主文件尽量控制在 150 行以内。超出的内容按性质拆分——语法规则进references/可执行逻辑进scripts/模板进assets/。主文件只保留何时用、主干步骤、关键注意事项、引用路径。这样做的好处一是加载快二是维护清晰。改一个语法细节不用动主流程改流程也不用翻几百行参考资料。6.4 测试与迭代别指望一次写对Skill 写完必须实测。我的测试方法是用三种不同措辞去触发它看是否都能正确命中再故意给一个边界输入看它会不会乱来。比如网页转 Markdown 的 Skill我会测正常文章、带大量代码的技术文、以及一个打不开的链接。实测中发现的典型问题包括触发词太窄导致漏触发、步骤描述有歧义导致模型跳步、错误处理缺失导致脚本报错后模型不知所措。每发现一个问题就回到SKILL.md补一句明确说明。迭代三五轮之后技能才会真正稳定。提示把每次踩的坑记在一个CHANGELOG.md里下次改 Skill 时能快速回忆当初为什么这么写。这个习惯帮我省了大量重复排查时间。7. 几个真实场景的 Skill 设计思路7.1 网页归档类 Skill 的取舍网页转 Markdown 看似简单实际取舍很多正文怎么识别、图片下不下载、代码块语言怎么判断、付费内容怎么处理。我的原则是能确定的事交给脚本判断不了的事交给模型并明确告知用户。比如正文识别用成熟算法图片默认保留链接遇到付费墙直接说明而不是硬凑内容。7.2 文档转换类 Skill 的稳定性设计Markdown 转 Word、表格转 Excel 这类需求核心是格式映射要明确。我会在 Skill 里列一张映射表写清楚Markdown 的 ## 对应 Word 的几级标题表格如何转成 Excel 的行列。映射写死了输出才稳定。否则每次转换结果都不一样根本没法用。7.3 建模与图形类 Skill 的边界用 Agent 做 Rational Rose 风格的 UML 建模是个很有意思的场景。这类 Skill 的关键是把图形语法和渲染逻辑分离SKILL.md说清楚支持哪几类图、输入什么、输出什么具体渲染交给脚本。同时要明确边界——比如只支持类图、时序图、用例图不支持复杂布局微调避免用户期望过高。8. 我踩过的坑与几条实在建议第一个坑是description 写太泛。早期我写处理各种文档任务结果模型在写代码时也去加载这个技能纯属浪费。后来收窄到具体动作和场景问题消失。第二个坑是把所有内容塞进主文件。一个 Skill 写到八百多行加载慢、改起来痛苦。拆成主文件加引用之后维护成本直线下降。第三个坑是忽略错误处理。脚本报错后模型一脸懵只能干等用户回复。后来我在每个脚本里都加了清晰的错误信息并在SKILL.md里写明遇到 X 错误时提示用户 Y整个流程才闭环。第四个坑是跨平台渲染差异。公式、callout、表格在不同工具里表现不一。我的应对是优先用兼容性最好的语法必要时在文档里注明依赖。最后分享一个实用习惯给每个 Skill 配一个最小可用的示例。放在assets/examples/里既方便自己测试也方便别人理解。一个能跑通的例子胜过一千字说明。Skill 这东西写十个不如把一个打磨到稳定好用质量永远比数量重要。