09-Claude Code 中的Skill基础和创建

在人工智能辅助编程的时代，如何让 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.md
templates/ (可选)
references/ (可选)
scripts/ (可选)
assets/ (可选)
复制

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

2. 我理解的Skill

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

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`	部署流程、提交规范、代码生成

这有点向古代的文官和武将，这两种类型的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、2、3步骤就是。
有输出模板： 需要个给它一个固定的输出格式。
trigger: manual ： 必须使用/xxxx来调用skill。

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

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

复制代码

/hello-jspang
复制

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