1. 从skills这个热词说起它到底是什么最近几个月不管是在技术群还是各种社区里skills这个词出现的频率高得离谱。很多人第一次看到skills这个词脑子里浮现的是技能这个通用含义但在当下的语境里它特指的是Agent Skills——一种给 AI 编程助手比如 Claude Code、Codex 这类工具扩展能力的模块化机制。你可以把它理解成给 AI 助手装的插件包每个 skill 就是一套封装好的指令、脚本和资源文件让 AI 在特定场景下知道该怎么做、按什么流程做、输出什么格式。我最初接触这个概念的时候也是一头雾水网上搜skills出来的结果五花八门有说skills推荐的有问如何学习skills的还有人在找skills技能库网址。信息碎片化严重没有一个系统性的梳理。所以这篇文章我打算把自己从零摸索到实际用起来的过程完整写下来包括 skills 的核心结构、怎么写一个自己的 skill、怎么安装别人开源的 skill、以及踩过的那些坑。这篇文章适合几类人看一是刚接触 Claude Code 或者类似 AI 编程工具听说有 skills 这个东西但不知道怎么上手的二是已经在用这些工具想自己写 skill 来提高效率的三是做数学建模、前端开发这类工作想找现成 skills 来用的。不管你基础如何我都会尽量用大白话把每个环节讲清楚。先给一个最直观的定义Agent Skills 就是一组放在特定目录下的文件核心是一个叫SKILL.md的说明文件加上可选的脚本、模板、参考文档等资源。AI 助手在运行时会根据你的任务自动判断是否需要加载某个 skill然后按照 SKILL.md 里定义的流程来执行。这个机制解决的核心问题是AI 助手虽然通用能力强但在特定领域的专业流程、格式规范、操作步骤上往往不够精准。你每次都要重复告诉它你要先做A再做B输出格式必须是C非常低效。Skills 就是把这些重复性的指令固化下来一次写好反复使用。2. Skills 的核心结构与工作原理拆解2.1 一个 Skill 的最小组成很多人以为写 skill 很复杂其实最小的 skill 只需要一个文件。你在项目目录下创建一个文件夹比如叫my-skill里面放一个SKILL.md这个 skill 就能被识别了。当然实际使用中通常会加上一些辅助文件让 skill 更强大。一个典型的 skill 目录结构长这样my-skill/ ├── SKILL.md # 核心说明文件必须存在 ├── scripts/ # 可选的脚本目录 │ ├── process.py │ └── validate.sh ├── templates/ # 可选的模板文件 │ └── output-template.md └── references/ # 可选的参考文档 └── api-docs.mdSKILL.md是整个 skill 的灵魂。它通常包含两部分元信息头部用 YAML 格式写在文件最上方和正文指令。元信息里最关键的是nameskill 名称和description描述description 写得好不好直接决定了 AI 能不能在正确的时机触发这个 skill。我见过很多人写 skill 时把 description 写得很模糊比如处理数据的技能结果 AI 根本不知道什么时候该用它。好的 description 应该是具体且带有触发场景的比如当用户需要将 CSV 文件转换为 JSON 格式并进行字段校验时使用此技能。2.2 AI 是怎么发现并加载 Skills 的这里涉及一个很多人忽略的机制渐进式披露Progressive Disclosure。AI 助手并不会一次性把所有 skill 的完整内容都加载到上下文里那样会撑爆 token 限制。它的做法是分层的第一层AI 启动时只扫描所有 skill 的元信息name 和 description建立一个索引。这一层消耗的 token 很少。第二层当你的任务和某个 skill 的 description 匹配上时AI 才会去读取那个 SKILL.md 的完整正文。第三层如果正文里引用了 scripts 或 references 里的文件AI 在执行到那一步时才会按需读取。这个设计非常聪明它让 skill 系统可以容纳几十上百个 skill 而不影响性能。理解这一点对你写 skill 很有帮助description 要精准到能被匹配正文要详细到能指导执行但不要把无关内容塞进正文浪费 token。2.3 为什么是 Markdown 而不是代码有人可能会问为什么 skill 的核心文件是 Markdown 而不是某种配置文件或者代码这其实是刻意为之的。Markdown 是自然语言和结构化格式的混合体AI 对它的理解能力极强。你用自然语言写指令AI 能准确执行你用列表和标题组织步骤AI 能按顺序走。相比写 JSON schema 或者 Python 配置Markdown 的编写门槛低得多非程序员也能上手。而且 Markdown 天然适合写流程说明这种东西。你可以用有序列表写步骤用引用块写注意事项用代码块写示例输入输出。AI 读这种格式的文档就像读一份人类写好的操作手册执行起来非常顺畅。3. 手把手写第一个 Skill从需求到落地3.1 先想清楚什么场景值得做成 Skill不是所有事情都值得写成 skill。我的经验是满足以下条件之一的场景才值得重复性高你每周甚至每天都要做同样的事比如生成周报、格式化数据、跑一套固定的检查流程。步骤固定操作流程是确定的不需要每次临时判断比如先读配置文件再校验字段再生成报告。格式要求严格输出必须符合特定模板或规范比如数学建模论文的摘要格式、前端组件的目录结构。容易出错人工做容易漏步骤比如部署前的检查清单。反过来一次性的、需要大量创造性判断的任务就不太适合做成 skill。比如帮我设计一个系统架构这种每次情况都不一样固化流程反而限制发挥。3.2 写一个代码审查Skill 的完整过程我拿一个实际例子来演示写一个自动做代码审查的 skill。这个 skill 的目标是当我说审查一下这段代码时AI 能按照我定义的检查项逐条过一遍输出结构化的审查报告。第一步建目录。在项目的.claude/skills/目录下不同工具的默认目录可能不同Claude Code 通常是这个路径创建code-review文件夹。第二步写 SKILL.md 的元信息头部--- name: code-review description: 当用户要求审查代码、检查代码质量、或提交代码前需要做质量把关时使用此技能。适用于 Python、JavaScript、TypeScript 等语言。 ---注意 description 里我特意写了触发场景当用户要求审查代码和适用范围语言列表这样 AI 匹配起来更准。第三步写正文指令。这部分是核心我把它分成几个模块## 审查流程 1. 首先通读代码理解整体功能和结构 2. 按以下检查项逐条审查 - 命名规范变量、函数、类名是否清晰且符合语言惯例 - 错误处理是否有未捕获的异常、边界条件是否处理 - 安全性是否存在注入风险、敏感信息硬编码 - 性能是否有明显的低效操作如循环内重复计算 - 可读性注释是否充分、函数是否过长 3. 对每个问题标注严重程度严重/警告/建议 4. 按模板输出报告 ## 输出模板 使用以下格式输出 ### 审查概览 - 文件{文件名} - 问题总数{数量} - 严重问题{数量} ### 详细问题 | 行号 | 严重程度 | 问题描述 | 修改建议 | |------|----------|----------|----------| | ... | ... | ... | ... | ## 注意事项 - 不要吹毛求疵聚焦真正影响质量的问题 - 对每个问题给出具体的修改代码示例 - 如果代码整体质量良好也要明确指出第四步测试。写完后我在对话里说帮我审查一下 utils.py观察 AI 是否触发了这个 skill输出是否符合模板。第一次测试时我发现 AI 没有严格按照表格格式输出原因是我的模板部分写得不够强调。后来我在模板前加了一句必须严格使用以下表格格式不得省略任何列问题就解决了。3.3 写好 SKILL.md 的几个关键技巧经过多次迭代我总结了几个让 skill 更可靠的写法指令要具体不要抽象。写检查代码质量不如写检查是否存在未处理的 Promise rejection。前者 AI 不知道怎么执行后者有明确的判断标准。用有序列表定义流程。AI 对有序列表的执行顺序理解得很好把步骤编号写清楚它就会按顺序走。给出输入输出的具体示例。在 SKILL.md 里放一两个输入是什么、期望输出是什么的例子AI 的模仿能力很强看到例子后输出会稳定很多。把容易出错的点单独用引用块标出来。比如 注意不要修改原文件只输出建议这种强调能有效防止 AI 越界操作。控制正文长度。虽然 skill 可以写很长但正文越长AI 读取时消耗的 token 越多而且容易抓不住重点。我的经验是核心流程控制在 500 字以内详细参考放到 references 目录里按需加载。4. 安装和使用别人的 Skills实操指南4.1 从哪里找现成的 Skills自己写 skill 固然好但很多通用场景已经有现成的了直接用能省不少事。目前 skills 的主要来源有几个官方和社区仓库一些 AI 工具官方会维护 skill 示例库社区也有大量开源贡献。搜索时用awesome skills或者skills 仓库这类关键词能找到不少合集。GitHub 上的个人项目很多开发者会把自己写的 skill 开源出来比如专门做数学建模的、做前端组件生成的、做数据清洗的。工具内置的 skill 市场部分工具开始提供内置的 skill 浏览和安装功能直接在界面里搜索就行。热搜词里提到的数学建模skills推荐、前端开发skills、ai漫剧常用skills说明这些垂直领域的 skill 需求很旺盛。如果你正好做这些方向优先找现成的用能少走很多弯路。4.2 手动安装 GitHub 上的 Skill这是被问得最多的问题之一claude code怎么手动装github上的skills。其实流程不复杂核心就是把文件放到正确的目录。第一步找到 skill 的仓库地址把整个仓库克隆下来或者下载压缩包解压。假设你下载了一个叫># 项目级安装示例 mkdir -p .claude/skills cp -r> 
长河君 · 2026/10/2 13:40:21 · 阅读 1.2k Agent Skills 从入门到实战：手把手教你编写与安装 AI 编程助手技能
1. 从skills这个热词说起它到底是什么最近几个月不管是在技术群还是各种社区里skills这个词出现的频率高得离谱。很多人第一次看到skills这个词脑子里浮现的是技能这个通用含义但在当下的语境里它特指的是Agent Skills——一种给 AI 编程助手比如 Claude Code、Codex 这类工具扩展能力的模块化机制。你可以把它理解成给 AI 助手装的插件包每个 skill 就是一套封装好的指令、脚本和资源文件让 AI 在特定场景下知道该怎么做、按什么流程做、输出什么格式。我最初接触这个概念的时候也是一头雾水网上搜skills出来的结果五花八门有说skills推荐的有问如何学习skills的还有人在找skills技能库网址。信息碎片化严重没有一个系统性的梳理。所以这篇文章我打算把自己从零摸索到实际用起来的过程完整写下来包括 skills 的核心结构、怎么写一个自己的 skill、怎么安装别人开源的 skill、以及踩过的那些坑。这篇文章适合几类人看一是刚接触 Claude Code 或者类似 AI 编程工具听说有 skills 这个东西但不知道怎么上手的二是已经在用这些工具想自己写 skill 来提高效率的三是做数学建模、前端开发这类工作想找现成 skills 来用的。不管你基础如何我都会尽量用大白话把每个环节讲清楚。先给一个最直观的定义Agent Skills 就是一组放在特定目录下的文件核心是一个叫SKILL.md的说明文件加上可选的脚本、模板、参考文档等资源。AI 助手在运行时会根据你的任务自动判断是否需要加载某个 skill然后按照 SKILL.md 里定义的流程来执行。这个机制解决的核心问题是AI 助手虽然通用能力强但在特定领域的专业流程、格式规范、操作步骤上往往不够精准。你每次都要重复告诉它你要先做A再做B输出格式必须是C非常低效。Skills 就是把这些重复性的指令固化下来一次写好反复使用。2. Skills 的核心结构与工作原理拆解2.1 一个 Skill 的最小组成很多人以为写 skill 很复杂其实最小的 skill 只需要一个文件。你在项目目录下创建一个文件夹比如叫my-skill里面放一个SKILL.md这个 skill 就能被识别了。当然实际使用中通常会加上一些辅助文件让 skill 更强大。一个典型的 skill 目录结构长这样my-skill/ ├── SKILL.md # 核心说明文件必须存在 ├── scripts/ # 可选的脚本目录 │ ├── process.py │ └── validate.sh ├── templates/ # 可选的模板文件 │ └── output-template.md └── references/ # 可选的参考文档 └── api-docs.mdSKILL.md是整个 skill 的灵魂。它通常包含两部分元信息头部用 YAML 格式写在文件最上方和正文指令。元信息里最关键的是nameskill 名称和description描述description 写得好不好直接决定了 AI 能不能在正确的时机触发这个 skill。我见过很多人写 skill 时把 description 写得很模糊比如处理数据的技能结果 AI 根本不知道什么时候该用它。好的 description 应该是具体且带有触发场景的比如当用户需要将 CSV 文件转换为 JSON 格式并进行字段校验时使用此技能。2.2 AI 是怎么发现并加载 Skills 的这里涉及一个很多人忽略的机制渐进式披露Progressive Disclosure。AI 助手并不会一次性把所有 skill 的完整内容都加载到上下文里那样会撑爆 token 限制。它的做法是分层的第一层AI 启动时只扫描所有 skill 的元信息name 和 description建立一个索引。这一层消耗的 token 很少。第二层当你的任务和某个 skill 的 description 匹配上时AI 才会去读取那个 SKILL.md 的完整正文。第三层如果正文里引用了 scripts 或 references 里的文件AI 在执行到那一步时才会按需读取。这个设计非常聪明它让 skill 系统可以容纳几十上百个 skill 而不影响性能。理解这一点对你写 skill 很有帮助description 要精准到能被匹配正文要详细到能指导执行但不要把无关内容塞进正文浪费 token。2.3 为什么是 Markdown 而不是代码有人可能会问为什么 skill 的核心文件是 Markdown 而不是某种配置文件或者代码这其实是刻意为之的。Markdown 是自然语言和结构化格式的混合体AI 对它的理解能力极强。你用自然语言写指令AI 能准确执行你用列表和标题组织步骤AI 能按顺序走。相比写 JSON schema 或者 Python 配置Markdown 的编写门槛低得多非程序员也能上手。而且 Markdown 天然适合写流程说明这种东西。你可以用有序列表写步骤用引用块写注意事项用代码块写示例输入输出。AI 读这种格式的文档就像读一份人类写好的操作手册执行起来非常顺畅。3. 手把手写第一个 Skill从需求到落地3.1 先想清楚什么场景值得做成 Skill不是所有事情都值得写成 skill。我的经验是满足以下条件之一的场景才值得重复性高你每周甚至每天都要做同样的事比如生成周报、格式化数据、跑一套固定的检查流程。步骤固定操作流程是确定的不需要每次临时判断比如先读配置文件再校验字段再生成报告。格式要求严格输出必须符合特定模板或规范比如数学建模论文的摘要格式、前端组件的目录结构。容易出错人工做容易漏步骤比如部署前的检查清单。反过来一次性的、需要大量创造性判断的任务就不太适合做成 skill。比如帮我设计一个系统架构这种每次情况都不一样固化流程反而限制发挥。3.2 写一个代码审查Skill 的完整过程我拿一个实际例子来演示写一个自动做代码审查的 skill。这个 skill 的目标是当我说审查一下这段代码时AI 能按照我定义的检查项逐条过一遍输出结构化的审查报告。第一步建目录。在项目的.claude/skills/目录下不同工具的默认目录可能不同Claude Code 通常是这个路径创建code-review文件夹。第二步写 SKILL.md 的元信息头部--- name: code-review description: 当用户要求审查代码、检查代码质量、或提交代码前需要做质量把关时使用此技能。适用于 Python、JavaScript、TypeScript 等语言。 ---注意 description 里我特意写了触发场景当用户要求审查代码和适用范围语言列表这样 AI 匹配起来更准。第三步写正文指令。这部分是核心我把它分成几个模块## 审查流程 1. 首先通读代码理解整体功能和结构 2. 按以下检查项逐条审查 - 命名规范变量、函数、类名是否清晰且符合语言惯例 - 错误处理是否有未捕获的异常、边界条件是否处理 - 安全性是否存在注入风险、敏感信息硬编码 - 性能是否有明显的低效操作如循环内重复计算 - 可读性注释是否充分、函数是否过长 3. 对每个问题标注严重程度严重/警告/建议 4. 按模板输出报告 ## 输出模板 使用以下格式输出 ### 审查概览 - 文件{文件名} - 问题总数{数量} - 严重问题{数量} ### 详细问题 | 行号 | 严重程度 | 问题描述 | 修改建议 | |------|----------|----------|----------| | ... | ... | ... | ... | ## 注意事项 - 不要吹毛求疵聚焦真正影响质量的问题 - 对每个问题给出具体的修改代码示例 - 如果代码整体质量良好也要明确指出第四步测试。写完后我在对话里说帮我审查一下 utils.py观察 AI 是否触发了这个 skill输出是否符合模板。第一次测试时我发现 AI 没有严格按照表格格式输出原因是我的模板部分写得不够强调。后来我在模板前加了一句必须严格使用以下表格格式不得省略任何列问题就解决了。3.3 写好 SKILL.md 的几个关键技巧经过多次迭代我总结了几个让 skill 更可靠的写法指令要具体不要抽象。写检查代码质量不如写检查是否存在未处理的 Promise rejection。前者 AI 不知道怎么执行后者有明确的判断标准。用有序列表定义流程。AI 对有序列表的执行顺序理解得很好把步骤编号写清楚它就会按顺序走。给出输入输出的具体示例。在 SKILL.md 里放一两个输入是什么、期望输出是什么的例子AI 的模仿能力很强看到例子后输出会稳定很多。把容易出错的点单独用引用块标出来。比如 注意不要修改原文件只输出建议这种强调能有效防止 AI 越界操作。控制正文长度。虽然 skill 可以写很长但正文越长AI 读取时消耗的 token 越多而且容易抓不住重点。我的经验是核心流程控制在 500 字以内详细参考放到 references 目录里按需加载。4. 安装和使用别人的 Skills实操指南4.1 从哪里找现成的 Skills自己写 skill 固然好但很多通用场景已经有现成的了直接用能省不少事。目前 skills 的主要来源有几个官方和社区仓库一些 AI 工具官方会维护 skill 示例库社区也有大量开源贡献。搜索时用awesome skills或者skills 仓库这类关键词能找到不少合集。GitHub 上的个人项目很多开发者会把自己写的 skill 开源出来比如专门做数学建模的、做前端组件生成的、做数据清洗的。工具内置的 skill 市场部分工具开始提供内置的 skill 浏览和安装功能直接在界面里搜索就行。热搜词里提到的数学建模skills推荐、前端开发skills、ai漫剧常用skills说明这些垂直领域的 skill 需求很旺盛。如果你正好做这些方向优先找现成的用能少走很多弯路。4.2 手动安装 GitHub 上的 Skill这是被问得最多的问题之一claude code怎么手动装github上的skills。其实流程不复杂核心就是把文件放到正确的目录。第一步找到 skill 的仓库地址把整个仓库克隆下来或者下载压缩包解压。假设你下载了一个叫># 项目级安装示例 mkdir -p .claude/skills cp -r>