一份能让 Claude Code / Cursor 通用的 Skill 该怎么写、去哪找

标准化之后的 Agent Skill，可能是今年 AI 编程里最值得认真了解的一件事。这篇把格式、原理、实战和资源一次讲透。

前言

如果你还在给每个项目手写一大坨 .cursorrules，或者每次开新会话都把同一套规范复制粘贴给 AI------是时候了解一下 Agent Skill 了。

Anthropic 在 2025 年 10 月推出了 Skill 机制，12 月把它作为开放标准发布。现在的局面是：一份 Skill 写好，Claude Code、Cursor、OpenAI Codex、Gemini CLI、Windsurf、GitHub Copilot 全都能用。这种跨工具通用性，是它和过去各家私有规则格式最大的区别。

下面从原理到实战，再到资源，完整过一遍。

---

一、Skill 的本质：一个文件夹 + 渐进式加载

很多人第一反应是"这不就是 Prompt 模板吗？" 不完全是。区别在于加载机制。

一个 Skill 本质上是一个文件夹：

my-skill/
├── SKILL.md          # 核心文件，必须有
├── reference.md      # 可选的参考文档
└── scripts/          # 可选的脚本
    └── helper.py

核心是 SKILL.md，结构如下：

---
name: React Best Practices
description: React 开发规范，涵盖组件设计、Hooks 使用与性能优化
---

# React 最佳实践

## 组件设计
- 优先使用函数组件 + Hooks
- 单个组件不超过 200 行，超了就拆

## 性能优化
- 列表渲染必须加 key
- 昂贵计算用 useMemo 包裹
...

关键在于它的**渐进式加载（progressive disclosure）**机制：

会话开始时，AI 只读取每个 Skill 的 name 和 description（约 100 token/个）。只有当它判断当前任务需要某个 Skill 时，才会把完整的 SKILL.md 正文（通常控制在 5000 token 以内）加载进上下文。

这个设计很关键。它意味着你可以挂载几十个 Skill 而不会撑爆上下文 ------平时只占名字和描述的开销，按需加载正文。对比把所有规则硬塞进 CLAUDE.md 的老做法，上下文利用率高出一个量级。

所以写 description 时要特别用心：它是 AI 判断"要不要加载这个 Skill"的唯一依据。描述写得含糊，AI 就不知道该在什么时候用它。

---

二、为什么是"通用"的：开放标准的意义

Skill 能跨工具通用，是因为它的格式是开放标准，各家工具都按这个规范来读：

