Claude Code Skills 完整教程：安装、目录与使用方法

先说结论：Skills 解决什么问题

如果你经常给 Claude Code 粘贴同一套要求，例如“整理任务时不要猜负责人，缺失信息单独列出”，就值得把这套要求写成 Skill。以后做同类任务，可以直接调用，也可以让 Claude 根据请求判断是否使用。

这篇教程用一个小例子贯穿全程：把几句话整理成任务表，保留负责人和截止时间，把没有给出的信息标成“待确认”。输入短、结果容易核对，不需要 API Key、数据库或额外依赖。

本文区分本地实测与官方规则。 本次在 ~/claude-skills-demo 使用 Claude Code 2.1.263 验证了基础对话、显式 /task-note 调用和结构化输出；自动调用、错误复现及部分目录行为仍以当前 Claude Code 官方 Skills 文档 为准。

文中的“本次实测”仅指上述练习目录中的测试；“官方文档说明”不等同于本机逐项验证。

Skills 到底是什么，哪些场景适合用

一个 Skill 是以 SKILL.md 为入口的目录。文件描述什么时候使用、按什么步骤做、输出应满足什么要求；目录里还可以放参考资料、样例或脚本。Claude Code 读取这些说明后执行任务。

单次提问直接在对话中表达即可。任务重复出现、输出格式或判断标准需要保持一致时，维护 Skill 才有价值。

项目中需要长期遵守的约定可以放在 CLAUDE.md；某类任务才需要的步骤适合放进 Skill。官方文档说明，Skill 正文在使用时加载，适合承载按需读取的流程。流程中若要访问外部系统，仍需要真实可用的工具、账号和权限，Skill 本身不能提供这些条件。

安装前需要确认什么

本文的“安装”指把自写或已审阅的 Skill 放进 Claude Code 支持的目录。前提是你已经装好 Claude Code，能够正常进入对话。若尚未安装，先从 Claude Code 官方文档 进入当前安装说明，完成后再继续。

以下 shell 示例面向 macOS 的 zsh 或 bash；斜杠调用则输入在 Claude Code 对话框中。先在终端记录版本：

claude --version

能打印版本不代表模型调用已经可用，还需要确认你能正常发起对话。使用干净的练习目录，避免第一次试验就让 Skill 接触业务代码。

本次实测：Claude Code 2.1.263，macOS 练习目录 ~/claude-skills-demo，2026-09-09；基础提示和 /task-note 均返回成功结果。

全局 Skills 与项目 Skills 放在哪里

官方把这两类分别称为 Personal 和 Project。下文的“全局”指当前操作系统用户的个人目录，不代表所有用户、机器或云端会话都能读取。

~ 是当前用户的 Home 目录，<project-root> 和 <skill-name> 是解释用占位符，不要按字面创建尖括号目录。不要把其他工具的 Skills 目录直接当成 Claude Code 的默认目录。

先从项目级开始，位置和 Git 变更都更容易检查。个人目录也可能影响当前项目；换一台机器或改用云端会话时，应重新确认哪些 Skill 实际可用。

同名优先级尤其容易记反。 官方目录说明 当前写的是：跨层级同名时，企业级高于个人级，个人级高于项目级。因此，不能认为“离项目更近就一定优先”。插件使用自己的命名空间；嵌套项目目录另有规则。不要期待两个同名文件的正文自动合成一份。

官方文档说明：个人级路径是 ~/.claude/skills/<skill-name>/SKILL.md，项目级路径是 .claude/skills/<skill-name>/SKILL.md；同名时企业级覆盖个人级、个人级覆盖项目级。本次用同名专用 Skill 实测 /zt-verify-scope 返回个人级标记，与该规则一致。

安装第一个 Skill：建立练习目录

在你选择的练习目录的上一级执行：

mkdir claude-skills-demo
cd claude-skills-demo
mkdir -p .claude/skills/task-note

