文章目录引言为什么该重视 Agent Skill一、先搞清楚Skill 到底解决什么问题1.1 传统用法的三大痛点1.2 一句话理解 Skill1.3 Skill 相比其他方案的定位1.4 什么时候值得做成 Skill二、四个核心设计原则决定 Skill 上限的关键2.1 渐进式披露别一股脑塞东西2.2 把上下文当公共资源少一句是一句2.3 按任务脆弱性调节自由度2.4 记住读者是模型不是人三、五种 Skill 结构模式先选结构再写内容3.1 模式 A极简指导型3.2 模式 B示例模板型3.3 模式 C工具脚本型3.4 模式 D知识库型3.5 模式 E完整工作流型四、SKILL.md一个 Skill 的「心脏」4.1 推荐的文件结构4.2 Frontmattername 和 description 写法4.3 正文三种常用结构4.4 代码示例的硬性要求五、附加文件references、scripts、assets 怎么设计5.1 目录总览与角色分工5.2 references/写给模型看的「长文档」5.3 scripts/给模型用的 CLI 工具5.4 assets/模板和资源文件六、脚本开发让 Skill 真正「有手有脚」6.1 一个好脚本应该长什么样6.2 常见的错误处理模式6.3 CLI 入口推荐写法七、从 0 到 1六步创建你的第一个 SkillStep 1先把场景说清楚Step 2根据场景选结构模式Step 3写好 description这一步最关键Step 4搭出核心流程骨架Step 5补充 references / scripts / assetsStep 6用真问题反复测试和迭代八、发布前的质量检查别把半成品丢给业务8.1 Frontmatter 检查8.2 SKILL.md 检查8.3 附加文件检查8.4 功能与维护性自查九、常见反模式这些坑可以直接绕开结语把 Skill 当成「产品」而不是「提示词」引言为什么该重视 Agent Skill如果你最近在用 Claude、GPT 这类助手做事大概率踩过这些坑每次对话都要重新讲规则、项目里写了一堆自定义指令却没法复用、各种长 Prompt 到处复制粘贴时间久了谁也不记得最新版本是哪份。接下来我们将探讨如何用「Agent Skill」把这些零散的 Prompt 和经验收拢成一套可复用、可维护、能上线跑业务的专业能力包。它不是再教你写一段牛逼的提示词而是教你设计一个「专业技能模块」能自动触发、按需加载文档、调用脚本真正接到业务里去跑。一、先搞清楚Skill 到底解决什么问题1.1 传统用法的三大痛点在没有 Skill 之前大部分人的用法是这样的靠记忆每次跟模型说「你现在扮演 XXX 专家要遵守以下规则……」一长串废话来回贴。靠项目指令在某个项目里写一大段自定义指令但换个项目就全没了。靠复制粘贴整理一堆「万能 Prompt」需要的时候翻记录、粘过去用。对应的问题也很直观重复劳动同样的话反复讲心累。容易漏今天版本跟昨天不一样谁也不知道哪句才算最新规范。难维护一堆长 Prompt 四处散落想改统一规则非常困难。1.2 一句话理解 SkillSkill 是一个可复用的知识包让 Claude 在任何地方、任何时候自动触发某种专业能力。翻译成人话就是你把一套专业能力流程、规范、脚本、模板封装成一个模块模型在遇到相关需求时可以自动加载用你预先设计好的方法来处理问题而不是临场自由发挥。1.3 Skill 相比其他方案的定位我们把Skill 和 MCP、项目指令、系统提示做了一个对比能力维度SkillMCP项目指令系统提示跨对话复用支持支持不支持不支持自动触发支持不支持不支持支持能否执行代码支持支持不支持不支持是否渐进加载信息支持不支持不支持不支持核心定位专业技能与业务流程接外部系统 / 工具当前项目的上下文人设与基础行为规则一句总结MCP 更像「接外部工具的接口层」Skill 更像「带流程和示例的专业应用层」。1.4 什么时候值得做成 Skill适合做 Skill 的场景有几个共同特点经常反复做比如固定格式的报告、代码审查流程、公众号推文模板。有领域门槛比如专利解读、合同风险识别、财报分析。有明确流程多步骤、需要判断分支而不是简单问答。涉及工具或脚本需要跑脚本、处理文件、调接口。不适合做 Skill 的场景也很清楚一次性的需求。简单事实查询天气、汇率这种。严重依赖实时数据且更适合直接用 MCP。简单格式转换如「帮我转成表格」这类。二、四个核心设计原则决定 Skill 上限的关键设计高质量的 Skill 需要遵循四个核心原则。这些原则源自 Anthropic 官方最佳实践能够确保 Skill 既高效又易用。2.1 渐进式披露别一股脑塞东西核心思路把信息分层用「目录思维」组织 Skill。把 Skill 里要写的内容分成三层Level 1元信息永远加载name技能唯一标识。description干什么、在什么情况下触发。大约 100 词决定「是否触发」这个 Skill。Level 2SKILL.md 正文触发时加载核心工作流程。关键代码示例。各种参考文件的导航。建议控制在 500 行以内少于 5000 词。Level 3附加资源按需加载references/详细文档。scripts/可执行脚本。assets/模板、示例文件等。这里理论上没有上限但要通过导航让模型按需读取。实践上的关键动作是两点SKILL.md 只写「主干流程」细节拆到 references/。对互斥内容比如「Windows 方案」和「macOS 方案」必须拆开文件避免无脑全塞。2.2 把上下文当公共资源少一句是一句第二个原则很简单上下文是大家抢着用的资源每个 token 都要问一句「值吗」几个自查问题这段话 Claude 本来是不是就知道这段解释是不是业务无关、属于教科书知识这段是否可以换成一个直接可跑的例子这几十个字值不值得占用上下文例如 反对这种长篇背景解释 PDF 是什么PDFPortableDocumentFormat便携式文档格式是一种用于呈现文档的文件格式它独立于应用程序软件、硬件和操作系统...而更推荐直接给一个可用示例frompypdfimportPdfReader readerPdfReader(document.pdf)forpageinreader.pages:textpage.extract_text()print(text)这就是典型的「用例代替废话」。2.3 按任务脆弱性调节自由度第三个原则是窄桥要装护栏平地就给自由发挥。高自由度像前端设计方向这类创意任务只给审美方向和原则别把模型绑死。中等自由度有推荐做法但允许变通的比如代码重构建议给流程框架和可调参数。低自由度一旦出错代价很大批量删库、报税报表、法律文本生成就要写严格步骤和具体命令。举两个例子前端风格 Skill 是「高自由度」大胆选择视觉风格PDF 表单脚本 Skill 是「低自由度」按指定脚本和步骤执行。# 高自由度示例frontend-designChoosea BOLD aesthetic direction:brutally minimal,maximalist chaos,retro-futuristic,organic/natural,luxury/refined...# 低自由度示例pdf forms1.Run:python scripts/extract_form_fields.py input.pdf2.Reviewthe extracted fields3.Run:python scripts/fill_form.py input.pdf output.pdf--data fields.json2.4 记住读者是模型不是人最后一个原则你在写的不是教程而是「给 Claude 的操作手册」。写作要点很直白多用祈使句Run、Check、If…then…。假设模型有基础技能只补它不知道的业务规则和流程。重点写「什么时候、做什么」而不是大段「你能做什么」的功能宣言。代码示例要能复制就跑而不是到处 TODO。三、五种 Skill 结构模式先选结构再写内容五种常见的 Skill 目录结构可以把它当成「设计前的选型表」。3.1 模式 A极简指导型目录结构大概是这样my-skill/ ├── SKILL.md # 全部内容 └── LICENSE.txt # 可选适合场景风格指南品牌语气、写作规范。思维框架、方法论。简单工具的用法。SKILL.md 推荐行数50–200 行。3.2 模式 B示例模板型典型结构my-skill/ ├── SKILL.md # 导航 选择逻辑 ├── examples/ # 或 templates/ │ ├── template-a.md │ ├── template-b.md │ └── template-c.md └── LICENSE.txt使用场景多种模板选择比如不同类型的邮件 / 报告。格式规范。各种固定文本模版。SKILL.md 一般控制在 50–150 行左右。3.3 模式 C工具脚本型结构大概是这样my-skill/ ├── SKILL.md # 工作流程 调用脚本 ├── scripts/ # 可执行脚本 │ ├── main_tool.py │ └── helper.py ├── references/ # 可选详细文档 │ └── advanced.md └── LICENSE.txt适用需要执行代码的任务。稍复杂的数据处理流程。与外部工具结合比如下载器、测试工具。SKILL.md 行数建议 100–300 行。3.4 模式 D知识库型目录大致如下my-skill/ ├── SKILL.md # 极简导航100 行 ├── rules/ # 或 references/ │ ├── topic-1.md │ ├── topic-2.md │ └── ... ├── assets/ # 可选示例代码 │ └── example.tsx └── LICENSE.txt适合用来承载某个技术框架完整指南。知识点众多且相对独立的主题。需要较多参考文档的场景。SKILL.md 保持在 30–100 行核心作用是「导航」。3.5 模式 E完整工作流型这是最重型的一种目录大致长这样my-skill/ ├── SKILL.md # 核心流程 Quick Start ├── references/ │ ├── forms.md # 条件加载特定场景 │ ├── advanced.md # 条件加载高级用法 │ └── api.md # 条件加载API 参考 ├── scripts/ │ ├── process.py │ ├── validate.py │ └── export.py ├── assets/ │ └── template.docx └── LICENSE.txt适合专业领域的一整套解决方案PDF、Office 套件处理等。多场景、多功能需要工作流的。希望直接放到生产环境里用的场景。SKILL.md 一般在 200–500 行之间。四、SKILL.md一个 Skill 的「心脏」这一章可以直接当你的写作模板用。4.1 推荐的文件结构一个通用模板大致是这样*** name: skill-name description: | [做什么的一句话描述]。 [触发条件/场景列表]。 [可选触发关键词] *** # [技能名称] # Overview / 概述 [1-2 段话说明这个技能做什么] # When to Use / 何时使用 [列出触发场景] # Quick Start / 快速开始 [最简单的使用示例] # Workflow / 工作流程 [核心步骤或决策树] # Reference Files / 参考文件 - [file1.md](references/file1.md) - 用途说明 # Error Handling / 错误处理 [常见问题和解决方案]自上而下分别解决是谁、干嘛的、什么时候用、怎么快速上手、完整流程是什么、要看细节去哪看、出错怎么办。4.2 Frontmattername 和 description 写法name 规则全小写。单词用短横线连接。不超过 64 字符。不能包含anthropic、claude这些品牌词。不要用大写和下划线。例如youtube-transcript✅ip-patent-analyzer✅IP_Patent_Analyzer❌claude-helper❌description 是触发的核心建议用这样的「黄金公式」做什么 何时触发/使用场景 可选触发关键词好的例子长这样工具类描述下载 YouTube 字幕的能力并明确「当用户提供 YouTube URL 或说要获取字幕/转写时触发」。文档处理类概括 PDF 提取、合并、表单处理能力并加上一句「当需要大规模处理 PDF 文档时使用」。支持多语言触发词开头一句中文功能说明下面一句英文再列一个「触发方式下载图片、找视频、download media…」。反例也很好记太模糊A helpful tool for working with documents.只说干嘛不说什么时候用。啰嗦地科普 PDF 是什么却没说清它在 Skill 里干嘛。# 示例1工具类 description:|DownloadYouTubevideo transcripts when userprovidesaYouTubeURL or askstodownload/get/fetch a transcript fromYouTube.Alsouse when user wantstotranscribeor get captions/subtitles from aYouTubevideo.# 示例2文档处理类 description:|ComprehensivePDF manipulation toolkitforextracting text and tables,creatingnewPDFs,merging/splitting documents,and handlingforms.WhenClaudeneedstofillin a PDF form or programmatically process,generate,or analyze PDF documents at scale.# 示例3双语触发词 description:|智能媒体下载器。根据用户描述自动搜索和下载图片、视频片段支持视频自动剪辑。Smartmediadownloader.Automaticallysearch and download images/video clips based on user description,withauto-trimming support.触发方式Triggers:下载图片,找视频,download media,download images反面示例 # ❌ 太模糊 description:Ahelpful toolforworkingwithdocuments.# ❌ 只说做什么没说何时用 description:Extracttext fromPDFsand createnewPDF documents.# ❌ 太长太啰嗦 description:|Thisis a comprehensive skill that helps users workwithPDF documents.PDF standsforPortableDocumentFormatand is widely usedforsharingdocuments.Thisskill can help you extract text,merge documents,split documents,rotate pages,add watermarks,and much more...4.3 正文三种常用结构正文主要有三种模式可以按任务类型选决策树型适合多分支、多场景。先写「Workflow Decision Tree」再为每个场景开子章节写步骤。## Workflow Decision Tree User task → Is it scenario A?├─ Yes → Use Method1(see section below)└─ No → Is it scenario B?├─ Yes → Use Method2└─ No → Use Method3(default)## Method1:[Scenario A][详细步骤]## Method2:[Scenario B][详细步骤]顺序流程型适合线性流程比如「检查前置条件 → 准备输入 → 执行任务 → 后处理」。## Workflow ### Step1:Check Prerequisites[说明命令]### Step2:Prepare Input[说明命令]### Step3:Execute Main Task[说明命令]### Step4:Post-processing[说明命令]工具箱型先给 Quick Start再按功能拆章节每个功能里有基础用法和高级用法高级部分跳到 references。## Quick Start[最简示例]## Feature1:[功能名]### Basic Usage[代码示例]### Advanced Options See[advanced.md](references/advanced.md)## Feature2:[功能名][同上结构]4.4 代码示例的硬性要求一条标准示例要能直接复制执行不需要用户「自己补完」。正例直接给好文件名、循环、打印逻辑用户粘贴运行就能看到结果。反例留空字符串、写 TODO、留注释让用户补逻辑这会严重影响模型学习用法。五、附加文件references、scripts、assets 怎么设计如果说 SKILL.md 是「大纲和说明书」那附加文件就是「补充教材、工具箱和模板库」。5.1 目录总览与角色分工一个典型 Skill 的目录会长成这样skill-name/ │ ├── SKILL.md # [必需] 核心文件 │ ├── references/ # [可选] 详细参考文档 │ ├── getting-started.md # 入门指南 │ ├── advanced.md # 高级用法 │ ├── api.md # API 参考 │ └── troubleshooting.md # 问题排查 │ ├── scripts/ # [可选] 可执行脚本 │ ├── main.py # 主工具脚本 │ ├── utils.py # 工具函数 │ └── validate.py # 验证脚本 │ ├── assets/ # [可选] 资源文件 │ ├── templates/ # 模板文件 │ ├── examples/ # 示例文件 │ └── fonts/ # 字体等资源 │ └── LICENSE.txt # [推荐] 许可证可以这样记references/模型要读完再用的内容。scripts/模型直接调用的黑盒工具。assets/输出用素材模型只会拿来复制或修改。examples/示例内容帮助模型学格式。5.2 references/写给模型看的「长文档」设计原则每个文件自包含不依赖其它 reference 文件。文件长度控制在 100–500 行超过就拆。超过 100 行最好加一个小目录TOC。推荐结构大致如下*** name: topic-name description: Brief description of this reference metadata: tags: tag1, tag2, tag3 *** # [主题名称] # Overview [概述] # [Section 1] [内容 代码示例] # Common Patterns [常用模式、最佳实践] # Troubleshooting [常见问题与排查]5.3 scripts/给模型用的 CLI 工具这里的原则有几条很重要当黑盒用通过--help就能知道用途和参数。单一职责一个脚本只做一件事。幂等同样输入多次执行结果一样。清晰输出明确的「成功 / 失败」信息。错误处理错误信息要能指导后续操作。Python 脚本模板 包含说明、用法示例、参数解析、异常处理、退出码等。可以直接拿来改#!/usr/bin/env python3 Brief description of what this script does. Usage: python script.py input [options] Examples: python script.py input.pdf python script.py input.pdf --output result.pdf importargparseimportsysdefmain():parserargparse.ArgumentParser(descriptionBrief description)parser.add_argument(input,helpInput file path)parser.add_argument(-o,--output,helpOutput file path)argsparser.parse_args()try:resultprocess(args.input,args.output)print(f✓ Success:{result})sys.exit(0)exceptExceptionase:print(f✗ Error:{e},filesys.stderr)sys.exit(1)if__name____main__:main()后面配合 argparse、try/except、sys.exit(0/1)等完整模式。5.4 assets/模板和资源文件assets/ 里的内容模型一般不会读而是当作「素材」来用各种文档模板.docx、.pptx、.html。图片资源logo、图标。字体、配置模版等。Skill 的作用是指挥模型拷贝或改这些文件而不是让模型把它们读到上下文里。六、脚本开发让 Skill 真正「有手有脚」如果你的 Skill 会跑脚本这一章基本就是一份脚本开发标准。6.1 一个好脚本应该长什么样六个特点自描述--help足够详细。单一职责一个脚本就做一件清晰的事情。幂等多次执行不会产生奇怪的副作用。输出清晰成功用 ✓失败用 ✗不要一堆难懂的日志。出错友好错误信息里最好带解决建议。对模型透明模型可以当工具直接调用无需理解内部实现。6.2 常见的错误处理模式3个小模式前置检查比如先检查 ffmpeg、yt-dlp 是否安装不满足就列出缺什么并退出。操作前确认对于可能耗时或有风险的操作用Proceed? (y/n)让用户确认。分步骤反馈处理一批 items 时按[i/total]打印进度失败的给出错误原因。这套方式对人类用户也友好。6.3 CLI 入口推荐写法推荐用argparse 子命令的方式搭结构比如status、process两个子命令对应不同功能。这样 Skill 在调用脚本时也更清晰不需要记一堆参数顺序。七、从 0 到 1六步创建你的第一个 Skill这部分可以直接当你的工作流程用。Step 1先把场景说清楚先别写代码先写清楚「Skill 要解决什么真实问题」。可以用这些问题引导自己这个 Skill 要解决的具体问题是什么用户会用什么话来触发它有哪些典型场景每个场景的输入输出是什么比如专利场景做了示例列了「专利检索」「专利分析」「侵权判断」三个具体场景每个都写了用户怎么说、输入和输出。你可以照抄这个格式替换成自己业务。## 场景分析 ### 场景1:专利检索 用户说:帮我检索关于XX技术的专利输入:技术关键词 输出:专利列表摘要 ### 场景2:专利分析 用户说:分析这份专利的权利要求输入:专利号或PDF 输出:权利要求解读保护范围 ### 场景3:侵权判断 用户说:判断这个产品是否侵犯专利输入:产品描述专利号 输出:侵权分析报告Step 2根据场景选结构模式对照五种结构模式选一个最贴合的顺便把理由写下来。例如专利 Skill 选择「模式 E 完整工作流型」理由是有多个功能检索 / 分析 / 判断。需要跑接口调用脚本或 MCP。部分场景需要法律条款等长文档支撑。这一步相当于给后续目录画了个线框图。Step 3写好 description这一步最关键description 决定 Skill 能不能被正确触发要格外上心。可以用这个模板开头description: | [一句话说明核心能力]。 Use when... / When user...列出 1-3 个场景 [可选触发关键词列表]写完后用这几个问题自查有没有说清楚「做什么」触发场景有没有具体到「用户会说的原话」有没有把常见关键词写进去字数有没有超过 1024 字Step 4搭出核心流程骨架先把框架搭好再往里填内容不要一上来就写长篇说明。推荐骨架# [Skill 名字] # Overview [简要说明] # When to Use [把 Step 1 里的场景复制过来整理] # Quick Start [最简单的一次调用示例] # Workflow [流程图 / 决策树 / 步骤列表] # [具体功能章节] [按功能拆详细说明] # Reference Files [列出 references/ 里的文件及用途]Step 5补充 references / scripts / assets根据前面设计的模式把长文、脚本、模板拆出去长文档 → references/。工具脚本 → scripts/。模板资源 → assets/。记得遵守前面讲的长度和结构原则。Step 6用真问题反复测试和迭代最后一步是不断打磨用不同说法尝试触发 Skill看是否精准。跑一遍每个场景的完整流程。故意制造错误确认报错和引导是否友好。把遇到的问题和修改记录下来比如发现少写了「检索」这个关键词就加回 description 里。一个「迭代记录」示例建议你也在自己项目里保留一份简单的迭代日志方便回顾。## 迭代记录 ### 问题1:Description 触发不准确 现象:用户说检索专利时没有触发 解决:在 description 中添加检索、搜索关键词 ### 问题2:流程中途中断 现象:Claude 执行到第3步就停止了 解决:在 SKILL.md 中添加明确的步骤编号和继续下一步提示 ### 问题3:脚本报错信息不清晰 现象:用户不知道如何解决报错 解决:改进脚本的错误信息添加解决建议八、发布前的质量检查别把半成品丢给业务8.1 Frontmatter 检查name 符合命名规则小写、短横线、不含品牌词、长度合规。description 清楚描述「做什么」和「何时触发」。字数不超过 1024 字符。8.2 SKILL.md 检查有 Quick Start 或最小可用示例。有清晰的工作流程描述。示例代码能直接跑。所有引用的文件都真实存在。总行数不超过 500 行超过就拆。8.3 附加文件检查references/ 里的每个文件都是自包含的。scripts/ 中的脚本都带--help。脚本都有基础错误处理。没有多余文件README、CHANGELOG、CONTRIBUTING 等。8.4 功能与维护性自查从四个角度做一次自我评估内容精简度有没有废话能不能用例子替代长篇解释触发准确度description 是否覆盖用户常用说法会不会误触执行可靠度流程是否无歧义脚本和示例是否都跑过维护友好度结构是否清晰后续扩展新功能是否容易九、常见反模式这些坑可以直接绕开下面列了一些典型「反例」非常值得收藏。描述太模糊只说「用于处理文档」完全看不出具体能力和触发条件。一次性塞太多内容把所有细节都堆在 SKILL.md 里不拆到 references。不写触发条件只说「能做什么」不说「什么时候用」。代码示例不可执行充满占位符和 TODO。脚本没帮助信息直接用sys.argv读参数没有 argparse也没有--help。创建一堆没用的说明文件README、INSTALLATION、CHANGELOG 等反而把目录搞乱。# ❌ 差 skill/├── SKILL.md ├── README.md # ❌ 不需要 ├── INSTALLATION.md # ❌ 不需要 ├── CHANGELOG.md # ❌ 不需要 └── CONTRIBUTING.md # ❌ 不需要 # ✅ 好 skill/├── SKILL.md ├── references/│ └── advanced.md └── scripts/└── process.py结语把 Skill 当成「产品」而不是「提示词」一个好的 Agent Skill本质上是一个可维护、可扩展的「小产品」而不是一段高级 Prompt。可以用本文的思路落地一整套实践方式先用六步法把业务场景、流程、脚本整理出来。按五种结构模式给 Skill 做「架构设计」。严格按四大原则写 SKILL.md 和附加文件。再用那份 Checklist 做一次完整体检然后再推给业务团队试用。只要你肯花一两天认真做一两个高质量 Skill你会发现后面很多复杂的需求不用从头想 Prompt 了直接往这个 Skill 上加场景就能稳定复用。这才是「从玩工具」到「做产品」的真正分界线。