工具	Skill 存放位置
Claude Code	.claude/skills/<name>/SKILL.md
Cursor	.cursor/rules/*.mdc 或 .cursorrules
Codex / Gemini CLI / 其他	读 AGENTS.md 或各自约定目录

虽然存放位置略有差异，但 SKILL.md 这个文件本身的格式是统一的。这就带来一个实际好处：社区里大量 .cursorrules 可以直接转成 SKILL.md，反之亦然。GitHub 上已经有不少项目专门做这种转换（后面资源部分会提）。

---

三、手把手：写一个能用的 Skill

光看不练没用，我们写一个真正能跑的。假设你想让 AI 在写 Python 时始终遵循你团队的规范。

第一步：在项目根目录建目录

mkdir -p .claude/skills/python-style

第二步 ：写 SKILL.md

---
name: Python Team Style
description: 团队 Python 编码规范，写或改 Python 代码时遵循。涵盖类型注解、异常处理、日志、测试约定。
---

# Python 团队规范

## 类型注解
- 所有函数签名必须有类型注解
- 复杂类型用 typing，避免裸 dict/list

## 异常处理
- 禁止裸 except，必须捕获具体异常
- 对外接口的异常要转成业务异常再抛

## 日志
- 用 logging，不用 print
- 日志必须带上下文（请求 ID、用户 ID 等）

## 测试
- 新增函数必须配 pytest 单测
- 测试文件命名 test_<module>.py

第三步：让 AI 加载

重新进入 Claude Code，直接给它一个任务：

帮我写一个解析 CSV 并入库的函数

如果 description 写得好，AI 会自动判断这是 Python 任务，加载你的规范，生成的代码就会带类型注解、用 logging、配单测------全自动按你的标准来。

这才是 Skill 的真正价值：把团队经验固化成 AI 每次都遵守的标准。 不用每次提醒，不用反复 review 同样的问题。

写 Skill 的几个经验：

1. description 要写清楚"什么时候用" ，这是 AI 的加载依据
2. 正文控制在 5000 token 以内，太长会挤占上下文
3. 一个 Skill 只干一件事，别把 Python 规范和前端规范塞一起
4. 用祈使句，"必须""禁止""优先"比"建议""可以"对 AI 约束力强

---

四、去哪找现成的 Skill

自己写之前，先看看社区有没有现成的。英文社区资源很丰富，我用过觉得靠谱的：

1. [ComposioHQ/awesome-claude-skills] 最权威的索引型 repo，把 Skill 概念、官方文档、各类资源整理得很清楚。入门首选。

2. Anthropic 官方 Skills 官方维护，质量最高，格式最标准。文档处理、前端设计、PDF 操作等都有，适合当模板学。

3. [skills.sh]（Vercel 维护） 可搜索的 Skill 目录，按分类、作者、安装量筛选，比在 GitHub 里翻效率高。

4. antigravity-awesome-skills 号称 1400+ Skill，带 npm 安装器，量大管饱。

5. Mindrally/skills 把 240+ 个 Cursor rules 转成了 SKILL.md 格式，主流技术栈基本都有。

这些资源量大、更新快，但对中文开发者有几个现实问题：

• 几乎全英文：正文给 AI 看没问题，但"要不要装、干嘛用"的判断部分全英文，每次都得先读一遍
• 质量参差：repo 多到爆炸，有生产级精品，也有复制粘贴的水货，甚至混着跑不起来的"meta-skill 框架"，没有筛选机制
• 安装方式不统一 ：有的 cp -r，有的 npx，有的给脚本，新手容易懵

---

五、中文开发者的资源选择

中文社区在 Skill 这块还比较早期。除了在公众号、掘金上零散找博主的自译版，或者自己把英文 Skill 丢给 AI 翻译，目前有专门做中文化整理的平台。

我最近在用的是 技集 JijiHub（jijihub.com） ，正好对应上面几个痛点：

• 中文化描述：每个 Skill 配 AI 翻译的中文版，能做什么、适合什么场景，中文写得清楚，不用先啃英文判断
• 安全评分 + 质量评测：按发现性、实用性、规范性、专业性几个维度打分，再加安全评分。前面说的"meta-skill 混进来跑不起来"那种坑，靠评分能过滤掉一部分
• 双格式下载 ：同一个 Skill 同时提供 Claude Code 的 SKILL.md 和 Cursor 的 .cursorrules，不用自己手动转
• 集合包：把同类 Skill 打包（比如前端全家桶），一次性下载

实话实说它也有局限：作为中文化平台，收录速度肯定比不上英文社区的更新节奏；个别 Skill 的中文翻译偏精简，复杂内容还是建议对照英文原版。但作为中文开发者快速筛选的第一站，比直接在英文 GitHub 里大海捞针舒服。

它的内容大多也是从开源 Skill 整理来的，所以英文社区的好东西过段时间在上面大概率能找到中文版。英文社区做补充，中文平台做筛选，搭配着用体验最好。

---

六、安装速查

不管从哪拿的 Skill，安装就这么几步：

Claude Code

# 项目级
mkdir -p .claude/skills/my-skill
cp downloaded/SKILL.md .claude/skills/my-skill/

# 全局（所有项目可用）
mkdir -p ~/.claude/skills/my-skill
cp downloaded/SKILL.md ~/.claude/skills/my-skill/

Cursor

# 放到项目根目录
cp downloaded.cursorrules .cursorrules
# 或新格式
mkdir -p .cursor/rules
cp downloaded.mdc .cursor/rules/my-skill.mdc

装完直接问 AI "你现在加载了哪些 skill"，或给它一个相关任务验证是否自动调用。

---

\])总结 Skill 标准化是个分水岭。过去各家工具的规则格式互不兼容，写一套只能用一个工具；现在一份 Skill 全家通用，社区资源也开始指数级增长。 对开发者来说，值得做两件事： 1. **建立自己的 Skill 库**：把团队规范、常用工作流写成 Skill，让 AI 每次都按你的标准来 2. **善用社区资源**：英文社区找最新最全，中文平台（如 JijiHub）做快速筛选和本地化 未来跟 AI 协作，拼的不是 prompt 写得多花，而是谁的 Skill 库更顺手、更贴合自己的工作流。 *** ** * ** *** 如果这篇有帮助，点个赞 / 收藏。后面我会写一篇 **《把团队规范写成 Skill：一个真实项目的完整实践》** ，用具体案例讲怎么把现有的代码规范、CI 流程、Code Review 清单全部 Skill 化。有问题评论区见。 *** ** * ** *** *文中资源均为实际使用，无商业合作。AI 工具迭代很快，具体功能以各平台最新版本为准。*