Claude Skills 完全指南：从零开始创建你的第一个 AI 技能

让 Claude 学会你的工作流程，打造专属的 AI 助手

什么是 Claude Skills？

想象一下，你可以给 Claude 一本"操作手册"，教它如何按照你的标准完成特定任务。这就是 Claude Skills 的核心理念。

Claude Skills 是一种模块化的能力扩展系统，它允许你通过简单的 Markdown 文件，配合可选的脚本和资源，来教会 Claude 执行专业化的任务。无论是遵循公司的品牌规范、生成特定格式的报告，还是与专有 API 交互，Skills 都能让 Claude 成为你领域内的专家。

Skills 的独特优势

渐进式加载 - Claude 只在需要时才加载技能内容，不会占用过多上下文窗口
可重用性 - 一次编写，随时调用，无需重复说明
专业化 - 将通用 AI 转变为领域专家
可分享 - 团队成员可以共享和复用相同的工作流程

Skills 的基本结构

一个完整的 Skill 由以下部分组成：


展开代码
my-skill/
├── SKILL.md              # 必需：技能定义文件
├── scripts/              # 可选：可执行脚本
│   └── process.py
├── references/           # 可选：参考文档
│   └── api_docs.md
└── assets/              # 可选：资源文件
    └── template.html

核心文件：SKILL.md

这是唯一必需的文件，包含两个部分：

1. YAML 前置元数据（Frontmatter）

yaml
展开代码
---
name: skill-name
description: 清晰描述技能的功能和使用场景
---

2. Markdown 正文 包含具体的操作指令、工作流程和最佳实践。

从零开始：创建你的第一个 Skill

让我们通过一个实际例子来学习如何创建 Skill。

场景：代码审查助手

假设你的团队需要一个能够按照公司标准进行代码审查的助手。

步骤 1：明确需求

首先问自己几个问题：

这个 Skill 要做什么？ → 审查代码质量、检查安全问题、确保遵循编码规范
何时应该触发？ → 当用户说"审查这段代码"、"code review"或提到"检查代码"时
需要哪些信息？ → 公司的编码规范、常见问题清单

步骤 2：设计技能结构

基于需求，我们决定：

将编码规范存储在 references/coding-standards.md
创建一个检查脚本 scripts/lint_check.py
在 SKILL.md 中编写审查流程

步骤 3：编写 SKILL.md

markdown
展开代码
---
name: code-review-assistant
description: Performs code reviews following company standards. Use when the user asks to review code, check code quality, or mentions code review. Checks for security issues, style violations, and best practices.
---

# Code Review Assistant

## 审查流程

当用户请求代码审查时，按以下步骤进行：

### 1. 初步分析
- 识别编程语言和框架
- 了解代码的主要功能

### 2. 检查清单

#### 安全性
- [ ] 是否存在 SQL 注入风险
- [ ] 是否正确处理用户输入
- [ ] 敏感数据是否加密

#### 代码质量
- [ ] 函数是否过长（超过 50 行）
- [ ] 是否有重复代码
- [ ] 命名是否清晰

#### 性能
- [ ] 是否存在明显的性能瓶颈
- [ ] 数据库查询是否优化

### 3. 参考公司规范

查看 `references/coding-standards.md` 了解详细的编码标准。

### 4. 生成报告

使用以下格式输出审查结果：

**总体评分**: [优秀/良好/需改进]

**发现的问题**:
1. [问题描述] - 严重性: [高/中/低]
   - 位置: 第 X 行
   - 建议: [具体改进建议]

**优点**:
- [列出代码的优点]

**改进建议**:
- [按优先级排序的改进建议]

## 运行静态分析

如果代码是 Python，运行 linting 检查：