如果 claude-skills-demo 已存在，换一个新的目录名再继续，避免把旧文件混进本次验证。这里不需要初始化框架或安装 npm 包。

用编辑器创建 .claude/skills/task-note/SKILL.md，粘贴下一节的完整内容并保存为纯文本 Markdown。最后应得到：

claude-skills-demo/
└── .claude/
    └── skills/
        └── task-note/
            └── SKILL.md

如果安装的是别人分享的 Skill，也应检查入口是否正好位于这一层。下载包可能多套一层目录；不能只把整仓库随意丢进 skills/ 就认定安装完成。复制前先读 SKILL.md 及其引用的脚本，检查会读写哪些文件、是否联网、是否会执行外部命令。

一个最小可用的 SKILL.md 怎么写

下面是本文自写的演示素材，可直接复制。它只要求整理用户提供的文本，不执行脚本、不访问外部服务。

---
name: task-note
description: 将用户提供的会议记录或零散事项整理成任务清单，提取负责人和截止时间，并列出待确认信息。用户要求整理任务或提取待办时使用。
---

# 整理任务清单

只依据用户本次提供的文字整理，不读取其他文件。

## 执行步骤

1. 提取需要执行的任务；背景介绍不要当成任务。
2. 保留原文给出的负责人和截止时间，不推断姓名或日期。
3. 负责人或截止时间缺失时，填写“待确认”。
4. 同一任务信息冲突时，保留冲突并放进待确认列表。

## 输出格式

以“任务整理结果”作为标题。
输出 Markdown 表格，列为：任务、负责人、截止时间。
表格后输出“待确认”列表，逐项说明缺失或冲突的信息。
没有待确认项时写“无”。没有输入内容时，请用户提供原文。

文件顶部的两条 --- 包住 YAML frontmatter，下面是 Markdown 正文。开头的 --- 放在第一行，前面不要加标题或说明文字。

description 解决“什么时候应该使用”，正文解决“使用后怎么做”。“帮我提高效率”太宽；“把会议记录整理成任务清单，并列出缺失的负责人和截止时间”才有可检查的边界。输出格式和缺失值规则要具体，否则模型仍需猜测。

按照当前 frontmatter 参考，Claude Code 的这些字段不是全部必填，官方推荐提供 description。本文显式写 name，并让它与目录名一致，便于理解和维护。

命名建议使用 task-note 这种简短的小写连字符名称。这是组织建议，不等于宣称当前解析器只接受这一种写法。当前官方文档说明，个人与项目级 Skill 的调用名来自目录名，name 用于显示名称；插件规则不同。也不要使用官方保留的 synced 目录名。

入口使用 SKILL.md，不要保存成 SKILL.md.txt、Word 文件或把本文的 .mdx 文章格式照搬成 Skill 入口。支持文件可以是说明文档、模板或脚本；它们的存在不等于会自动加载或执行，正文应说明什么时候读取、怎么使用。脚本需要的运行时也要真实存在。

截图中的真实显式调用已确认本例的目录名、frontmatter 和 SKILL.md 入口可用。其他入口格式或命名边界仍应查阅当前官方资料后再测试。

Claude Code 如何发现、加载和使用 Skill

把“目录存在”“可发现”“已使用”分开看，排查会容易很多：

文件放在受支持的目录
        ↓
Claude Code 发现 Skill，获得名称和描述
        ↓
用户显式调用，或 Claude 判断请求匹配
        ↓
加载 Skill 正文，按说明处理任务
        ↓
核对调用记录与结果

这是流程示意，不是实际运行轨迹。官方说明，默认情况下 Claude 获得名称与描述，在调用时加载正文。能看到名称不代表这一轮已经读取正文，更不代表结果正确。

启动目录、嵌套目录与保存后的变化

