你写了三年代码，踩过无数坑，沉淀了一套自己的"直觉"——哪些写法容易出 bug、哪些组合性能最好、哪些边界 case 新人一定会漏。 这些东西，以前只能靠"口口相传"或者写在没人看的 Wiki 里。现在，它们可以变成 Agent Skills——让 AI 继承你的经验，替你传授。

一、从"写文档"到"资产化"

1.1 一个反复出现的问题

每个有一定积累的开发者或团队，都会遇到这样的困境：

• 你知道这个组件有三个隐蔽的坑，但每次新人接手都要重新踩一遍
• 团队有一套成熟的 CSS 动效方案，但散落在五个项目的不同文件里
• 你写了一份详尽的开发规范，但三个月后发现没人在看

问题不是缺少知识，而是知识的存在形式不对。文档是给人看的，但人不一定会看；规范是写给人遵守的，但遵守需要自觉。

1.2 AI Agent 改变了知识的消费方式

2026 年的今天，越来越多的日常开发由 AI Coding Agent 承接——Cursor、Claude、Windsurf 等工具已经深度嵌入了从写代码到审代码的每个环节。

这带来了一个新的可能性：把知识沉淀给 AI，让 AI 在生成代码时自动遵守。

Agent Skills 就是这个可能性的具体载体。它不是"文档"，而是一种资产——结构化的、可检索的、能被 Agent 自动加载和遵循的工程知识。

区别在于：

当然，Skills 并不能完全替代文档——面向人的沟通、架构决策的上下文、设计意图的解释，这些仍然需要传统文档。但对于 "怎么做"和"不该怎么做" 这类操作性知识，Skills 是更高效的载体。

二、什么是 Agent Skill

2.1 一句话定义

Agent Skill 是一个自包含的知识单元，由一个 SKILL.md 主文件和可选的辅助文档组成，安装到 Agent 运行环境后，Agent 会根据用户意图自动匹配并加载相关 Skill，在生成代码时遵循其中的规则和模板。

2.2 和 Rules、MCP 的区别

在 AI 增强开发的工具箱里，Skills 不是唯一的选项。理解它和同族工具的边界，才能做出正确的选型：

简单的判断标准：

• "这个项目里所有代码都必须遵守" → Rules
• "当开发者在做某类事情时，应该知道这些" → Skills
• "需要调用外部服务或执行操作" → MCP

三者不是互斥关系。一个成熟的 AI 增强体系，往往是 Rules 打底（全局约束），Skills 补充（领域知识），MCP 扩展（服务端能力）。关于 MCP 的深入理解，可以参考：用 Node.js 开发一个 MCP 服务：从协议本质到最佳实践。

2.3 Skill 的组成

一个 Skill 的最小可用单元：

1skill-name/
2├── SKILL.md              # 必需：主文件（frontmatter + 正文）
3├── reference.md          # 可选：详细参考文档
4├── examples.md           # 可选：使用示例
5└── recipes/              # 可选：场景化配方
6    ├── scenario-a.md
7    └── scenario-b.md

其中 SKILL.md 是唯一的必需文件，也是 Agent 加载的入口。辅助文档按需添加——当主文件超过 500 行时，就应该考虑拆分。

三、写一个好的 SKILL.md

3.1 Frontmatter：让 Agent 找到你

每个 SKILL.md 必须包含 YAML frontmatter，其中两个字段至关重要：

1---
2name: qiuye-edge-gradient-mask
3description: >-
4  Implement edge gradient fade masks for scrollable areas, viewports, sections,
5  and visual elements. Use when adding soft fade-out edges to scroll containers,
6  page borders, infinite scroll strips, card edges, or any area that needs a
7  smooth gradient transition instead of a hard clip. Covers scroll-aware
8  show/hide, horizontal/vertical fades, CSS mask-image, and overlay div
9  approaches. Triggers on: "edge fade", "gradient mask", "scroll fade",
10  "fade edge", "edge mask", "soft edge", "gradient overlay", "scroll shadow",
11  "overflow fade", "mask-image gradient", "edge blur".
12---

