Claude Skills（Agent Skills）

一文读懂：它是什么、解决什么问题、以及如何正确使用

Anthropic 在 Claude 生态中引入了一个非常“工程化”的能力：Agent Skills（也叫 Claude Skills）。 如果你用 Claude 做过稍微复杂一点的工作（写代码、处理文档、跑流程、自动化任务），你会发现：Skills 本质上是在给 Claude 配“岗位说明书 + SOP + 工具箱”。

本文将用偏工程师视角，系统梳理：

  • Claude Skills 是什么，本质解决什么问题
  • 它和 Prompt、Slash Command、MCP 等机制的区别
  • 一个 Skill 的真实结构长什么样
  • 如何写出“容易被 Claude 自动触发”的 Skill
  • 实际使用中的最佳实践与坑位

主要参考官方文档与示例仓库（文末附链接）

一、什么是 Claude Skills？

Claude Skills 是一组可复用、按需加载的“任务能力包”，用于教 Claude 在特定场景下按你定义的方式完成工作。

更具体地说：

  • Skill 是一个文件夹级别的能力单元

  • 核心是 SKILL.md，告诉 Claude：

    • 这项能力是干什么的
    • 什么时候该用
    • 用的时候按什么步骤做

  • Skill 不需要你手动调用

    • 当你的提问和 Skill 的描述匹配时
    • Claude 会自行判断是否启用它

你可以把它理解为：

Prompt 的工程化 + SOP 化 + 可复用化版本

二、为什么要用 Skills？它解决了什么问题？

在真实使用中，很多人都会遇到这些痛点：

  • 每次都要重复解释同一套规则

    “我们公司代码规范是这样的…” “这个项目的文档结构是这样的…”

  • 有明确流程，但每次都要手写提示

    拉数据 → 清洗 → 校验 → 输出

  • 有些任务用脚本更可靠，但希望 Claude 自动配合

Claude Skills 的价值在于：

1️⃣ 把“正确做法”固化下来

一旦写成 Skill，后续所有相关请求都会自动受益。

2️⃣ 自动触发，而不是手动调用

你不用记住 /run_xxx 这种命令，Claude 会自己判断。

3️⃣ 更省上下文（Progressive Disclosure）

  • 必要规则放在 SKILL.md
  • 大量参考资料、API 文档、示例文件 按需加载
  • 不会一上来就把上下文塞爆

三、Claude 是如何决定“用不用某个 Skill”的？

核心只有两点：

1. description（最重要）

SKILL.md 顶部的 YAML 描述，决定了触发概率。

官方建议 description 要包含：

  • 动作动词（extract / analyze / generate / validate）
  • 用户可能会说的话
  • 使用场景边界

📌 这是 Claude 用来做“匹配判断”的主要依据

2. Skill 内部的执行指令

一旦 Claude 决定启用 Skill，就会严格参考你写的：

  • 执行步骤
  • 输出格式
  • 异常与边界处理
  • 是否允许调用工具 / 脚本

四、一个 Skill 通常包含哪些内容？

从官方模型看，Skill 里的内容可以分为三类：

1️⃣ Instructions（指令）

  • 核心是 SKILL.md
  • 描述流程、规则、风格、输出格式
  • 可以拆成多个 .md 文件

2️⃣ Code（可执行代码）

  • 脚本（Python / Bash / Node 等）

  • 适合做确定性强的事情：

    • 批处理
    • 校验
    • 解析文件

  • Claude 负责“什么时候用”，代码负责“怎么稳定执行”

3️⃣ Resources（参考资料）

  • API 文档
  • Schema
  • 模板
  • 示例数据

👉 只在需要时才加载，这是 Skills 非常重要的设计点。

五、Skill 放在哪里？谁能用？

在 Claude Code 环境中，Skill 的位置决定了可见范围：

位置 作用范围
Enterprise 组织级（管理员维护）
~/.claude/skills/ 个人全局可用
.claude/skills/ 项目级（推荐）
Plugin 随插件分发

优先级规则（同名 Skill）：

Enterprise > Personal > Project > Plugin

六、最小可用 Skill 示例

目录结构：

.claude/skills/explain-code/
└── SKILL.md

SKILL.md 示例：

---
name: explain-code
description: 用图示和类比解释代码，适用于用户询问“这段代码在做什么 / 为什么这样设计”
---

# Explain Code

## Instructions
- 先给 3 句话的整体总结
- 再用 ASCII 图解释控制流或数据流
- 最后给一个现实世界类比

## Examples
- “解释这段 React 代码为什么会重复渲染”

📌 注意：

  • name 建议与目录名一致
  • description 决定触发率，比正文还重要

七、多文件 Skill 与 Progressive Disclosure

真实项目中，推荐这样拆：

my-skill/
├── SKILL.md
├── api.md
├── schema.md
└── examples.md
  • SKILL.md：入口说明 + 使用指引
  • 其它文件：只在需要时引用

好处非常明显：

  • 降低 token 消耗
  • 减少“无关信息干扰模型决策”
  • Skill 更容易长期维护

八、Skills vs 其它 Claude 定制方式

很多人会混淆这些概念，官方给了一个非常实用的区分思路：

方式 适合做什么
Skills 自动触发的流程 / 规范 / 能力
Slash Commands 手动触发的 Prompt 模板
CLAUDE.md 项目级永久规则
Subagents 隔离上下文、独立执行
Hooks 事件驱动脚本
MCP Server 提供外部工具与数据

一句话总结：

Skill = 教 Claude“什么时候、该怎么做” MCP = 给 Claude“能用什么工具”

九、Claude.ai、Claude Code、Claude API 的关系

  • Claude Code

    • 完整支持自定义 Skills
    • 最适合工程与团队场景

  • Claude.ai

    • 部分计划内置示例 Skill

  • Claude API

    • 支持 Agent + Skills（以平台文档为准）

官方示例仓库支持三种方式试用。

十、实战最佳实践

✅ description 写“动作 + 场景 + 关键词” ❌ 不要写成营销文案

✅ 流程要“可执行”

  • 明确输入
  • 明确输出
  • 明确异常处理

✅ 脚本只做确定性工作 让模型负责决策，让代码负责执行

⚠️ 只使用可信来源的 Skill

  • 尤其是包含可执行代码时
  • 官方明确建议避免使用未知第三方 Skill

总结一句话

Claude Skills 本质上是：把 Prompt、流程、规范、工具，升级成“可复用、可自动触发的工程能力单元”。

如果你已经在用 Claude 写代码、做文档、跑流程，Skills 几乎是必用能力。

官方参考链接