问题背景

在使用 Claude Code 进行项目开发时，我们可以通过 .claude/skills/ 目录定义项目专属的技能规范，例如：

• 布局规范
• 弹窗组件使用规范
• 文件上传确认规范
• 表单验证规范
• ……

然而，在实际使用中发现一个关键问题：即使用户用明确语言精准命中了某个 skill 的 description 关键字，AI 仍然会优先去读取类似页面和相关组件来完成任务，而不是优先加载对应的 skill 规范。

除非用户明确指定"请使用 xxx skill"，否则 AI 不会主动调用。

---

问题分析

为什么 AI 不会自动使用 Skills？

1. 工具优先级机制：Claude Code 的 AI 默认倾向于使用 Read 工具直接读取文件内容，因为它更通用、更直观。

2. Skills 工具的特殊性：Skill 工具的作用不是简单读取文本，而是将技能指令注入为行为规范，影响 AI 后续的代码生成方式。这种"注入"机制 AI 不会主动推断。

3. Read 与 Skill 的本质区别：

   • Read 工具：获取文件的文本内容（只读）
   • Skill 工具：将技能内容加载为行为约束（影响后续输出）

---

解决方案

核心思路

在项目的 CLAUDE.md 文件中，明确、强制性地指定 Skills 的使用规则，让 AI 在匹配到相关任务时必须优先调用 Skill 工具。

具体实现

在 CLAUDE.md 中添加以下内容：

- **Project skills (非常重要)**:
-  当任务匹配某个 skill 的领域时（如布局规范、弹窗、上传确认等），**必须使用 `Skill` 工具加载对应的技能**，而不是用 Read 工具读取技能文件。Read 工具只能获取文本内容，Skill 工具才能将技能指令注入为行为规范。可用技能位于 `.claude/skills/` 目录。

  **Skill 调用规则（必须遵守）**：
  1. **从用户对话提取关键字**：仔细分析用户的原话，提取中文关键字（如"弹窗规范"、"新版弹窗"、"布局"、"上传确认"等）
  2. **用关键字匹配 skill 名称**：直接用提取的关键字调用 `Skill` 工具
  3. **调用失败时的处理**：如果返回 `Unknown skill` 错误，**必须**先用 `Glob` 工具查找 `.claude/skills/` 目录下的可用 skill 的description，然后用正确的名称重新调用 `Skill` 工具
  4. **禁止降级**：绝对不能因为一次调用失败就改用 `Read` 工具读取 skill 文件，这是违反规范的行为

  **错误示例**：用户说"按照弹窗规范调整" → 错误调用 `Skill('dialog')` → 失败 → 改用 `Read` 工具 ❌
  **正确示例**：用户说"按照弹窗规范调整" → 提取关键字"弹窗规范" → 调用 `Skill('新版弹窗规范')` → 成功 ✅
  **兜底示例**：不确定名称 → `Glob('.claude/skills/*.md')` → 获取列表 → 用正确名称调用 `Skill` ✅

关键点说明

要素	说明
位置	放在 CLAUDE.md 的 ## Key Conventions 或独立章节
语气	使用"非常重要"、"必须"等强约束词汇
对比说明	明确指出 Read 和 Skill 的区别，消除歧义
路径指引	给出 skills 目录位置，方便 AI 自行查找

---

使用效果

配置完成后，当用户提出类似以下需求时：

• “按照布局规范调整页面结构”
• “弹窗组件需要符合项目规范”
• “文件上传需要有确认提示”

AI 将会：

1. ✅ 自动识别任务匹配的 skill
2. ✅ 优先调用 Skill 工具加载规范
3. ✅ 遵循规范生成符合项目标准的代码

而不是：

1. ❌ 直接读取类似页面代码
2. ❌ 按照自己的理解生成代码
3. ❌ 忽略项目已有的规范约束

---

完整配置示例

# CLAUDE.md

## Project Overview
（项目概述...）

## Commands
（命令说明...）

## Key Conventions

- **Comments**: 复杂逻辑需要详细注释...
- **Component naming**: PascalCase...
- **File size**: 单文件不超过 300 行...
- **Project skills (非常重要)**: 当任务匹配某个 skill 的领域时（如布局规范、弹窗、上传确认等），**必须使用 `Skill` 工具加载对应的技能**，而不是用 Read 工具读取技能文件。Read 工具只能获取文本内容，Skill 工具才能将技能指令注入为行为规范。可用技能位于 `.claude/skills/` 目录。
-   **Skill 调用规则（必须遵守）**：
  1. **从用户对话提取关键字**：仔细分析用户的原话，提取中文关键字（如"弹窗规范"、"新版弹窗"、"布局"、"上传确认"等）
  2. **用关键字匹配 skill 名称**：直接用提取的关键字调用 `Skill` 工具
  3. **调用失败时的处理**：如果返回 `Unknown skill` 错误，**必须**先用 `Glob` 工具查找 `.claude/skills/` 目录下的可用 skill 名称，然后用正确的名称重新调用 `Skill` 工具
  4. **禁止降级**：绝对不能因为一次调用失败就改用 `Read` 工具读取 skill 文件，这是违反规范的行为

  **错误示例**：用户说"按照弹窗规范调整" → 错误调用 `Skill('dialog')` → 失败 → 改用 `Read` 工具 ❌
  **正确示例**：用户说"按照弹窗规范调整" → 提取关键字"弹窗规范" → 调用 `Skill('新版弹窗规范')` → 成功 ✅
  **兜底示例**：不确定名称 → `Glob('.claude/skills/*.md')` → 获取列表 → 用正确名称调用 `Skill` ✅

总结

这个问题的本质是 AI 工具调用的优先级偏好。通过在 CLAUDE.md 中添加明确的约束指令，我们可以：

1. 纠正 AI 的默认行为：从"优先 Read"改为"优先 Skill"
2. 确保规范被正确加载：Skill 工具的注入机制才能真正约束 AI 行为
3. 提升开发一致性：生成的代码自动符合项目规范

这个配置对于团队协作和代码规范统一非常重要，建议所有使用 Claude Code 的项目都在 CLAUDE.md 中明确声明 Skills 的使用规则。