Claude Code Skills 完全指南

掌握模块化能力扩展的核心机制

核心机制: 模型自主调用 | 配置方式: SKILL.md + 资源文件 | 应用场景: 专业领域知识、复杂工作流、团队协作

🎯 什么是 Claude Skills?

Claude Skills 是包含指令、脚本和资源的模块化能力包,让 Claude 能够在相关任务时自动识别并使用专业知识。

核心特性

正在加载图表...

Skills vs 其他机制

Skills 与其他功能的对比:

特性SkillsSlash CommandsHooksMCP Tools
调用方式模型自主用户手动事件触发模型调用
适用场景复杂工作流快速操作自动化检查外部集成
配置复杂度中等低中等高
可移植性跨平台Claude CodeClaude Code需服务器
执行时机智能判断立即执行生命周期按需调用

设计哲学: “Skills 用于打包专业知识和复杂流程,让 Claude 在需要时自动获得超能力”

🏗️ Claude Skills 系统架构

整体架构图

正在加载图表...

📁 Skill 存储位置

三种存储层级

正在加载图表...

目录结构示例

# 个人 Skills
~/.claude/skills/
├── my-workflow/
│   ├── SKILL.md
│   ├── reference.md
点击展开查看完整代码共 32 行

📝 SKILL.md 文件结构

完整格式说明

---
name: skill-name
description: 描述这个 Skill 做什么以及何时使用它
allowed-tools: Read,Write,Bash  # 可选:限制工具访问
tags:                            # 可选:分类标签
点击展开查看完整代码共 26 行

YAML Frontmatter 字段详解

1. name (必需)

格式要求:

  • 只能包含小写字母、数字和连字符
  • 最大长度 64 字符
  • 使用动名词形式(gerund): processing-pdfs, analyzing-data

示例:

name: code-review-helper
name: api-documentation-generator
name: database-schema-validator

2. description (必需)

关键要求:

  • 必须说明做什么 AND 何时使用
  • 最大长度 1024 字符
  • 使用第三人称: “Processes…” 而非 “I can process…”
  • 包含具体触发场景

好的 description:

# ✅ 明确功能和触发条件
description: Analyzes Excel spreadsheets and generates pivot tables when the user asks to summarize or analyze tabular data from .xlsx files

# ✅ 指定使用场景
description: Reviews pull request code for security vulnerabilities and performance issues when analyzing Git diffs or reviewing code changes

不好的 description:

# ❌ 过于笼统
description: Helps with data

# ❌ 没有触发条件
description: Processes Excel files

# ❌ 第一人称
description: I can help you analyze spreadsheets

3. allowed-tools (可选)

用途: 限制 Skill 可以使用的工具,提高安全性

格式: 逗号分隔的工具列表

示例:

# 只读 Skill
allowed-tools: Read,Glob,Grep

# 代码分析 Skill
allowed-tools: Read,Bash(eslint *),Bash(prettier --check *)

# 完全访问(默认)
# 不指定 allowed-tools 字段

工具名称:

  • Read - 读取文件
  • Write - 写入文件
  • Edit - 编辑文件
  • Glob - 文件模式匹配
  • Grep - 内容搜索
  • Bash - Shell 命令
  • Bash(command) - 特定命令

4. tags (可选)

用途: 分类和组织 Skills

示例:

tags:
  - testing
  - automation
  - typescript

🔄 Skills 工作流程

Skill 调用流程

正在加载图表...

渐进式披露机制

正在加载图表...

🚀 创建 Skill 实战

步骤 1: 规划 Skill

正在加载图表...

步骤 2: 创建目录结构

# 1. 决定存储位置
# 个人使用
mkdir -p ~/.claude/skills/my-skill

# 团队共享
点击展开查看完整代码共 23 行

步骤 3: 编写 SKILL.md

---
name: code-review-checklist
description: Performs comprehensive code review following team standards when analyzing pull requests or reviewing code changes, checking for security, performance, maintainability, and style issues
allowed-tools: Read,Grep,Bash(git diff *)
tags:
点击展开查看完整代码共 83 行

步骤 4: 添加参考资料

# Code Review Reference Guide

## Security Vulnerability Patterns

### SQL Injection
点击展开查看完整代码共 54 行

步骤 5: 添加示例

# Code Review Examples

## Example 1: Simple Feature Addition

**Input:** Review PR adding user profile editing
点击展开查看完整代码共 71 行

📚 实战示例库

示例 1: Excel 分析 Skill

---
name: excel-analyzer
description: Analyzes Excel spreadsheets and generates insights including summary statistics, pivot tables, and data visualizations when the user asks to analyze or summarize .xlsx files
allowed-tools: Read,Bash(python *)
tags:
- data-analysis
- excel
- automation
---

# Excel Analyzer

## Overview
Analyzes Excel files to extract insights, generate statistics, and create summaries.
点击展开查看完整代码共 92 行

示例 2: API 文档生成 Skill

---
name: api-docs-generator
description: Generates comprehensive API documentation from TypeScript code when the user asks to document API endpoints or create API reference documentation
allowed-tools: Read,Write,Grep
tags:
- documentation
- api
- typescript
---

# API Documentation Generator

## Overview
Automatically generates API documentation from TypeScript source files.
点击展开查看完整代码共 118 行

示例 3: 测试生成 Skill

