跳绳鸭
67.76M · 2026-02-04
本文通过解析一个在社区中比较火的 agent skill 来切入，首先介绍如何使用这个 skill，并且分析它的 skill 文件组成。上手使用这个实例后，你就会对 agent skill 有一个非常具象的理解。
在阅读本文之前，请确保你已经了解并使用过 claude code，如果还没用上这个强大的工具，请参考大橘子的文章配置并使用：开源模型质变：Claude Code 超级小白入门指南
如果我直接告诉你 skill 是一个文件，里面包含 skill.md，还有包含其他资源文件和 python 执行脚本，你大概率还是不理解它是什么，接下来我准备循序渐进的介绍它。
首先针对同样一个任务，比如说让大模型设计一个网站；
对于普通人和一个前端设计专家来说，他们实现的效果是截然不同的。
普通人几乎是完全依赖大模型本身的认知来设计网站；
而专家可以将自己的领域知识用提示词的方式告诉大模型如何更好的设计网站，再结合大模型的理解和执行能力，就能能够做出出色的网站。
注意：以上说的大模型，具体指代claude code 等 agent 产品形态，底层基于LLM驱动。
那有没有一种方式可以将这种专家经验沉淀下来，让其他人也能共用？这就是 skills 的核心设计初衷之一。
接下来我们再来看在 claude code 里面，一个具体的 agent skill 是怎么实现的。
最近看到社区一个比较专业的 agent skill，叫 ui-ux-pro-max-skill，我们从这个开源 skill 来切入，它是一个用来设计前端页面和交互的专业技能。项目名称也很语义化，ui 就是用户界面（User Interface）， ux 是用户体验（User Experience）。pro max 是当前终端产品一贯的命名风格，代表更专业更极致的含义。
目前在 github 上已经收获 2w 多 star，今天我们就拿它来深入分析。
这是它的官网主页，红框里框起来的是目前主流的 AI 开发平台或工具，在这些平台上都可以使用这个技能。
将当前这个项目克隆下来后，直接在当前目录下启动 claude code 就可以直接使用它。
不一会儿，一个像样的网站就自动生成好了，所以有的文件都写入了本地文件夹 blog下面，并且遵从指令使用了 react 技术栈来完成编码。
当然你也可以指定其他的技术栈（例如 vue），如果不指定技术栈，默认是会一份包含所有内容的 html。
生成的网站长这样：
我们观察一下 claude code 的输出日志，看看它是如何完成这个任务的。
首先 claude code 根据用户的 prompt 识别到了当前任务可以使用 /ui-ux-pro-max 这个技能来实现，于是它就会参照这个技能里定义的工作流来完成这个网站的设计和实现。
接下来它执行了一系列的 python 脚本获取设计方案。
脚本执行成功之后，它读取了所有的设计指南，然后开始一步步编码。
看到这里，你或许会意识到：后续的编码都是 claude code 本身的能力了；
而这个 skill 只是为了帮助了 claude code 拿到了更详细的设计指南和最佳实践。
我们用一句话指令当然也可能让 claude code 产出博客网站的代码，但是生成的效果不确定性会非常高，加上了专业的设计指南和最佳实践的约束之后，同样的底层模型驱动下，生成效果肯定会好很多。
我们来分析下这个开源的 skill 是如何实现的。
在项目的目录下，我们可以看到很多个文件夹，这个开源的技能包实现了对多个 coding agent 平台的兼容支持，意味着我们可以在多个AI 开发工具（涵盖 cursor、windsurf、 Antigravity）中使用它。其中最典型的是 claude code。
我们重点看一下在 claude code 里面，它是如何实现这个 skill 的。
这里只需要关注.claude/skill/ui-ux-pro-max这个文件夹即可。
有两种方式实现 skills，第一种就是将 skill 写在项目下的 ./claude/skill 目录下，它是项目维度上的；
第二种是将 skill 安装到全局的 .claude 目录下，这样就可以在任意位置使用这个技能。
首先看一下 skill.md 文件的头部
---
name: ui-ux-pro-max
description: "UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient. Integrations: shadcn/ui MCP for component search and examples."
---
这是技能文件的元数据。
claude code 初始接收用户指令的时候，仅会在上下文携带这两个字段的信息。
skill.md 文件里后面所有的正文，都是用来这个技能的使用细节。
我们看到正文里核心包含这些内容：
## When to Apply
...
## Quick Reference
...
## Prerequisites
...
## How to Use This Skill
### Step 1: Analyze User Requirements
### Step 2: Generate Design System (REQUIRED)
### Step 3: Supplement with Detailed Searches (as needed)
...
正文里详细描述了
claude code 是编程领域强大的 agent，后文我将直接用 agent 来指代 claude code。
当 agent 判断需要使用这个技能之后，就会详细参考正文里的步骤来使用该技能。
例如步骤二里详细说明了要执行一个 python 脚本来获取设计指南
这个脚本就在 skill 目录下这个位置
我们看到在 script 目录下一共有三个脚本，其中 search.py 用来查找合适的设计方案。而 core.py 和 design_system.py 是在 search.py 内部会调用的模块文件。
那么它的搜索功能是如何实现的呢？
我们看到这里还有个 data 文件夹，里面包含很多 csv 文件
这么多的表格数据实际上就是技能内置的用来提供设计指南的核心知识库。
| 文件 | 作用 | 记录数 |
|---|---|---|
| styles.csv | UI风格定义（玻璃态、极简、暗黑等） | 50种风格 |
| colors.csv | 配色方案 | 97个调色板 |
| typography.csv | 字体搭配 | 57组字体 |
| ux-guidelines.csv | UX最佳实践 | 99条规则 |
| charts.csv | 图表类型推荐 | 25种图表 |
| products.csv | 产品类型建议 | 各行业模板 |
| landing.csv | 落地页结构 | CTA策略 |
| icons.csv | 图标库信息 | 图标资源 |
| web-interface.csv | Web界面指南 | 通用规则 |
| ui-reasoning.csv | 推理规则 | 100条行业规则 |
| react-performance.csv | React性能优化 | 性能指南 |
在 stack 目录下，定义了覆盖多个技术栈的最佳实践经验的数据13个技术栈的专属指南：
有了这些经验沉淀的数据，再搭配上特定的搜索算法，就能实现 为生成网站的需求 快速提供专业的设计方案和最佳实践方案。
前文我们提到：编码都是 coding agent 本身的能力；
而这份 skill 只是为 AI 提供了更详细的设计指南和最佳实践。最终传递给 AI 在它写代码之前的 prompt，已经被专业化改写过了，不再是最初的手写的提示词。
在这个改写的过程中，借助了脚本执行来搜索 csv 数据库的各种设计资源。
这些 csv 数据文件本质上也是这个 skill 的知识库。
值得注意的是，这些脚本文件也好，csv 知识库也好，并不是一股脑都传递给 agent 的上下文。
而是在执行任务的过程中按需加载的，这也是官方提到的 progressive disclosure（渐进式披露） 。
元数据就是 skill.md 头部的两个字段说明
---
name: ui-ux-pro-max
description: "UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient. Integrations: shadcn/ui MCP for component search and examples."
---
如果当前具备多个 skill 技能，而每个 skill 文件夹又有众多文件。只有这个元数据会被加载进 agent 的初始上下文，agent 起初只需要知道有哪些技能可用，什么时候用对应的技能即可。
## When to Apply
...
## Quick Reference
...
## Prerequisites
...
## How to Use This Skill
### Step 1: Analyze User Requirements
### Step 2: Generate Design System (REQUIRED)
### Step 3: Supplement with Detailed Searches (as needed)
...
skill.md 的正文定义了使用技能的详细指导描述，这部分内容也可能比较多，仅当 agent 判断当前的任务需要使用到这个技能的时候，才会被加载进当前 agent 的上下文用于指导后续如何使用技能。
对了，claude code 之类的coding agent 是用 bash 命令来动态读到 skill.md 文件内容的。
在刚刚这个 skill 案例中，csv 数据表属于知识库文件，python 脚本属于代码文件。
这些资源文件也是在执行任务过程中按照指导的 workflow 来按需加载的。
scripts/
├── core.py (10K) - 核心搜索引擎：BM25算法、CSV配置
├── design_system.py (43K) - 设计系统生成器：多域搜索、推理引擎、持久化
└── search.py (5K) - CLI入口：参数解析、命令分发、输出格式化
总结一下： progressive disclosure（渐进式披露） 这个特性确保了在 skill 执行过程中，仅有相关的资源或者代码会被加载进 agent 的上下文，无关内容不会占用上下文。因为上下文窗口的空间太宝贵了，且会很大程度影响 AI 生成的质量。
agent skill 是什么？
为什么会出现 agent skill，它解决了什么问题？
以上是我的个人理解，欢迎交流。
