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.md

SKILL.md是整个 skill 的灵魂。它通常包含两部分：元信息头部（用 YAML 格式写在文件最上方）和正文指令。元信息里最关键的是name（skill 名称）和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>