依据官方 发现规则，启动时会读取启动目录及向上到仓库根目录沿途的 .claude/skills/。启动目录下更深层的 Skills 并非一次全部加载；Claude 读取或编辑对应子目录文件后，它们才变为可用。嵌套同名 Skill 的限定名称规则也不能简化成“子目录覆盖父目录”。初次练习放在启动目录即可。

官方还说明，已监听的 Skills 目录中的 SKILL.md 变更可在当前会话生效；若顶层 Skills 目录在启动时尚不存在，新建后需要重启。本文选择先写好文件再启动新会话，减少热更新和历史上下文对验证的干扰。

官方文档说明：Claude Code 会发现启动目录及父目录中的项目级 Skills，嵌套目录的 Skills 在访问对应子目录后才可用；SKILL.md 文本变更可在当前会话生效，首次创建原本不存在的顶层目录则需重启以开始监听。本次未逐项复现这些时序行为，不把它们写成本地实测。

Claude Code 已能够通过 /task-note 调用该 Skill。

实际调用示例：把零散事项整理成任务表

留在 claude-skills-demo 目录，在终端启动 Claude Code：

claude

先验证显式调用

在 Claude Code 对话框输入下面一条消息，注意不要在 shell 执行它：

/task-note 小林周五前完成首页文案；小周负责检查移动端导航；下周一前补齐文章截图，负责人未定。

根据当前 官方调用说明，可以用 /skill-name 调用并跟随输入。本文不设置禁止手动调用的字段。记录真实调用入口、Skill 名称和输出，之后逐项对照：

截图中的真实输出展示了任务表、负责人和截止时间，并将缺失信息标为“待确认”。验收时仍应检查两项缺失信息：移动端导航检查的截止时间、补齐截图的负责人。“周五”和“下周一”应保留原文，不能擅自换算成某个日期。

再验证自动使用

另开一个从同一目录启动的新会话，发送下面的请求，不带 /task-note，也不要把 Skill 正文粘贴到会话里：

请把下面的记录整理成任务清单，并列出待确认信息：
小林周五前完成首页文案；小周负责检查移动端导航；下周一前补齐文章截图，负责人未定。

检查是否有实际 Skill 调用或读取证据，再核对输出。不要因为表格格式相似就认定自动使用了 Skill，也不要把模型自己说“已加载”当成独立证据。当前版本如果没有可见调用记录，就把自动加载保留为待核验。

自动使用由请求与描述的匹配等因素决定，不承诺每次都触发。手动成功而自动使用没有发生时，先检查 description 是否准确、是否有禁用设置，再做新会话对照。

需要控制调用方式时

官方 调用控制说明 提供两个不同字段，加入现有 frontmatter 时按目的选择：

初次练习不要添加这些设置，先跑通默认行为。把流程写成“只读”也是文字约束，不是权限隔离；本文示例没有工具授权字段，不需要额外设置文件。

本次实测 /task-note 成功接收参数并输出任务表；自然语言请求也得到相同结构，但没有独立调用记录，不能据此证明自动调用。官方文档说明 /skill-name 可带参数，disable-model-invocation: true 可关闭自动调用；本次额外确认 --disable-slash-commands 会使 /task-note 返回 Unknown command。

多项目共用 Skills 怎么管理

个人使用可以把通用 Skill 放进 ~/.claude/skills/。团队使用则建议把项目依赖的 Skill 随仓库保存，让规则变更和代码一起 Review，新成员也能看到同一份说明。

先选定哪一份是维护源，再决定如何分发。小规模使用可从维护源复制经过 Review 的版本到各项目，记录来源版本；更新时比较差异，避免直接覆盖项目已经调整过的内容。

skills-library/              维护源，普通目录，不会仅凭名字被发现
└── task-note/
    └── SKILL.md

project-a/                  使用经过 Review 的项目副本
└── .claude/skills/task-note/SKILL.md

project-b/
└── .claude/skills/task-note/SKILL.md

