一、Skill的配置位置

在 Claude Code 中，Skill 可以通过两种级别的配置文件进行定义和注册，理解这两种配置位置的作用范围和优先级规则，是正确管理 Skill 的基础。

1.1 项目级 CLAUDE.md

项目级 CLAUDE.md 位于项目根目录（即 CLAUDE.md 所在的仓库根目录），其 Skill 定义仅在该项目的会话中生效。这是最常用的配置层级，适合将与特定项目相关的自动化和辅助工具注册为 Skill，例如项目专属的代码审查规范、构建脚本、测试命令等。

1.2 用户级 CLAUDE.md

用户级 CLAUDE.md 位于用户家目录下的 ~/.claude/CLAUDE.md，其 Skill 定义在所有项目的会话中全局生效。这是配置通用 Skill 的最佳位置，例如文本处理、格式化工具、通用代码审查模板等跨项目复用的功能。

1.3 作用范围与优先级规则

当同一项目同时存在项目级和用户级 Skill 时，项目级 Skill 会覆盖（override）同名的用户级 Skill。命名不冲突的 Skill 则会合并生效。优先级规则如下：

• 项目级 Skill 优先级高于用户级 Skill
• 同名 Skill 以项目级定义为准
• 不同名 Skill 全部生效，不受层级影响
• Skill 的加载顺序为：先加载用户级，再加载项目级，后者覆盖前者

二、Skill的YAML语法结构

Skill 在 CLAUDE.md 中使用 YAML 格式的代码块进行定义，每个 Skill 由名称（name）、触发命令（command）和执行提示词（prompt）三个核心部分组成。下面是一个完整的 Skill 定义示例：

2.1 name — 技能名称

name 字段定义了 Skill 的显示名称，用于在帮助列表和对话中标识该 Skill。名称应当简洁明了，能够准确描述 Skill 的功能。名称可以使用中文或英文，但建议在团队协作场景下使用英文以避免编码问题。

2.2 command — 触发命令

command 字段定义了触发该 Skill 的斜杠命令，用户在对话中输入 /<command> 即可调用对应的 Skill。命令名称应当简短且具有辨识度，避免与其他 Skill 的命令冲突。命令规则如下：

• 只能包含小写字母、数字和连字符（-）
• 不能包含空格或特殊字符
• 建议长度控制在 2-20 个字符之间
• 不能与内建命令（如 /help、/clear 等）重名

2.3 prompt — 提示词模板

prompt 字段是 Skill 的核心，定义了当用户调用 Skill 时，Claude 将执行的具体指令。prompt 支持模板语法，可以包含参数占位符，从而实现动态内容注入。prompt 的编写质量直接决定了 Skill 的执行效果，建议遵循以下原则：

• 明确指定任务的输入和输出格式
• 提供具体的检查要点或步骤说明
• 使用 {{INPUT}} 或命名参数引用用户输入
• 保持 prompt 的聚焦性，一个 Skill 只做一件事

三、参数传递机制

Skill 支持多种参数传递方式，使得 Skill 可以灵活地接收用户输入并注入到 prompt 模板中，从而实现动态和可复用的 Skill 定义。

3.1 位置参数

在 prompt 模板中使用 {{arg1}}、{{arg2}} 等占位符来引用用户通过位置传递的参数。用户调用时在命令后附加空格分隔的参数值，系统会自动按顺序填充。适用于参数数量固定且顺序明确的场景。

3.2 命名参数

使用 {{name}} 形式定义命名参数，用户通过 /command name=value 的语法传递。命名参数不受顺序限制，用户可以选择性地传递部分参数，未传递的命名参数将保持占位符形式。适用于需要多个可选参数的复杂 Skill。

3.3 特殊参数 — INPUT

{{INPUT}} 是一个特殊的通配参数，它会捕获用户命令后的所有输入文本，包括多行内容。这是最灵活的传参方式，适用于代码审查、文本分析等需要处理大量输入的场景。当使用 {{INPUT}} 时，不需要在 prompt 中定义其他命名参数。

