Claude Skills 完全指南：从入门到精通

💡 01MVP 提示: 这是一篇系统性指南 (Guide)，旨在帮助你深入理解 Skills 的工作机制、最佳实践和生态系统。如果你只想快速上手，请查阅 Skills 快速上手 Cheatsheet。

Part 1: 理解 Skills

1.1 什么是 Skills？

Skills 是 AI Agent 的模块化能力包。

它不仅仅是一段 Prompt，而是一个包含指令 (Instructions)、脚本 (Scripts) 和 资源 (Resources) 的标准化文件夹。通过 Skills，你可以教 AI 如何使用 它所连接的工具，或者如何执行特定的工作流程 (SOP)。

1.2 核心三要素：Skills vs MCP vs Sub-agents

很多人容易混淆这三个概念，它们的区别在于角色分工：

概念	形象比喻	核心作用	典型场景	Token 消耗
MCP (Model Context Protocol)	发工具 (The Tools)	让 AI 连接外部世界（连数据库、读文件、调 API）。	"帮我查一下数据库里的销售额"	高 (预加载)
Skills	给说明书 (The Manual)	教 AI 怎么用工具（处理流程、SOP、格式规范）。	"按这个标准审查代码"、"按这个风格写文章"	低 (按需加载)
Sub-agents	派小弟 (The Worker)	派个分身去并行干活（独立会话，不干扰主线程）。	"去把整个仓库的代码都扫一遍，找出所有 Bug"	高 (独立会话)

为什么 Skills 很重要？

Token 效率: MCP 需要预加载所有工具定义，消耗大量 Token。Skills 采用渐进式披露 (Progressive Disclosure)，平时只加载极小的元数据，只有在需要时才展开完整内容。
标准化: 它是跨平台的。你在 Claude Code 里写的 Skill，稍作适配就能在 Cursor 或 Trae 中使用。

Part 2: 实战 Skills

2.1 安装与管理

推荐使用 eskill CLI 工具进行统一管理。

# 安装
npm install -g @empjs/skill

# 安装 Skill (支持 GitHub URL)
eskill add https://github.com/anthropics/skills/tree/main/skills/skill-creator

# 查看列表
eskill list

2.2 Skill 的解剖学：文件结构

一个标准的 Skill 文件夹结构如下：

my-skill/
├── SKILL.md          # [必需] 核心定义文件
├── scripts/          # [可选] 可执行脚本 (Python, Node, Bash)
│   └── process.py
├── references/       # [可选] 详细参考文档
│   └── guide.md
└── assets/           # [可选] 静态资源 (模板, 配置)
    └── template.json

核心文件：`SKILL.md`

这是 Skill 的大脑，必须包含 YAML Frontmatter 和 Markdown 主体。

---
name: code-reviewer               # 唯一 ID (小写, 无空格)
description: |                    # 触发机制 (Critical!)
  审查代码是否符合团队规范。
  使用场景：用户请求 review 代码、提交 PR 前、或提到“代码审查”时。
---

# Code Review Skill

当用户请求审查代码时，请遵循以下步骤：

## 1. 安全性检查
- 检查是否有硬编码的 Secrets。
- 检查是否有 SQL 注入风险。

## 2. 性能检查
- 检查是否有不必要的循环。
- 检查 React 组件是否过度渲染。

## 3. 脚本调用 (高级用法)
如果需要运行静态分析工具，请执行：
`python scripts/analyze.py --file <filename>`

2.3 如何编写高质量的 Description

description 字段决定了 AI 何时调用这个 Skill。写得不好，AI 就不会用。

❌ Bad: Review code (太短，AI 不知道具体什么时候用)
✅ Good: Review code for security vulnerabilities and performance issues. Use when user asks to 'review', 'check', or 'audit' code files. (明确了功能、场景和触发词)

Part 3: 最佳实践与生态

3.1 最佳实践 (Best Practices)

单一职责 (Single Responsibility):
- 不要做一个 "Super Skill" 包含所有功能。
- 拆分为 code-review, test-generator, doc-writer。AI 会根据需求自动组合调用它们。
脚本优于 Prompt (Scripts > Prompts):
- 如果任务是确定性的（比如格式化 JSON、上传图片），写成 Python/Node 脚本放在 scripts/ 里，让 AI 调用。
- 脚本执行结果准确、稳定，且不消耗推理 Token。
渐进式披露 (Progressive Disclosure):
- SKILL.md 只写核心流程（< 500 行）。
- 复杂的边缘情况、长文档放在 references/ 目录。AI 只有在觉得 SKILL.md 不够用时，才会去读 references。

3.2 安全注意事项

沙箱执行: 只要是脚本，就有风险。
审查来源: 不要随意安装来路不明的 Skill，特别是包含混淆脚本的。
敏感信息: 检查脚本是否会上传你的 ENV 变量或代码到外部服务器。

3.3 资源列表

资源	描述	链接
Anthropic Official	官方仓库，包含文档处理、搜索等基础 Skill	GitHub
Skills.sh	Vercel 推出的 Skill 商店，支持一键安装	Website
Awesome Claude Skills	社区维护的 Skill 列表	GitHub
Obra Superpowers	一套强大的开发工作流 Skills	GitHub

Part 4: 常见问题 (FAQ)

Q: 我可以用 Skills 来替代 MCP 吗？ A: 不能。如果你需要实时连接数据库或 API，还是需要 MCP。但你可以写一个 Skill 来封装 MCP 的调用流程。

Q: Skills 支持热更新吗？ A: 支持。在 Claude Code 2.1+ 和最新版 Trae/Cursor 中，修改 SKILL.md 后通常无需重启即可生效。

Q: 为什么我的 Skill 没被调用？ A: 检查 description。尝试增加更多相关的触发关键词。或者在对话中显式提到 Skill 的名字（如 @my-skill）。

Claude Skills 完全指南

On this page