Claude Code与Cursor通用技能编写指南：2024精选资源与实战教程

如果你还在为每个项目手动编写冗长的 .cursorrules，或者每次开启新的AI会话都要重复粘贴同一套规范——那么，是时候掌握 Agent Skill 了。

这项由 Anthropic 在 2025 年 10 月推出、并于 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 在初始化时，仅读取文件头部的元信息（name 和 description）。只有当判定当前任务与该 Skill 描述高度相关时，才会将正文部分加载到上下文中。

这一设计极为巧妙。它意味着你可以在项目中配置数十个 Skill，而不会耗尽有限的上下文窗口——平时它们仅占用名称和描述的基础开销，仅在需要时加载详细内容。相比过去将所有规则硬塞进一个 CLAUDE.md 文件的老方法，上下文利用率获得了数量级的提升。

因此，编写 description 时需要格外精准：它是 AI 判断“是否加载此 Skill”的唯一依据。描述模糊，AI 便无法准确调用。

二、为何能“通用”：开放标准的价值

Skill 之所以能跨工具通用，根本原因在于它是一套开放标准。各工具均遵循同一规范读取，尽管存放路径略有差异：

这种统一性带来了一个切实的好处：社区中现存的大量 .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_.py

第三步：验证与使用。

重新进入 Claude Code，直接交付一个任务，例如：“帮我编写一个解析 CSV 并入库的函数”。

如果之前的 description 撰写足够精准，AI 会自动识别此为 Python 任务，从而加载你定义的规范。最终生成的代码将自动包含类型注解、使用 logging 模块、并考虑 pytest 单测——完全遵循你设定的标准执行。

这正是 Skill 的核心价值：将团队积累的开发经验固化为 AI 每次协作时自动执行的“肌肉记忆”。 从此，你无需反复提醒，也不必重复审查那些本应由规范杜绝的共性问题。

以下是几条来自实践的经验：

1. description 必须清晰界定“使用场景”，这是 AI 加载决策的依据。
2. 正文内容控制在 5000 token 以内，过长会过度挤占宝贵的上下文空间。
3. 遵循单一职责原则，一个 Skill 只专注解决一类问题，避免将 Python 规范与前端规范混杂。
4. 使用祈使句和明确指令，如“必须”、“禁止”、“优先”等词汇，比“建议”、“可以”对 AI 的约束力更强。

四、如何寻找现成的 Skill

在动手编写之前，不妨先探索社区中是否有现成的资源。英文社区的生态已相当丰富，以下几个是经过验证的优质资源：

1. ComposioHQ/awesome-claude-skills：目前最权威的索引型仓库，将 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 格式，主流技术栈基本覆盖。

这些资源虽然丰富且更新迅速，但对于中文开发者而言，也存在几个现实问题：

• 几乎全英文：Skill 正文供 AI 阅读没问题，但决定“是否安装、用于何处”的描述信息全是英文，每次都需要额外阅读理解。
• 质量参差不齐：仓库数量爆炸，其中既有生产级的精品，也有简单复制粘贴的“水货”，甚至混杂着一些无法直接运行的“元 Skill 框架”，缺乏有效的筛选机制。
• 安装方式不统一：有的需要 cp -r 手动复制，有的提供 npx 安装脚本，对于新手容易造成困惑。

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

目前，中文社区在 Skill 领域的生态尚处于早期阶段。除了在技术博客或论坛上寻找零散的翻译版本，或者自行用 AI 翻译英文 Skill 外，也开始出现一些专门进行中文化整理和分发的平台。

例如，技集 JijiHub 这类平台，正针对上述痛点提供解决方案：

• 中文化描述：每个 Skill 都配备了 AI 翻译的中文版本，功能、适用场景用中文清晰描述，无需先啃英文原版再做判断。
• 安全评分与质量评测：平台会从发现性、实用性、规范性、专业性等维度对 Skill 进行打分，并附加安全评分。这能在一定程度上过滤掉那些滥竽充数或存在风险的“元 Skill”。
• 双格式下载：同一个 Skill 同时提供适用于 Claude Code 的 SKILL.md 格式和适用于 Cursor 的 .cursorrules 格式，省去了手动转换的麻烦。
• 集合包：将同类型的 Skill（例如前端开发全家桶）打包提供，支持一次性下载和部署。

客观而言，这类平台也有其局限性：作为中文化平台，其收录速度很难跟上英文社区日新月异的更新节奏；个别 Skill 的中文翻译可能较为精简，对于复杂内容，仍建议对照英文原版以确保准确性。但作为中文开发者进行快速筛选和获取本地化资源的“第一站”，其体验远比在浩瀚的英文 GitHub 中大海捞针要友好得多。

六、安装速查

无论从哪里获取 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

# 传统 .cursorrules 格式
cp downloaded.cursorrules .cursorrules

# 或新的 .mdc 格式
mkdir -p .cursor/rules
cp downloaded.mdc .cursor/rules/my-skill.mdc

安装完成后，可以直接询问 AI “你现在加载了哪些 skill？”，或者交付一个相关任务，观察其输出是否符合 Skill 中的规范，以此验证安装是否成功。

总结

Skill 的标准化是一个重要的分水岭。过去，各家AI编程工具的规则格式互不兼容，编写一套规则往往只能用于单一工具；现在，一份 Skill 可以实现全家桶通用，社区的共享资源也正在呈现指数级增长。

对于开发者而言，当下有两件事值得投入：

1. 着手建立自己的 Skill 库：将团队的编码规范、常用工作流、最佳实践沉淀为 Skill，让 AI 成为你团队标准的坚定执行者。
2. 善用社区资源：在英文社区寻找最新、最全的原始素材，同时利用好中文平台进行快速筛选和本地化，提升获取效率。

展望未来，与 AI 协作的效率竞争，将不再仅仅取决于谁写的 Prompt 更精巧，而更多地取决于谁的 Skill 库更贴合实际工作流、用起来更得心应手。