```bash
python scripts/lint_check.py <文件路径>

注意事项

保持建设性和友好的语气
优先指出安全问题
提供具体的代码示例说明如何改进

步骤 4：添加参考文档

创建 references/coding-standards.md：

markdown
展开代码
# 公司编码规范

## Python 规范

### 命名约定
- 变量：snake_case
- 类名：PascalCase
- 常量：UPPER_CASE
- 私有变量：_leading_underscore

### 函数规范
- 每个函数必须有 docstring
- 函数长度不超过 50 行
- 单一职责原则

### 安全规范
- 永远不要使用 `eval()`
- 使用参数化查询防止 SQL 注入
- 敏感配置存储在环境变量中

## JavaScript 规范

### 使用 ESLint
- 配置: .eslintrc.json
- 规则: Airbnb style guide

### 异步处理
- 优先使用 async/await
- 正确处理错误（try/catch）

步骤 5：创建实用脚本

创建 scripts/lint_check.py：

python
展开代码
#!/usr/bin/env python3
"""
简单的 Python linting 检查工具
"""
import sys
import re
from pathlib import Path

def check_file(filepath):
    """检查 Python 文件的基本质量问题"""
    issues = []
    
    with open(filepath, 'r', encoding='utf-8') as f:
        lines = f.readlines()
    
    for i, line in enumerate(lines, 1):
        # 检查行长度
        if len(line.rstrip()) > 100:
            issues.append(f"第 {i} 行: 行长度超过 100 字符")
        
        # 检查是否使用了 eval
        if 'eval(' in line:
            issues.append(f"第 {i} 行: 安全警告 - 使用了 eval()")
        
        # 检查是否有多余的空白
        if line.endswith(' \n') or line.endswith('\t\n'):
            issues.append(f"第 {i} 行: 行尾有多余空白")
    
    return issues

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("用法: python lint_check.py <文件路径>")
        sys.exit(1)
    
    filepath = Path(sys.argv[1])
    if not filepath.exists():
        print(f"错误: 文件 {filepath} 不存在")
        sys.exit(1)
    
    issues = check_file(filepath)
    
    if issues:
        print(f"发现 {len(issues)} 个问题:\n")
        for issue in issues:
            print(f"  - {issue}")
    else:
        print("✓ 未发现明显问题")

编写高质量 Skill 的核心原则

1. 描述字段是关键

description 字段决定 Claude 何时使用你的 Skill。一个好的描述应该：

✅ 好的描述示例：

yaml
展开代码
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

这个描述清楚地说明了：

功能：提取文本、填表、合并文档
触发词：PDF、forms、document extraction

❌ 不好的描述示例：

yaml
展开代码
description: Helps with documents

太模糊，Claude 无法判断何时使用。

2. 保持简洁原则

上下文窗口是珍贵资源。记住：Claude 已经很聪明了，只添加它不知道的信息。

问自己：

Claude 真的需要这个解释吗？
这段文字值得占用这么多 tokens 吗？

优先使用：

简洁的代码示例而非冗长的解释
要点列表而非段落说明
参考文件而非在 SKILL.md 中堆砌所有内容

3. 设置适当的自由度

根据任务的复杂度选择约束程度：

自由度	适用场景	实现方式
高	多种方法都可行	文本指令 + 指导原则
中	有首选模式但允许变化	伪代码 + 可配置参数
低	操作容易出错，需要精确执行	具体脚本 + 少量参数

示例：

高自由度（创意写作）：

markdown
展开代码
## 写作指南
- 保持友好、专业的语气
- 使用具体例子说明观点
- 段落长度适中（3-5 句）

低自由度（数据库操作）：

markdown
展开代码
## 数据库查询流程
1. 运行 `scripts/validate_query.py` 验证查询安全性
2. 仅使用参数化查询
3. 设置查询超时：30秒
4. 记录所有查询到日志

4. 渐进式披露

利用 Skills 的三级加载机制：

级别 1 - 元数据（总是加载）

yaml
展开代码
name: pdf-processor
description: Process PDF files...

约 100 tokens

级别 2 - SKILL.md 正文（触发后加载） 主要工作流程和指令约 2,000-5,000 tokens

级别 3 - 额外资源（按需加载）

markdown
展开代码
## 高级功能
- 表单填写：查看 [FORMS.md](FORMS.md)
- API 参考：查看 [REFERENCE.md](REFERENCE.md)

按需加载，无限制

最佳实践：

SKILL.md 保持在 500 行以内
将详细文档移至 references/
在 SKILL.md 中明确引用这些文件

实战技巧

技巧 1：使用脚本提高效率

何时使用脚本：

同样的代码需要反复重写
操作需要确定性和可靠性
复杂的数据处理或转换

示例：PDF 旋转

不使用脚本：

markdown
展开代码
使用 PyPDF2 旋转 PDF：
1. 导入库
2. 打开文件
3. 旋转每一页
4. 保存文件

每次 Claude 都要重写代码，容易出错。

使用脚本：

markdown
展开代码
运行 `scripts/rotate_pdf.py <文件> <角度>`

确定性执行，token 高效。

技巧 2：善用 assets 目录

何时使用 assets：

模板文件（HTML、React 样板）
品牌资源（logo、字体）
示例文档

示例：前端开发 Skill


展开代码
frontend-builder/
├── SKILL.md
└── assets/
    ├── react-template/
    │   ├── index.html
    │   ├── app.jsx
    │   └── styles.css
    └── logo.svg

在 SKILL.md 中引用：

markdown
展开代码
## 创建新项目
1. 复制 `assets/react-template/` 作为起点
2. 替换 logo 为 `assets/logo.svg`
3. 根据需求定制

技巧 3：处理多种变体

当 Skill 支持多个框架或选项时：

在 SKILL.md 中：

markdown
展开代码
# 数据库查询 Skill

## 支持的数据库
- PostgreSQL - 查看 [references/postgres.md](references/postgres.md)
- MySQL - 查看 [references/mysql.md](references/mysql.md)
- MongoDB - 查看 [references/mongodb.md](references/mongodb.md)

## 基本流程
1. 识别数据库类型
2. 阅读对应的参考文档
3. 构建查询
4. 验证结果

在 references/ 中：每个数据库的详细文档，只在需要时加载。

常见问题与解决方案

Q1: 我的 Skill 没有被触发怎么办？

检查清单：

描述是否足够具体？包含触发关键词了吗？
文件路径正确？必须是 SKILL.md（区分大小写）
YAML 格式正确？使用 YAML 验证器检查

改进描述：

yaml
展开代码
# ❌ 太模糊
description: Helps with code

# ✅ 清晰明确
description: Reviews Python code for security vulnerabilities and style issues. Use when the user asks to review code, check code quality, or mentions code review.

Q2: 如何测试我的 Skill？

创建测试用例：列出典型的用户请求
验证触发：确保 Skill 在正确的场景下触发
检查输出：输出是否符合预期质量
迭代改进：根据实际使用情况调整

测试示例：

markdown
展开代码
测试用例：
1. "请审查这段 Python 代码" → 应该触发
2. "帮我写一段代码" → 不应该触发
3. "code review needed" → 应该触发

Q3: Skill 太长怎么办？

策略：

评估每个部分：是否真的需要？
使用 references/：移动详细文档
简化说明：用示例代替长篇解释
拆分 Skill：如果功能差异大，考虑创建多个 Skills

重构示例：

Before (all in SKILL.md - 800 lines):

markdown
展开代码
# API Integration

## REST API 使用
[100 行详细说明]

## GraphQL 使用
[100 行详细说明]

## 认证方式
[200 行文档]
...

After (SKILL.md - 200 lines):

markdown
展开代码
# API Integration

## 快速开始
基本 REST 调用示例...

## 详细文档
- REST API: 查看 [references/rest.md](references/rest.md)
- GraphQL: 查看 [references/graphql.md](references/graphql.md)
- 认证: 查看 [references/auth.md](references/auth.md)

高级模式

模式 1：多步骤工作流

适用于复杂的、顺序敏感的流程。

markdown
展开代码
# 部署工作流

## 部署检查清单

### 阶段 1：预部署验证
- [ ] 运行 `scripts/pre_deploy_check.py`
- [ ] 检查环境变量配置
- [ ] 确认数据库迁移脚本

### 阶段 2：构建
- [ ] 运行测试套件
- [ ] 构建 Docker 镜像
- [ ] 标记版本号

### 阶段 3：部署
- [ ] 部署到 staging
- [ ] 运行冒烟测试
- [ ] 检查日志无错误

### 阶段 4：部署到生产
- [ ] 获得批准
- [ ] 执行蓝绿部署
- [ ] 监控指标

### 阶段 5：验证
- [ ] 健康检查通过
- [ ] 运行回归测试
- [ ] 通知团队

## 回滚程序
如果任何阶段失败：
```bash
scripts/rollback.sh <版本号>