description 是 Skill 能否被正确匹配的决定性因素。写法上有几个关键原则：

1. 用第三人称描述能力（"Implement X…" 而非 "I help you…"）
2. 同时说明 what 和 when（做什么 + 什么时候用）
3. 在末尾追加 Triggers on: 关键词列表，覆盖用户可能的表述方式

1# ❌ 差的 description
2description: "A skill for CSS stuff"
3
4# ✅ 好的 description
5description: >-
6  Implement edge gradient fade masks for scrollable areas and visual elements.
7  Use when adding soft fade-out edges to scroll containers or page borders.
8  Triggers on: "edge fade", "gradient mask", "scroll fade", "soft edge".

这和 MCP 中 Tool 的 description 是同一个道理——描述写得越精准，匹配就越准确。

3.2 正文结构：为 Agent 而写，不是为人

Skill 正文和传统文档最大的区别在于读者不同。人可以跳读、理解隐含语境、自动补全上下文；Agent 需要明确的、结构化的指令。

推荐的正文结构：

1# Skill 标题
2
3一句话概述这个 Skill 做什么。
4
5## 核心原则
6不可违反的规则（用"必须"、"禁止"明确表述）
7
8## 场景决策
9场景 → 推荐方案的映射表
10
11## 模板 / 配方
12每个方案的具体实现（代码 + 关键点说明）
13
14## 主题 / 兼容性
15颜色、响应式、浏览器兼容等注意事项
16
17## 常见陷阱
18容易犯的错误及正确做法

几个写作原则：

• 指令优先于解释：Agent 需要知道"怎么做"，而不是"为什么这样做"。把 why 留给辅助文档。
• 用表格做决策映射：场景 → 方案的对应关系，表格比叙述更容易被 Agent 准确解析。
• 代码示例要完整可用：不要给伪代码，给真正能跑的最小示例。
• 正面示例和反面示例并列：明确说"做什么"和"不做什么"，减少 Agent 的猜测空间。

3.3 一个真实的例子

以一个边缘渐变遮罩的 Skill 为例，看看好的 Skill 长什么样：

1---
2name: qiuye-edge-gradient-mask
3description: >-
4  Implement edge gradient fade masks for scrollable areas, viewports, sections,
5  and visual elements. Use when adding soft fade-out edges to scroll containers,
6  page borders, infinite scroll strips, card edges, or any area that needs a
7  smooth gradient transition instead of a hard clip. Covers scroll-aware
8  show/hide, horizontal/vertical fades, CSS mask-image, and overlay div
9  approaches. Triggers on: "edge fade", "gradient mask", "scroll fade",
10  "fade edge", "edge mask", "soft edge", "gradient overlay", "scroll shadow",
11  "overflow fade", "mask-image gradient", "edge blur".
12---
13
14# Edge Gradient Mask (边缘渐变遮罩)
15
16在容器、视口或视觉元素的边缘叠加渐变遮罩，使内容柔和地淡出。
17
18## 核心原则
19
20- **必须** `pointer-events-none` + `aria-hidden="true"`
21- **主题适配**：颜色使用 `from-background` 等语义 token
22- **z-index**：遮罩高于被遮内容，低于操作按钮
23- 静态遮罩用纯 CSS；需要滚动感知时才引入 JS
24
25## 场景决策
26
27| 场景 | 推荐方案 | 参考模板 |
28|---|---|---|
29| 页面固定边缘 | mask-image + backdrop-blur | 模板 A |
30| 小型滚动容器边缘 | overlay div + 滚动感知 | 模板 B |
31| 水平无限滚动条两侧 | 左右静态 overlay | 模板 C |
32| 装饰性渐变 | overlay div 或 pseudo-element | 模板 D |
33
34## 模板 A — 页面固定边缘遮罩
35
36（具体代码实现...）
37
38## 常见陷阱
39
40- ❌ 忘记 `pointer-events-none`，导致遮罩拦截了点击
41- ❌ 硬编码颜色值，暗色模式下遮罩露白边
42- ✅ 使用 `oklch(from var(--background) ...)` 从主题变量派生