---
name: test-generator
description: Generates comprehensive unit tests for TypeScript/JavaScript code when the user asks to create tests or improve test coverage
allowed-tools: Read,Write
tags:
- testing
- jest
- typescript
---

# Test Generator

## Overview
Automatically generates unit tests following best practices and achieving high coverage.
点击展开查看完整代码共 152 行

🎓 最佳实践

15 条黄金法则

正在加载图表...

Skill 编写检查清单

✅ 元数据检查

  • name 使用 gerund 形式(processing-data)
  • name 只包含小写、数字、连字符
  • description 说明”做什么”和”何时用”
  • description 使用第三人称
  • description 包含具体触发场景
  • 如需限制,设置 allowed-tools
  • 添加相关 tags

✅ 内容质量

  • SKILL.md < 500 行
  • 包含 Overview 部分
  • 步骤清晰可执行
  • 提供具体示例
  • 说明输出格式
  • 包含最佳实践
  • 错误处理说明

✅ 文件组织

  • 详细内容放在 reference.md
  • 示例放在 examples.md
  • 脚本放在 scripts/ 目录
  • 避免嵌套引用(最多一层)

✅ 测试验证

  • 在 Haiku 上测试
  • 在 Sonnet 上测试
  • 在 Opus 上测试
  • 测试边界情况
  • 测试错误处理
  • 验证输出格式

✅ 团队协作

  • 添加 README 说明
  • 文档变更记录
  • 提交到项目 Git
  • 团队成员审查

🔧 调试与优化

常见问题排查

正在加载图表...

性能优化技巧

1. 控制文件大小

<!-- ❌ 不好: SKILL.md 包含所有内容 -->
---
name: my-skill
description: ...
---

# My Skill

## Instructions
[500+ lines of detailed instructions]

## Examples
[200 lines of examples]

## Reference
[300 lines of reference material]
<!-- ✅ 好: 拆分内容 -->
---
name: my-skill
description: ...
---

# My Skill

## Instructions
[Core instructions < 100 lines]

For detailed reference, see [reference.md](./reference.md)
For examples, see [examples.md](./examples.md)

2. 使用脚本处理确定性任务

<!-- ❌ 让 Claude 处理复杂计算 -->
## Instructions
Calculate the SHA256 hash of each file and compare with expected values...

<!-- ✅ 使用脚本 -->
## Instructions
Run the verification script:
\`\`\`bash
python scripts/verify_hashes.py
\`\`\`

3. 优化 description 匹配

# ❌ 过于宽泛
description: Helps with data analysis

# ✅ 具体场景
description: Analyzes CSV and Excel files to generate statistical summaries and visualizations when the user requests data analysis or asks to summarize tabular data

🌐 Skills 生态系统

官方 Skills

📄 Document Skills

  • pdf - PDF 处理和表单填充
  • xlsx - Excel 电子表格创建和编辑
  • docx - Word 文档操作
  • pptx - PowerPoint 演示文稿

🎨 Creative Skills

  • algorithmic-art - 生成式艺术创作
  • canvas-design - 视觉设计
  • slack-gif-creator - GIF 动画

💼 Enterprise Skills

  • brand-guidelines - 品牌规范
  • internal-comms - 内部沟通
  • theme-factory - 主题定制

🔧 Developer Skills

  • mcp-builder - MCP 服务器生成
  • webapp-testing - Web 应用测试
  • artifacts-builder - Claude 工件构建

社区 Skills 资源

📚 GitHub 仓库

🎓 学习资源

📖 案例研究: 完整 Skill 开发流程

场景: 创建数据库迁移 Skill

正在加载图表...

完整实现

---
name: database-migration
description: Generates database migration files with up/down SQL scripts when the user asks to create a database migration or schema change
allowed-tools: Write,Bash(npm run *)
tags:
- database
- migration
- sql
---

# Database Migration Generator

## Overview
Automatically generates timestamped database migration files with proper up/down scripts.

## Instructions

### 1. Gather Migration Details
Ask the user for:
- Migration description (e.g., "add user email column")
点击展开查看完整代码共 204 行

💡 总结

Claude Skills 是模块化能力扩展的强大机制:

核心优势:

  • 🎯 智能调用 - Claude 自主判断何时使用
  • 📦 模块化 - 可组合、可移植、易维护
  • ⚡ 高效 - 按需加载,上下文优化
  • 💪 强大 - 支持脚本、工具、MCP 集成

三种存储位置:

  1. 个人 Skills - ~/.claude/skills/ (个人工作流)
  2. 项目 Skills - .claude/skills/ (团队共享)
  3. 插件 Skills - 插件市场(社区贡献)

核心文件结构:

  • SKILL.md - 核心指令和元数据(必需)
  • reference.md - 详细参考资料(可选)
  • examples.md - 使用示例(可选)
  • scripts/ - 可执行脚本(可选)

最佳实践:

  • 保持单一职责
  • 编写明确的 description
  • 使用渐进式披露(SKILL.md < 500行)
  • 提供具体示例
  • 跨模型测试
  • 使用脚本处理确定性任务
  • 通过 Git 共享团队 Skills

适用场景:

  • 复杂多步骤工作流
  • 专业领域知识
  • 团队标准和规范
  • 可重复的任务自动化

开始使用 Claude Skills,为 Claude 装备超能力! 🚀

相关资源

✨ 准备好创建你的第一个 Skill 了吗? ✨

从简单的工作流开始,逐步打造专属的 AI 能力库