Claude Code Skills 详解

概述

Skills 是 Claude Code 中的模块化、可发现的知识单元，用于教导 Claude 如何以可重复的方式完成特定任务。它们是独立的软件包，包含指令、元数据和可选的资源文件。

核心特性

特性	说明
模块化和可重用性	独立的软件包，可跨项目重复使用
自动调用机制	Claude 根据用户请求自动判断何时触发
渐进式披露	仅预加载元数据，按需加载完整内容
跨平台兼容	支持 Claude.ai、Claude Code 和 API
可执行代码支持	可包含 Python、Shell 等脚本

Skills vs Slash Commands

👉Skills与MCP、Tools的区别详解 ^skills-vs-others

对比项	Skills	Slash Commands
触发方式	自动触发（基于语义匹配）	手动触发（输入 /command）
适用场景	复杂多文件工作流、专业领域知识	简单重复任务、用户触发的快捷操作
配置文件	SKILL.md	.claude/commands/*.md
复杂度	高（可含脚本、模板、资源）	低（单个 Markdown 文件）

目录结构

技能存储位置

# 个人技能（所有项目通用）
~/.claude/skills/
    └── my-skill/
        └── SKILL.md

# 项目技能（团队共享）
<项目根目录>/.claude/skills/
    └── team-skill/
        └── SKILL.md

技能目录结构

my-skill/
├── SKILL.md          # 核心文件（必需）
├── reference.md      # 参考文档（可选）
├── examples.md       # 示例集合（可选）
├── scripts/          # 可执行脚本（可选）
│   └── helper.py
└── templates/        # 文件模板（可选）
    └── template.txt

SKILL.md 配置格式

基本结构

---
name: skill-name
description: 技能描述，Claude 依靠此描述判断何时触发
allowed-tools:
  - Tool1
  - Tool2
---
# 以下是 Markdown 格式的指令内容

必需字段

字段	要求	说明
name	最多 64 字符	只能包含小写字母、数字和连字符
description	最多 1024 字符	最关键字段，决定触发时机

Description 编写要点

Description 是 Claude 判断是否触发技能的核心依据，应包含：

1. 功能定义 - 技能做什么
2. 适用场景 - 什么情况下使用
3. 触发关键词 - 用户可能使用的词汇

💡 提示: 最佳实践

description: 公众号文章写作助手。根据用户提供的主题、大纲或参考内容，
  自动生成符合公众号风格的原创文章。当用户提到"写公众号""生成文章"等关键词时触发。

⚠️ 警告: 反面示例

description: 写作助手Skill.

过于宽泛，Claude 难以判断何时触发。

可选字段

字段	说明
allowed-tools	限制可使用的工具（如 Bash、Read、Grep）
user-invocable	是否显示在斜杠命令菜单，默认 true
model	指定使用的 Claude 模型
context	设为 fork 时在隔离子代理中运行
agent	与 context: fork 配合，指定代理类型
hooks	定义生命周期钩子
dependencies	声明依赖包

可选字段详解

allowed-tools - 工具权限控制

# 方式一：逗号分隔
allowed-tools: Read, Write, Bash

# 方式二：YAML 列表
allowed-tools:
  - Read
  - Write
  - Bash(python:*)  # 支持 glob 模式

model - 指定模型

model: claude-sonnet-4-20250514

未指定时使用当前对话的活动模型。

context + agent - 子代理模式

context: fork
agent: Explore  # 可选: Explore, Plan, general-purpose 或自定义代理

在隔离环境中执行，拥有独立的对话历史。适用于需要独立上下文的复杂任务。

hooks - 生命周期钩子

hooks:
  PreToolUse:
    - command: "echo 'Before tool execution'"
  PostToolUse:
    - command: "echo 'After tool execution'"
  Stop:
    - command: "echo 'Skill completed'"

支持的钩子事件：

• PreToolUse - 工具执行前
• PostToolUse - 工具执行后
• Stop - 技能完成时

dependencies - 依赖声明

dependencies: python>=3.8, pandas>=1.5.0, openpyxl

声明技能所需的软件包和版本要求。

创建自定义 Skill 步骤

步骤 1：创建技能目录

# 个人技能
mkdir -p ~/.claude/skills/my-reporting-skill

# 项目技能
mkdir -p .claude/skills/team-reporting-skill

步骤 2：创建 SKILL.md

---
name: quarterly-reporting-assistant
description: 季度报告生成助手。当用户要求生成季度销售、财务或运营报告时触发。
  可根据提供的数据或模板生成结构化报告。
  触发关键词：生成季度报告、创建销售报告、财务报告。
---

# 季度报告生成助手

## 工作流程

1. **理解报告类型** - 确定用户需要的报告类型（销售、财务、运营等）
2. **获取必要数据** - 读取用户提供的数据文件或询问数据来源
3. **选择报告模板** - 从 `templates/` 目录选择合适模板
4. **填充报告内容** - 将数据填充到模板中
5. **审查与优化** - 检查报告逻辑和格式
6. **输出报告** - 以 Markdown 或指定格式输出

## 示例对话

用户输入: "请帮我生成一份关于Q3销售数据的季度报告。"

Claude 动作:
1. 识别到用户请求"季度报告"和"销售数据"
2. 询问用户提供Q3销售数据
3. 使用 `templates/sales-report.md` 模板
4. 生成并展示销售报告草稿

步骤 3：添加资源文件（可选）

模板文件 templates/sales-report.md

# {{Quarter}} 销售数据报告

## 概述
本报告总结了 {{Quarter}} 的销售表现。

## 关键指标
- 总销售额: {{TotalSales}}
- 订单数量: {{OrderCount}}
- 平均订单价值: {{AOV}}

## 销售趋势
（插入销售趋势图或详细数据）

## 总结与展望

处理脚本 scripts/data_processor.py

import json

def process_sales_data(data):
    total_sales = sum(item['amount'] for item in data)
    order_count = len(data)
    aov = total_sales / order_count if order_count > 0 else 0
    return {
        "TotalSales": f"${total_sales:,.2f}",
        "OrderCount": order_count,
        "AOV": f"${aov:,.2f}"
    }

if __name__ == "__main__":
    sample_data = [
        {"item": "Product A", "amount": 120.50},
        {"item": "Product B", "amount": 80.00},
    ]
    print(json.dumps(process_sales_data(sample_data)))

工作原理

sequenceDiagram
    participant User as 用户
    participant Claude as Claude
    participant Manager as Skill Manager
    participant Skill as SKILL.md

    User->>Claude: 发送请求
    Claude->>Manager: 检查技能元数据
    Manager-->>Claude: 返回匹配的技能描述
    Claude->>Claude: 判断是否需要技能
    alt 需要技能
        Claude->>User: 请求确认加载技能
        User-->>Claude: 确认
        Claude->>Skill: 加载完整 SKILL.md
        Skill-->>Claude: 返回指令内容
        Claude->>Claude: 按指令执行任务
    else 不需要技能
        Claude->>Claude: 正常处理请求
    end
    Claude->>User: 返回结果

最佳实践

编写高质量 Skill

1. Description 足够具体 - 直接影响 Claude 能否准确触发
2. 指令清晰分步 - 提供明确的操作指导
3. 工作流明确 - 定义清晰的执行流程
4. 从小任务开始 - 逐步掌握技能创建

安全注意事项

⚠️ 警告: 安全提醒
技能可以包含可执行代码，加载第三方技能时务必评估来源可靠性。

调试技巧

1. 使用 /skills 命令查看已加载的技能
2. 检查 description 是否包含足够的触发关键词
3. 确保 SKILL.md 语法正确（YAML frontmatter 格式）

API 集成

通过 Messages API 使用 Skills：

{
  "container": {
    "skill_id": "my-skill-id",
    "type": "skill",
    "version": "1.0"
  }
}

需要启用的 Beta 头：

• code-execution-2025-08-25
• skills-2025-10-02
• files-api-2025-04-14

参考资源

• Claude Code 官方文档
• Claude Code GitHub