符号链接可以减少副本。当前官方文档说明个人级、项目级等位置的 Skill 目录支持指向其他目录的 symlink，Claude Code 会读取目标目录中的 SKILL.md。本次未完成 API 回合中的 symlink 运行测试，因此把它视为官方支持的管理方式，使用前仍应在自己的环境验证目标可读性。

个人与项目级不要长期维护同名、不同内容的 Skill；结合前面的优先级规则，它很容易让你以为在使用仓库版本，实际却使用个人版本。需要不同用途时，用不同名称表达边界。

推荐的目录组织方式

最小示例只需要 SKILL.md。当说明确实变长，再增加用得到的文件：

.claude/
└── skills/
    └── task-note/
        ├── SKILL.md
        ├── examples.md
        └── reference.md

这是扩展结构建议，最小安装不需要后两个文件。examples.md 可以保存典型输入和验收结果，reference.md 放较长的术语表；在 SKILL.md 里明确引用并说明何时读取。文件名用于组织，不代表它们有特殊自动加载规则。

入口负责使用条件、执行步骤和输出要求；较长资料按需读取。等到确实需要重复运行命令，再增加脚本并写清运行时、输入、输出和失败处理。不要为了让目录显得完整，预先放一堆空目录。

常见坑：按证据排查

YAML 有问题不一定表现为“完全加载失败”

当前 官方排查说明 提到：frontmatter YAML 解析失败时，Claude Code 可能使用空元数据加载正文，斜杠调用仍能工作，但自动匹配缺少 description。不要预写不存在的“加载失败”红色弹窗，也不要把所有未触发都归因于 YAML。

遇到真实异常时，保存触发步骤、原始文件的脱敏版本、Claude Code 版本和首个有效错误。需要日志时，官方说明可用 --debug 观察解析错误；日志可能包含会话、路径或凭据信息，只截与问题有关并已脱敏的部分。

当前没有可核验的真实错误案例。官方排查说明提到 frontmatter YAML 解析失败时可能以空元数据加载正文；不要把这一规则改写成必然的“完全加载失败”。遇到实际错误时，再按版本、触发步骤和首个有效错误记录恢复过程。

Skills 太多、来源不清，也会增加排查成本

先维护几份你能解释、能验收的 Skill。把 description 写准确，避免每份都宣称适用所有工作。不同工具可能支持不同扩展字段，复制之前检查目标产品说明，不能因为都叫 Skills 就假设行为一致。

截图与分享文件前，遮挡 macOS 用户名、Home 路径中的个人名称、API Key、Token、Email、私有 Repo 信息和 Terminal history 中的 Secret。还要检查窗口标题、其他标签页、账号、会话 ID、Cookie、内部 URL 和二维码。遮挡敏感值时保留 .claude/skills/task-note/SKILL.md 这样的关键相对层级。

最终总结与待实测清单

从一个项目级 Skill 开始最容易复现：创建目录，写好 SKILL.md，显式调用，再在新会话验证自动使用。验收既要看调用证据，也要对照任务结果；文件存在、菜单出现、输出正确是不同层面的证据。

个人级适合本机多项目复用，项目级适合随仓库维护。新手先从一个项目级 task-note 开始，不必一开始就加脚本、链接或复杂目录。共享前先选定维护源，同名冲突按当前产品规则核对，别依赖“项目一定优先”的直觉。下一步可以继续阅读 Claude Code 的官方 Skills 文档，或为另一个重复任务写一份更小的 Skill。

本篇仍需完成：

• 本次已记录版本、测试环境和基础对话结果；自动调用、目录监听、symlink 时序与真实错误仍以官方规则和未来实测为准。

参考资料

以下为 2026-09-08 查阅的官方资料，不代表本文已在用户版本完成实测：

• Skills 目录与同名优先级
• 父目录与嵌套目录的发现规则
• 文件变更监听
• Frontmatter 字段与调用名来源
• 支持文件的组织、调用控制与参数传入
• Skill 未触发的排查