这个结构的核心逻辑是：原则 → 决策 → 实现 → 避坑，Agent 按顺序读完就能正确执行。

四、技能仓库：从散落到治理

4.1 为什么需要一个仓库

当你的 Skills 只有两三个时，放在项目的 .cursor/skills/ 目录下就够了。但随着积累增多，问题会浮现：

• 跨项目复用困难：同一个 Skill 在三个项目里各有一份，版本不一致
• 命名冲突：两个人都写了叫 button-usage 的 Skill，内容完全不同
• 检索低效：二十个 Skill 平铺在一个目录下，找不到想要的
• 质量参差：没有审阅流程，有的 Skill 写得很好，有的几乎不可用

解法很自然：用一个独立的 Git 仓库来统一管理所有 Skills。

4.2 目录设计

好的目录结构应该满足三个要求：可检索（按领域快速定位）、可审阅（结构一致便于 review）、可演进（新增 Skill 不需要重构目录）。

推荐的分层结构：

1qiuye-skills/
2├── README.md
3├── frontend/
4│   ├── ui-ux/
5│   │   └── skills/
6│   │       ├── edge-gradient-mask/
7│   │       │   ├── SKILL.md
8│   │       │   └── reference.md
9│   │       └── scroll-animation/
10│   │           └── SKILL.md
11│   ├── engineering/
12│   │   └── skills/
13│   │       └── monorepo-setup/
14│   │           └── SKILL.md
15│   └── component-patterns/
16│       └── skills/
17│           └── form-validation/
18│               └── SKILL.md
19├── ai-tooling/
20│   └── skills/
21│       ├── mcp-server-dev/
22│       │   └── SKILL.md
23│       └── prompt-engineering/
24│           └── SKILL.md
25└── devops/
26    └── skills/
27        └── docker-compose-patterns/
28            └── SKILL.md

核心约定：

1. 一级目录按技术领域划分（frontend/、ai-tooling/、devops/）
2. 二级目录按子领域细分（ui-ux/、engineering/）
3. 所有 Skill 目录统一位于 skills/ 下，层级固定为 .../.../skills/<skill-name>/SKILL.md
4. 每个 Skill 目录是最小可用单元，包含 SKILL.md 和所有辅助资产

这种设计保证了：向上可以按领域浏览，向下可以精确定位到具体 Skill。

4.3 命名规范

Skill 的命名需要同时服务两个目的：人的检索和 Agent 的匹配。

目录名（即 Skill 的物理路径标识）：

• 小写英文 + 连字符（kebab-case）
• 简洁但有区分度，如 edge-gradient-mask、form-validation
• 避免过于泛化的名字，如 css-tips、react-stuff

name 字段（SKILL.md frontmatter 中的唯一标识）：

• 在整个仓库中全局唯一
• 可以加前缀标识来源或领域，如 qiuye-edge-gradient-mask
• 遵循 name 字段的字符约束：小写字母、数字、连字符，最长 64 字符

五、安装与分发

5.1 安装机制

Skills 的安装本质上就是把 Skill 目录复制到 Agent 能识别的路径下。不同场景有不同的安装位置：

选择依据很简单：

• 项目相关的 Skill（如项目特有的组件用法）→ 安装到项目级，随代码仓库共享
• 通用的个人积累（如通用的 CSS 动效方案）→ 安装到个人级

5.2 从仓库安装

手动复制当然可以，但不够优雅。npx skills 提供了从 Git 仓库直接安装的能力：

交互式安装仓库内的 Skills：

1npx skills add https://github.com/qiuyedx/qiuye-skills.git

查看仓库中可用的 Skills 列表：

1npx skills add https://github.com/qiuyedx/qiuye-skills.git --list

安装某个子路径下的 Skills：