展开代码

### 模式 2：条件逻辑

处理不同场景的分支逻辑。

```markdown
# 文档生成器

## 确定文档类型

询问用户文档类型：
- **API 文档** → 使用 `references/api-template.md`
- **用户指南** → 使用 `references/user-guide-template.md`
- **技术规范** → 使用 `references/tech-spec-template.md`

## 生成流程

IF 文档类型 == "API 文档":
  1. 扫描代码注释
  2. 提取 API 端点
  3. 应用 API 模板
  
ELSE IF 文档类型 == "用户指南":
  1. 识别用户角色
  2. 创建功能清单
  3. 应用用户指南模板
  
ELSE:
  1. 收集技术需求
  2. 应用技术规范模板

模式 3：模板和示例

提供具体的输出格式。

markdown
展开代码
# 邮件生成器

## 输出模板

### 专业商务邮件

主题：[简洁、行动导向的主题]

[收件人姓名]，

[开场问候 - 1 句]

[背景/目的 - 1-2 句]

[主要内容 - 2-3 段]

要点 1
要点 2
要点 3

[行动号召 - 1 句]

[结束语]

[你的名字]


展开代码

### 示例
查看 `references/email-examples.md` 了解不同场景的示例。

真实案例学习

案例 1：品牌规范 Skill

需求：确保所有生成的内容符合公司品牌标准

解决方案：


展开代码
brand-guidelines/
├── SKILL.md
├── assets/
│   ├── logo.svg
│   ├── colors.json
│   └── fonts/
└── references/
    ├── tone-of-voice.md
    └── visual-guidelines.md

SKILL.md 片段：

markdown
展开代码
---
name: brand-guidelines
description: Ensures content follows company brand guidelines. Use when creating marketing materials, documents, or any branded content.
---

# 品牌规范

## 视觉元素
- **Logo**: 使用 `assets/logo.svg`
- **配色方案**: 查看 `assets/colors.json`
- **字体**: `assets/fonts/` 目录

## 内容基调
参考 `references/tone-of-voice.md`：
- 友好但专业
- 避免行话
- 积极向上

## 检查清单
生成内容前检查：
- [ ] 使用正确的 logo
- [ ] 颜色符合品牌色板
- [ ] 语气符合品牌调性
- [ ] 包含必要的法律声明

案例 2：数据分析 Skill

需求：标准化数据分析流程和报告格式

解决方案：


展开代码
data-analysis/
├── SKILL.md
├── scripts/
│   ├── clean_data.py
│   ├── generate_stats.py
│   └── create_visualizations.py
└── references/
    ├── statistical-methods.md
    └── visualization-best-practices.md

SKILL.md 片段：

markdown
展开代码
---
name: data-analysis
description: Performs structured data analysis with statistical methods and visualizations. Use when analyzing datasets, generating reports, or creating data-driven insights.
---

# 数据分析工作流

## 步骤 1：数据清洗
```bash
python scripts/clean_data.py <input.csv> <output.csv>

