尧图网页设计 
1. 从skills这个热词说起它到底是什么最近几个月不管是在技术社区还是各种开发者群里skills这个词出现的频率高得离谱。很多人第一次看到Claude Skills或者Agent Skills的时候第一反应是这不就是个插件吗第二反应是跟Function Calling有什么区别。我一开始也是这么想的直到真正动手写了几个SKILL.md、把它接到实际工作流里跑了一遍才发现这东西的设计思路跟传统的工具调用完全不是一回事。先把概念说清楚。Agent Skills本质上是一种用自然语言描述、以文件形式组织的能力包。它的核心载体是一个叫SKILL.md的Markdown文件里面用结构化的方式写清楚这个技能是干什么的、什么时候该用它、用的时候需要哪些输入、执行步骤是什么、输出长什么样。模型在运行的时候会根据当前任务去匹配这些技能描述然后按照SKILL.md里写的流程去执行。你可以把它理解成给AI写的一份操作手册而不是一段需要编译的代码。它解决的核心问题是让非程序员也能给AI扩展能力同时让能力的复用和版本管理变得像管理文档一样简单。以前你要给模型加个新功能得写代码、定义schema、处理参数校验、调试返回值一套下来没个半天搞不定。现在你只要写一个Markdown文件把步骤讲清楚模型就能照着做。这个门槛的降低是数量级的。适合谁来学三类人最该关注。第一类是日常用Claude Code、Cursor这类工具做开发的工程师skills能让你的重复操作自动化第二类是做数据分析、数学建模、内容创作的知识工作者skills能把你的方法论固化下来反复用第三类是想把自己经验产品化的人一套好的skills就是一套可交付的方法论。哪怕你完全不懂编程只要能把自己的工作流程写清楚就能做出可用的skills。2. Skills的核心设计逻辑为什么是Markdown而不是代码2.1 用自然语言描述能力的底层考量传统工具调用Function Calling要求你把能力定义成严格的JSON Schema参数类型、必填项、枚举值都得写死。这套机制很严谨但有个致命问题它假设所有能力都能被精确地参数化。可现实中大量的任务是模糊的、需要判断的、步骤之间有依赖的。比如帮我审查这段代码的安全问题你没法用几个参数把这个需求描述清楚因为审查什么、按什么标准、发现问题的处理方式都是需要模型在执行过程中动态决定的。Skills的设计者显然想通了这一点。既然模型本身就能理解自然语言那为什么还要用代码去描述能力直接用自然语言写清楚遇到什么情况做什么事就行了。SKILL.md里可以写判断逻辑、可以写分支条件、可以写如果遇到X就参考Y文件这种引用关系。这种表达力是JSON Schema给不了的。我实测下来的感受是对于流程明确、步骤固定的任务skills的编写效率比写代码高5到10倍。一个中等复杂度的技能从构思到能用半小时以内。同样的功能用传统方式实现光调试参数传递就得花两小时。2.2 SKILL.md的文件结构拆解一个标准的SKILL.md通常包含这几个部分我按重要性排序说元信息区技能名称、一句话描述、适用场景标签。这部分决定了模型能不能在正确的时机想起你。描述写得越具体匹配越准。我见过太多人把描述写成处理数据结果模型永远想不起来用它。正确的写法是当用户需要清洗CSV中的重复行并按指定列去重时使用。触发条件明确写出什么情况下该激活这个技能。可以写关键词也可以写场景描述。这部分是给模型看的路由规则。执行步骤核心内容。用有序列表把每一步写清楚每步说明做什么、用什么工具、注意什么。步骤要具体到可执行不能写分析数据这种空话要写读取文件、检查列名、统计每列的空值率。输入输出规范说明需要用户提供什么、最终产出什么格式。这能避免模型自由发挥导致结果不可控。示例给一两个完整的输入输出样例。这是提升技能稳定性的最有效手段没有之一。提示SKILL.md的写法没有强制标准但有一个原则必须遵守——假设读你这份文件的人完全不了解背景。写得越自包含模型执行时越不容易跑偏。2.3 Skills与传统方案的本质差异维度传统Function CallingAgent Skills定义方式JSON Schema代码定义Markdown自然语言编写门槛需要编程能力会写文档即可灵活性参数固定难以处理模糊任务可写判断逻辑和分支复用方式代码包/库文件复制/目录共享调试难度需要看日志、断点直接读SKILL.md看逻辑版本管理Git管理代码Git管理文档diff更直观适用场景精确的API调用流程性、判断性任务这张表是我自己踩坑之后总结的。最关键的差异在最后一行Function Calling适合调一个接口拿一个结果Skills适合完成一件需要多步判断的事。搞混这两个定位用哪个都会别扭。3. 手把手写第一个SKILL.md从零到能用3.1 环境准备与目录结构不管你用的是Claude Code、还是其他支持skills的工具目录结构基本是通用的。我以最常见的组织方式来说skills/ ├── my-first-skill/ │ ├── SKILL.md # 核心定义文件 │ ├── examples/ # 示例输入输出 │ │ ├── input1.md │ │ └── output1.md │ └── resources/ # 技能用到的参考文件 │ └── template.md每个技能一个独立目录目录名用英文小写加连字符。SKILL.md放在根目录这是约定俗成的入口。examples和resources是可选的但强烈建议加上尤其是examples。如果你用的是Claude Codeskills通常放在项目根目录的.claude/skills/下或者用户级的~/.claude/skills/。项目级的技能只对当前项目生效用户级的全局可用。我的建议是通用的、跨项目复用的放用户级项目特定的放项目级。这样既不会污染全局又能保证项目内的技能跟着代码走。3.2 一个完整SKILL.md的逐段写法我拿一个真实用过的技能举例——代码审查助手。这个技能我用了大半年帮我在提交前抓出过不少低级错误。--- name: code-review-helper description: 当用户提交代码片段或文件路径需要检查潜在bug、安全问题和代码风格时使用 tags: [code, review, security] --- # 代码审查助手 ## 何时使用 - 用户明确要求审查代码 - 用户提交了代码片段并询问有没有问题 - 代码提交前的自检场景 ## 执行步骤 1. **读取代码**如果用户给的是文件路径先读取完整文件内容如果给的是片段直接使用。 2. **语法与逻辑检查** - 检查是否有明显的语法错误 - 检查边界条件处理空值、越界、除零 - 检查循环和递归的终止条件 3. **安全检查** - 检查用户输入是否直接拼接进查询或命令 - 检查敏感信息是否硬编码 - 检查文件操作是否有路径穿越风险 4. **风格检查** - 命名是否清晰 - 函数是否过长超过50行提示 - 是否有重复代码 5. **输出报告**按严重程度分级列出问题每条包含位置、问题描述、修改建议。 ## 输出格式 按以下结构输出 ### 严重问题 - [行号] 问题描述 → 建议 ### 一般问题 - [行号] 问题描述 → 建议 ### 风格建议 - [行号] 建议内容 ## 注意事项 - 不要为了凑数而报告无关紧要的问题 - 每条问题必须给出具体的修改方向不能只说这里有问题 - 如果代码整体质量良好直接说明不要强行找问题这份文件大概400字但信息密度很高。关键在于每一步都是可执行的动词开头模型读完之后知道该干什么而不是读完还是一头雾水。3.3 让技能被正确触发的三个技巧写完SKILL.md只是第一步能不能被正确触发才是关键。我踩过的坑主要集中在这里。第一个技巧description要写什么时候用而不是是什么。很多人写description喜欢写这是一个代码审查工具这种写法模型很难判断该不该用。改成当用户提交代码需要检查问题时使用匹配率立刻上去了。因为模型是在做当前场景是否匹配的判断你给它场景描述它才能判断。第二个技巧在SKILL.md里写反例。明确写出以下情况不要使用本技能能有效减少误触发。比如代码审查技能里可以写如果用户只是问某个函数的用法不要触发本技能。第三个技巧用examples锚定输出格式。模型对示例的敏感度远高于对描述的理解。给一个完整的输入输出示例比写十句输出要规范都管用。我现在的习惯是每个技能至少配一个example复杂的配两到三个覆盖不同情况。4. 进阶玩法让Skills真正融入工作流4.1 技能组合与链式调用单个技能能做的事有限真正有意思的是把多个技能串起来。比如我有一套内容创作的技能链素材收集→大纲生成→初稿撰写→事实核查→风格润色。每个环节是一个独立技能前一个的输出是后一个的输入。这种链式调用的关键在于接口约定。每个技能的输出格式必须稳定下一个技能才能可靠地消费。我的做法是在每个SKILL.md里明确写出输出格式章节并且用examples固化下来。这样即使模型换了、版本更新了只要格式约定不变整条链就不会断。注意链式调用时不要一次性把所有技能都塞给模型。正确的做法是分步触发每一步只激活当前需要的技能。一次性加载太多技能会稀释模型的注意力反而容易出错。4.2 用Skills封装个人方法论这是我觉得skills最有价值的地方。每个人在工作中都有一套自己的方法论但大部分时候它只存在于脑子里。Skills给了你一个把这些方法论外化的机会。举个例子我做技术方案评审有一套固定的检查清单兼容性、性能、可维护性、回滚方案、监控埋点。以前每次评审都得在脑子里过一遍容易漏。现在我把这套清单写成了一个tech-review技能每次评审前激活它模型会按清单逐项引导我检查。用了三个月漏项率从大概20%降到了几乎为零。写这类方法论技能的要诀是把你做决策时的判断依据写出来。不要只写检查性能要写检查性能预估QPS、检查是否有N1查询、确认缓存策略、评估最坏情况下的响应时间。判断依据越具体技能越像你本人。4.3 团队协作中的Skills管理一个人用skills和一群人用skills复杂度完全不是一个量级。团队场景下我总结了三条经验建立技能仓库把所有skills放在一个独立的Git仓库里按领域分目录。新人入职直接clone能力立刻对齐。制定命名规范技能名统一用领域-动作的格式比如> Agent Skills实战指南：用Markdown定义AI能力，从原理到工作流
1. 从skills这个热词说起它到底是什么最近几个月不管是在技术社区还是各种开发者群里skills这个词出现的频率高得离谱。很多人第一次看到Claude Skills或者Agent Skills的时候第一反应是这不就是个插件吗第二反应是跟Function Calling有什么区别。我一开始也是这么想的直到真正动手写了几个SKILL.md、把它接到实际工作流里跑了一遍才发现这东西的设计思路跟传统的工具调用完全不是一回事。先把概念说清楚。Agent Skills本质上是一种用自然语言描述、以文件形式组织的能力包。它的核心载体是一个叫SKILL.md的Markdown文件里面用结构化的方式写清楚这个技能是干什么的、什么时候该用它、用的时候需要哪些输入、执行步骤是什么、输出长什么样。模型在运行的时候会根据当前任务去匹配这些技能描述然后按照SKILL.md里写的流程去执行。你可以把它理解成给AI写的一份操作手册而不是一段需要编译的代码。它解决的核心问题是让非程序员也能给AI扩展能力同时让能力的复用和版本管理变得像管理文档一样简单。以前你要给模型加个新功能得写代码、定义schema、处理参数校验、调试返回值一套下来没个半天搞不定。现在你只要写一个Markdown文件把步骤讲清楚模型就能照着做。这个门槛的降低是数量级的。适合谁来学三类人最该关注。第一类是日常用Claude Code、Cursor这类工具做开发的工程师skills能让你的重复操作自动化第二类是做数据分析、数学建模、内容创作的知识工作者skills能把你的方法论固化下来反复用第三类是想把自己经验产品化的人一套好的skills就是一套可交付的方法论。哪怕你完全不懂编程只要能把自己的工作流程写清楚就能做出可用的skills。2. Skills的核心设计逻辑为什么是Markdown而不是代码2.1 用自然语言描述能力的底层考量传统工具调用Function Calling要求你把能力定义成严格的JSON Schema参数类型、必填项、枚举值都得写死。这套机制很严谨但有个致命问题它假设所有能力都能被精确地参数化。可现实中大量的任务是模糊的、需要判断的、步骤之间有依赖的。比如帮我审查这段代码的安全问题你没法用几个参数把这个需求描述清楚因为审查什么、按什么标准、发现问题的处理方式都是需要模型在执行过程中动态决定的。Skills的设计者显然想通了这一点。既然模型本身就能理解自然语言那为什么还要用代码去描述能力直接用自然语言写清楚遇到什么情况做什么事就行了。SKILL.md里可以写判断逻辑、可以写分支条件、可以写如果遇到X就参考Y文件这种引用关系。这种表达力是JSON Schema给不了的。我实测下来的感受是对于流程明确、步骤固定的任务skills的编写效率比写代码高5到10倍。一个中等复杂度的技能从构思到能用半小时以内。同样的功能用传统方式实现光调试参数传递就得花两小时。2.2 SKILL.md的文件结构拆解一个标准的SKILL.md通常包含这几个部分我按重要性排序说元信息区技能名称、一句话描述、适用场景标签。这部分决定了模型能不能在正确的时机想起你。描述写得越具体匹配越准。我见过太多人把描述写成处理数据结果模型永远想不起来用它。正确的写法是当用户需要清洗CSV中的重复行并按指定列去重时使用。触发条件明确写出什么情况下该激活这个技能。可以写关键词也可以写场景描述。这部分是给模型看的路由规则。执行步骤核心内容。用有序列表把每一步写清楚每步说明做什么、用什么工具、注意什么。步骤要具体到可执行不能写分析数据这种空话要写读取文件、检查列名、统计每列的空值率。输入输出规范说明需要用户提供什么、最终产出什么格式。这能避免模型自由发挥导致结果不可控。示例给一两个完整的输入输出样例。这是提升技能稳定性的最有效手段没有之一。提示SKILL.md的写法没有强制标准但有一个原则必须遵守——假设读你这份文件的人完全不了解背景。写得越自包含模型执行时越不容易跑偏。2.3 Skills与传统方案的本质差异维度传统Function CallingAgent Skills定义方式JSON Schema代码定义Markdown自然语言编写门槛需要编程能力会写文档即可灵活性参数固定难以处理模糊任务可写判断逻辑和分支复用方式代码包/库文件复制/目录共享调试难度需要看日志、断点直接读SKILL.md看逻辑版本管理Git管理代码Git管理文档diff更直观适用场景精确的API调用流程性、判断性任务这张表是我自己踩坑之后总结的。最关键的差异在最后一行Function Calling适合调一个接口拿一个结果Skills适合完成一件需要多步判断的事。搞混这两个定位用哪个都会别扭。3. 手把手写第一个SKILL.md从零到能用3.1 环境准备与目录结构不管你用的是Claude Code、还是其他支持skills的工具目录结构基本是通用的。我以最常见的组织方式来说skills/ ├── my-first-skill/ │ ├── SKILL.md # 核心定义文件 │ ├── examples/ # 示例输入输出 │ │ ├── input1.md │ │ └── output1.md │ └── resources/ # 技能用到的参考文件 │ └── template.md每个技能一个独立目录目录名用英文小写加连字符。SKILL.md放在根目录这是约定俗成的入口。examples和resources是可选的但强烈建议加上尤其是examples。如果你用的是Claude Codeskills通常放在项目根目录的.claude/skills/下或者用户级的~/.claude/skills/。项目级的技能只对当前项目生效用户级的全局可用。我的建议是通用的、跨项目复用的放用户级项目特定的放项目级。这样既不会污染全局又能保证项目内的技能跟着代码走。3.2 一个完整SKILL.md的逐段写法我拿一个真实用过的技能举例——代码审查助手。这个技能我用了大半年帮我在提交前抓出过不少低级错误。--- name: code-review-helper description: 当用户提交代码片段或文件路径需要检查潜在bug、安全问题和代码风格时使用 tags: [code, review, security] --- # 代码审查助手 ## 何时使用 - 用户明确要求审查代码 - 用户提交了代码片段并询问有没有问题 - 代码提交前的自检场景 ## 执行步骤 1. **读取代码**如果用户给的是文件路径先读取完整文件内容如果给的是片段直接使用。 2. **语法与逻辑检查** - 检查是否有明显的语法错误 - 检查边界条件处理空值、越界、除零 - 检查循环和递归的终止条件 3. **安全检查** - 检查用户输入是否直接拼接进查询或命令 - 检查敏感信息是否硬编码 - 检查文件操作是否有路径穿越风险 4. **风格检查** - 命名是否清晰 - 函数是否过长超过50行提示 - 是否有重复代码 5. **输出报告**按严重程度分级列出问题每条包含位置、问题描述、修改建议。 ## 输出格式 按以下结构输出 ### 严重问题 - [行号] 问题描述 → 建议 ### 一般问题 - [行号] 问题描述 → 建议 ### 风格建议 - [行号] 建议内容 ## 注意事项 - 不要为了凑数而报告无关紧要的问题 - 每条问题必须给出具体的修改方向不能只说这里有问题 - 如果代码整体质量良好直接说明不要强行找问题这份文件大概400字但信息密度很高。关键在于每一步都是可执行的动词开头模型读完之后知道该干什么而不是读完还是一头雾水。3.3 让技能被正确触发的三个技巧写完SKILL.md只是第一步能不能被正确触发才是关键。我踩过的坑主要集中在这里。第一个技巧description要写什么时候用而不是是什么。很多人写description喜欢写这是一个代码审查工具这种写法模型很难判断该不该用。改成当用户提交代码需要检查问题时使用匹配率立刻上去了。因为模型是在做当前场景是否匹配的判断你给它场景描述它才能判断。第二个技巧在SKILL.md里写反例。明确写出以下情况不要使用本技能能有效减少误触发。比如代码审查技能里可以写如果用户只是问某个函数的用法不要触发本技能。第三个技巧用examples锚定输出格式。模型对示例的敏感度远高于对描述的理解。给一个完整的输入输出示例比写十句输出要规范都管用。我现在的习惯是每个技能至少配一个example复杂的配两到三个覆盖不同情况。4. 进阶玩法让Skills真正融入工作流4.1 技能组合与链式调用单个技能能做的事有限真正有意思的是把多个技能串起来。比如我有一套内容创作的技能链素材收集→大纲生成→初稿撰写→事实核查→风格润色。每个环节是一个独立技能前一个的输出是后一个的输入。这种链式调用的关键在于接口约定。每个技能的输出格式必须稳定下一个技能才能可靠地消费。我的做法是在每个SKILL.md里明确写出输出格式章节并且用examples固化下来。这样即使模型换了、版本更新了只要格式约定不变整条链就不会断。注意链式调用时不要一次性把所有技能都塞给模型。正确的做法是分步触发每一步只激活当前需要的技能。一次性加载太多技能会稀释模型的注意力反而容易出错。4.2 用Skills封装个人方法论这是我觉得skills最有价值的地方。每个人在工作中都有一套自己的方法论但大部分时候它只存在于脑子里。Skills给了你一个把这些方法论外化的机会。举个例子我做技术方案评审有一套固定的检查清单兼容性、性能、可维护性、回滚方案、监控埋点。以前每次评审都得在脑子里过一遍容易漏。现在我把这套清单写成了一个tech-review技能每次评审前激活它模型会按清单逐项引导我检查。用了三个月漏项率从大概20%降到了几乎为零。写这类方法论技能的要诀是把你做决策时的判断依据写出来。不要只写检查性能要写检查性能预估QPS、检查是否有N1查询、确认缓存策略、评估最坏情况下的响应时间。判断依据越具体技能越像你本人。4.3 团队协作中的Skills管理一个人用skills和一群人用skills复杂度完全不是一个量级。团队场景下我总结了三条经验建立技能仓库把所有skills放在一个独立的Git仓库里按领域分目录。新人入职直接clone能力立刻对齐。制定命名规范技能名统一用领域-动作的格式比如>