平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“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/ | 你所有的项目 | 个人本地 |
| Project | .claude/skills/ | 当前项目 | 提交到Git |
| Plugin | | 启用该插件的项目 | 随插件分发 |
同名优先级：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，开始执行你设置好的技能，新建文件，写入内容，通知结果。
结合项目来看，总的来说，Claude这部分内容适合结合实际项目边做边理解。先抓住核心思路，再逐步补上细节和边界处理，最后效果会更稳定，也更容易复用。
