在人工智能辅助编程的时代，如何让 AI 助手更好地理解你的需求、遵循你的规范、执行特定任务，是提升开发效率的关键。Claude Code 的 Skills 系统正是为解决这一问题而生。

Skills 并非传统意义上的"插件"或"扩展"，而是一种按需加载的认知结构。它将领域知识、执行步骤、输出规范与约束条件封装成独立的能力单元，在需要时被语义触发，渐进式加载到主 Agent 的认知空间中。这种设计既保持了主 Agent 的简洁性，又实现了能力的无限扩展。

本文将从 Skills 的基本概念入手，深入解析其触发机制与存放位置，并通过实际案例演示如何编写一个完整的 Skills 文件。你将了解到 Skills 的两大类型——参考型（提供知识规范）与任务型（执行具体操作），以及它们在 YAML 前缀、触发方式和应用场景上的核心差异。

无论你是希望统一团队代码风格，还是想要自动化重复性工作流程，掌握 Skills 的编写方法都将为你的开发体验带来质的提升。

一、什么是Skills

1.官方的解释

Skill是一个技能，是一个包含一下内容的文件夹：
- SKILL.md（必需）：使用Markdown格式说明，带有YMAL前文
- scripts/ （可选）：可执行代码（Python，Bash等）
- references/ ( 可选)： 按需加载的文档
- assets/ (可选) ： 输出中使用的模版、字体、图标

.claude/skills/<skill-name>/
    SKILL.md
    templates/     (可选)
    references/    (可选)
    scripts/       (可选)
    assets/        (可选)

可以看到，一个Skill就是一个文件夹，或者叫做路径。

2. 我理解的Skill

Skills是一种可被语义触发的能力包，它包含领域知识、执行步骤、输出规范与约束条件，并在需要时渐进式加载到主Agent的认知空间中。

Cladue Code Skills

Skills并不是简单的"能力扩展机制"（或者叫做插件），它本质上是一种按需加载的认知结构。可能你还是不太好理解，我这里做个简单的比喻，来帮助你理解： Skills = 你手机里的App应用。

  • 主Agent = 你的手机
  • Skills = 手机里的应用（App）
  • 语音触发 = 用手点看了App

当明白了什么是Skills, 可以更具像一点，在Claude Code 里的Skills是一markdown文档。

二、编写一个Skills

接下来我们就学着编写一个Skills，先说它的存放位置。

1. Skills的存放位置

新建一个Skills我们首先要确定它的存放位置，位置不同，它的适用范围也不同。也就是**位置决定了谁能使用它，以及优先级顺序。

级别 路径 使用范围 版本控制
Enterprise 由管理员配置（Managed Settings） 组织内所有用户 集中管理
Personal ~/.claude/skills/<skill-name>/SKILL.md 你所有的项目 个人本地
Project .claude/skills/<skill-name>/SKILL.md 当前项目 提交到Git
Plugin <plugin>/skills/<skill-name>/SKILL.md 启用该插件的项目 随插件分发

同名优先级：Enterprise > Personal > Project。Plugin Skills 使用  plugin-name:skill-name  命名空间，不与其他级别冲突。

通过这个表，可以看出，其实Skills就是一个SKILL.md文件。下面就以项目级

2. 两大类型的Skills：参考型和任务型

从工程角度，Skill 内容分为两类，参考型和任务型。参考型 Skill 影响“怎么做”，任务型 Skill 决定“做什么”。前者是语义环境，后者是具体行动。

类型 特征 重点 典型列子
参考型（Reference） 提供知识、Claude在当前对话中应用 强调“在什么场景下应用这些知识” API规范、代码风格、领域知识
任务型(Task) 执行具体操作步骤 强调“这个操作做什么”，常斜杠命令使用/command 部署流畅、提交规范、代码生成

Skill两种类型

这有点向古代的文官和武将，这两种类型的Skills定义的方法也稍有不同。下面我们就来试着编写一个任务型Skill并使用它。

2. 编写Skills文件

编写一个项目的Skills，这个是任务型的，编写这个的主要目的是让大家了解，如何来编写Skill，已经如何执行，其实这个Skill没有任何用处，类似些程序时候的Hello World 。

路径为：.项目根目录/.claude/skills/hello-jspang/SKILL.md

这个Skill就是一个参考型的skill，用于规定软件的“API设计规范”。

.claude/skills/hello-jspang/     # skill 目录，名称即 skill 名
└── SKILL.md                        # 主文件（必需）
---
name: hello-jspang
description: 创建/更新HELLO_JSPang.md,用于验证skill能跑通闭环.
trigger: manual  
---

## Instructions

1. 在项目根目录创建或更新 `HELLO_JSPang.MD`。
2. 内容必须包含三行：
   - `# hello skill`
   - `生成了 Hello_JSPang`
   - `Time: <当前时间>`
3. 最后用不超过3行告诉我你完成了什么。

注意这个 Skill 的关键特征——它是一个典型的任务型 Skill**。

  1. 有执行步骤： 需要一个完成的执行过程，这里的1、2、3步骤就是。
  2. 有输出模板： 需要个给它一个固定的输出格式。
  3. trigger: manual ： 必须使用/xxxx来调用skill。

一个Skill的编写，description 是灵魂，因为它不是给人看的文档，而是给Claude 看的触发器。Cluade选择是否激活一个Skill，完全依赖于阅读description。它不是单纯的拼配关键词，而是语义理解。（虽然我这里使用了中文，但是建议英文好的使用英文）

如何调用？在控制台直接输出

/hello-jspang

Claude就会开始调用这个Skill，开始执行你设置好的技能，创建文件，写入内容，通知结果。

好这节课的内容就先到这里，下节课我们继续学习Skill相关的知识。