3.4 环境变量引用

Skill 的 prompt 中可以引用环境变量，语法为 {{env:VARIABLE_NAME}}。这使得 Skill 可以访问系统环境信息、API 密钥等配置数据，而无需硬编码在 CLAUDE.md 中。环境变量引用在用户级 CLAUDE.md 中尤其有用，可以安全地传递跨项目的敏感配置。

3.5 多行输入的处理

当用户需要传递多行文本时，可以在调用 /command 后直接粘贴多行内容，Skill 的 {{INPUT}} 参数会自动捕获包含换行的完整文本。在 prompt 模板中应当使用 white-space: pre-wrap 样式来确保多行输入的正确显示。

四、Skills的测试与调试

正确配置 Skill 后，需要进行测试验证以确保其按预期工作。以下是一套完整的测试与调试流程。

4.1 修改生效机制

CLAUDE.md 的修改会在下次会话中生效。在编辑 CLAUDE.md 文件后，需要重新加载配置才能使用新增或修改的 Skill。如果需要在不重启会话的情况下使修改生效，可以使用 /reload-plugins 命令重新加载配置。

4.2 使用 /command 测试 Skill

定义 Skill 后，在对话中输入 /<command> 即可触发测试。执行后观察 Claude 是否按预期响应，检查 prompt 中的指令是否被正确执行。如果 Skill 定义正确，Claude 会立即执行 prompt 中描述的任务。

4.3 通过输出结果验证 prompt 模板

测试 Skill 时，重点关注以下方面：

• 参数是否被正确替换和填充
• 格式要求是否被遵守（如列表、表格、代码块）
• 输出内容的完整性和准确性
• 是否符合 prompt 中指定的步骤和要点

4.4 常见配置错误排查

以下是 Skill 配置中最常见的错误及其解决方案：

错误现象	可能原因	解决方案
Skill 未出现在 / 列表中	YAML 语法错误	检查缩进和冒号格式
命令执行时无响应	command 名称包含非法字符	只使用小写字母、数字和连字符
参数显示为原始占位符	参数名拼写错误	确保 prompt 中的参数名与用户传递的名称一致
多行格式丢失	缺少 pre-wrap 样式	在 CSS 中添加 white-space: pre-wrap
Skill 被其他配置覆盖	同名 Skill 冲突	检查项目级和用户级是否存在同名 Skill

五、多项目Skills复用

随着项目中 Skill 数量的增长，如何高效管理和复用 Skill 成为一个重要问题。以下介绍几种 Skill 复用策略。

5.1 用户级 CLAUDE.md 共享通用 Skill

将不依赖特定项目上下文的通用 Skill 放在用户级 CLAUDE.md（~/.claude/CLAUDE.md）中，这些 Skill 将在所有项目中自动可用。适用于以下类型的 Skill：

• 文本格式化与转换工具
• 通用代码审查模板
• 标准化 Git 提交信息生成器
• 常用命令速查工具
• 技术文档翻译工具

5.2 CLAUDE.md 引用机制

Claude Code 支持通过 @ 引用语法在 CLAUDE.md 中引入其他文件的内容。利用这一机制，可以将公共 Skill 定义维护在独立的文件中，然后在多个项目的 CLAUDE.md 中引用，实现真正的"一处定义，多处使用"。例如：

5.3 团队 Skill 的标准化管理

在团队协作场景下，建议建立一套标准化的 Skill 管理流程：

• 将通用 Skill 维护在独立的 .claude/skills/ 目录中，按功能分类组织
• 使用版本控制（Git）管理 Skill 定义的变更历史
• 为 Skill 编写文档，说明每个 Skill 的用途、参数和使用示例
• 定期审查和更新 Skill，移除不再使用的冗余定义
• 统一命名规范，避免团队内部 Skill 命令冲突