直接复制仓库中子目录的页面链接即可。比如只想安装前端 UI/UX 相关的 Skills：

1npx skills add https://github.com/qiuyedx/qiuye-skills/-/tree/master/frontend/ui-ux/skills

安装指定名称的 Skill：

name 是 SKILL.md 头部的 name 字段，在仓库中全局唯一：

1npx skills add https://github.com/qiuyedx/qiuye-skills.git --skill qiuye-edge-gradient-mask

5.3 更新与维护

1# 检查已安装的 Skills 是否有更新
2npx skills check
3
4# 更新所有已安装的 Skills
5npx skills update

整个安装流程可以归纳为：

六、团队级实践

6.1 从个人积累到团队共享

个人的 Skills 仓库往往是自然生长的——解决了一个问题，就顺手沉淀一个 Skill。但当团队想要共享 Skills 时，需要一些额外的治理。

核心问题是：如何保证 Skills 的质量和一致性，同时不阻碍贡献？

推荐的做法：

1. 设立统一的仓库，团队成员通过 PR 贡献 Skill
2. 每个 PR 至少一人 review，重点审查 description 的准确性和正文的可执行性
3. 定期清理，淘汰过时或低质量的 Skill

6.2 Skill 的生命周期

一个 Skill 从诞生到退役，通常经历以下阶段：

• Draft：开发者提交初版，可能只有基本框架
• Review：团队审阅，确认 description 准确、正文可执行、代码示例可用
• Active：正式使用，Agent 可以匹配和加载
• Maintained：发现了需要修正的问题，或依赖的技术栈有变化
• Deprecated：技术方案过时或被更好的 Skill 替代

6.3 质量门禁

一个 Skill 进入 Active 状态前，建议通过以下检查：

1✅ name 字段全局唯一
2✅ description 准确描述了能力和适用场景
3✅ description 包含 Triggers on 关键词
4✅ 主文件 SKILL.md 不超过 500 行
5✅ 代码示例可直接运行（非伪代码）
6✅ 包含"核心原则"或"禁止事项"部分
7✅ 包含至少一个正面示例和一个反面示例
8✅ 在真实场景中做过至少一次生成验证

最后一条尤其重要——Skill 的质量最终由生成效果检验，而不是由文档的"看起来完整"来保证。

6.4 与项目 Rules 的协同

团队的 Skills 仓库和项目的 Rules 配置是两个互补的层次：

加载优先级上，Rules 高于 Skills——这意味着如果 Rules 说"禁止使用 any"，即使某个 Skill 的示例代码中用了 any，Agent 也应该遵守 Rules 的约束。这种分层设计保证了项目级约束不会被外部 Skill 破坏。

七、写 Skill 的方法论

7.1 从哪里开始

不要试图一次性把所有经验都写成 Skill。从最高频的问题开始：

1. 回忆过去三个月被问过最多的问题——"这个组件怎么用？"、"这个动效怎么实现？"、"这种场景选哪个方案？"
2. 翻 Code Review 记录——反复指出的同类问题，就是 Skill 的候选内容
3. 找到 AI 经常犯错的地方——Agent 用错了你的内部组件？这正是 Skill 该覆盖的

7.2 迭代而非一步到位

Skill 的写作不应该是"憋一篇完美文档"的过程，而应该是一个快速迭代的循环：

关键心态是：Skill 的第一版一定不完美，这没关系。 重要的是让它尽快进入"被使用 → 被验证 → 被改进"的循环。

7.3 description 的迭代技巧

description 决定了 Skill 能否被正确匹配，值得反复打磨。一个实用的迭代方法：

1. 写完初版 description 后，用不同的表述方式向 Agent 描述同一个需求
2. 观察 Agent 是否加载了你的 Skill
3. 如果没有匹配到，把用户的原始表述加入 Triggers on: 列表
4. 重复测试，直到覆盖大部分常见表述

比如一个关于表单验证的 Skill，用户可能会说：

• "帮我做表单校验"
• "怎么验证用户输入"
• "表单提交前检查"
• "input validation"
• "form validation pattern"