检查：

缺失值
异常值
数据类型

步骤 2：探索性分析

运行描述性统计：

bash
展开代码
python scripts/generate_stats.py <data.csv>

查看 references/statistical-methods.md 选择合适的分析方法。

步骤 3：可视化

bash
展开代码
python scripts/create_visualizations.py <data.csv> <output_dir>

参考 references/visualization-best-practices.md。

步骤 4：生成报告

报告结构

执行摘要 (1 页)
- 关键发现
- 主要建议
数据概览
- 数据源
- 样本大小
- 时间范围
详细分析
- 统计结果
- 可视化图表
- 解读
结论与建议


展开代码

---

## 最佳实践总结

### ✅ 应该做的

1. **清晰的描述**：包含功能说明和触发关键词
2. **简洁至上**：质疑每一行内容的必要性
3. **使用示例**：示例胜过千言万语
4. **测试脚本**：确保所有脚本都能正常运行
5. **引用资源**：明确告诉 Claude 何时查看哪个文件
6. **版本控制**：记录重要变更

### ❌ 不应该做的

1. **避免模糊描述**："帮助处理文档"太宽泛
2. **不要过度说明**：假设 Claude 已有基础知识
3. **避免重复**：信息应该只存在一处
4. **不要创建不必要的文件**：README、CHANGELOG 等对 AI 无用
5. **避免硬编码**：使用参数而非固定值
6. **不要忽略测试**：未测试的 Skill 可能会失败

---

## 进阶主题

### 与 MCP（Model Context Protocol）结合

Skills 和 MCP 可以完美配合：

- **Skills**：定义如何完成任务
- **MCP**：提供外部数据和 API 访问

**示例**：客户支持 Skill
```markdown
# 客户支持助手

## 查询客户信息
使用 MCP 的 CRM 集成获取：
- 客户历史记录
- 订单状态
- 支持工单

## 响应流程
1. 通过 MCP 查询客户数据
2. 应用 `references/response-templates.md` 中的模板
3. 根据问题类型调整语气
4. 记录交互到 CRM（通过 MCP）

团队协作

分享 Skills：

Git 仓库：将 Skills 目录提交到版本控制
内部市场：建立团队 Skills 库
文档规范：制定团队 Skill 编写标准

组织结构：


展开代码
team-skills/
├── engineering/
│   ├── code-review/
│   ├── deployment/
│   └── testing/
├── marketing/
│   ├── content-creation/
│   └── campaign-planning/
└── sales/
    ├── proposal-generation/
    └── customer-analysis/

下一步行动

立即开始

识别重复任务：找出你经常重复执行的工作流程
创建第一个 Skill：从简单的开始，比如格式化输出
迭代改进：根据实际使用反馈优化
分享经验：与团队分享你的 Skills

学习资源

官方文档：docs.claude.com/en/docs/claude-code/skills
GitHub 仓库：github.com/anthropics/skills
社区集合：github.com/travisvn/awesome-claude-skills
工程博客：anthropic.com/news/skills

灵感来源

浏览 Anthropic 的官方 Skills 示例：

docx - Word 文档处理
pptx - PowerPoint 生成
pdf - PDF 操作
xlsx - Excel 表格处理
frontend-design - 前端设计
mcp-builder - 创建 MCP 服务器

结语

Claude Skills 将 AI 从"通用助手"转变为"领域专家"。通过精心设计的 Skills，你可以：

节省时间：一次编写，永久使用
保证质量：确保输出符合标准
知识传承：将专业知识固化为可复用的资源
赋能团队：让每个人都能访问专业工作流程

开始创建你的第一个 Skill，让 Claude 真正成为你的专属 AI 助手！