这些表述都应该被 Triggers on 覆盖到。

八、思考：资产化的深层价值

8.1 知识的"半衰期"问题

团队里的工程知识有一个隐性的半衰期——一个人离职，他脑子里的 50% 的隐性知识就丢失了；一个项目交接，能传递的经验可能不到 30%。

Skills 资产化的深层价值不在于"让 AI 更聪明"，而在于把团队知识从"存储在人脑中"变成"存储在可版本化、可审阅、可复用的资产中"。

这本质上是一种知识基建——短期看是在写文档，长期看是在建设团队的认知基底。

8.2 "写给 Agent 看"反过来提升了知识质量

一个有趣的副作用：当你尝试把一段经验写成 Skill 时，你会被迫把模糊的直觉变成精确的规则。

• "这个组件用起来有点坑" → 具体是哪些参数组合会出问题？
• "性能不好的时候试试虚拟列表" → 数据量超过多少条时推荐切换？
• "动效不要太多" → 具体的时长范围和缓动函数建议是什么？

写给 Agent 看的知识，因为需要精确和可执行，反而比写给人看的文档质量更高。

8.3 Skills 不是银弹

最后需要清醒地认识到 Skills 的边界：

• Skills 解决的是"操作性知识"的传递，不是"判断性知识"——何时用什么架构、如何权衡取舍，这些仍然需要人来决策
• Skills 的效果取决于 Agent 的基础能力——如果 Agent 本身对某个领域的理解很差，再好的 Skill 也只能有限提升
• 过度依赖 Skills 会导致"知其然不知其所以然"——对于学习阶段的开发者，理解原理比遵循规则更重要

Skills 是工具，不是目的。用好它的前提是清楚什么该交给 Agent，什么该留给人。

九、Quick Start：五分钟建立你的 Skills 仓库

如果你已经被说服，想开始建立自己的 Skills 仓库，这是最小启动步骤：

第一步：创建仓库

1mkdir my-skills && cd my-skills
2git init

第二步：建立目录结构

1mkdir -p frontend/ui-ux/skills

第三步：写你的第一个 Skill

1mkdir frontend/ui-ux/skills/my-first-skill

创建 SKILL.md：

1---
2name: my-first-skill
3description: >-
4  (描述这个 Skill 做什么，什么时候用)
5  Triggers on: "keyword1", "keyword2".
6---
7
8# Skill 标题
9
10一句话概述。
11
12## 核心原则
13
14- **必须**...
15- **禁止**...
16
17## 场景决策
18
19| 场景 | 推荐方案 |
20|---|---|
21| ... | ... |
22
23## 模板
24
25（代码示例）
26
27## 常见陷阱
28
29- ❌ ...
30- ✅ ...

第四步：安装到本地

1# 安装到当前项目
2npx skills add /path/to/my-skills
3
4# 或推送到 Git 后从远程安装
5npx skills add https://github.com/yourname/my-skills.git

第五步：验证

在 Cursor 中用自然语言描述一个与你的 Skill 相关的任务，观察 Agent 是否正确加载和遵循了你的 Skill。

从一个 Skill 开始，积累到十个、五十个——你的 Agent 会越来越像一个真正了解你的工作方式的搭档。

十、结语

回到开头的问题：那些你花了三年积累的工程经验，应该以什么形式存在？

不是 Wiki 里没人点开的一篇长文，不是 Notion 里逐渐过时的笔记，而是活在你的开发工具里、每次生成代码时都被自动引用的结构化资产。

Agent Skills 提供了这种可能性。它不完美，但方向是对的——把知识从人的记忆迁移到系统的能力中，让好的实践不依赖于"有人记得"，而是内嵌于"工具会做"。

这不是在替代开发者，而是在放大开发者的影响力。你的经验不再只能影响坐在你旁边的同事，而是能通过 Skills，影响每一个使用你的 Agent 的人。

这大概是"知识沉淀"最好的形态了。