Claude Code Skills 使用指南

Claude Code Skills 使用指南

一、什么是 Skill

Skill 是按需加载的知识模块。与 CLAUDE.md（每次对话始终加载）不同，Skill 只在模型判断相关时才注入上下文，适合存放详细规范、代码示例和领域知识，从而减小 CLAUDE.md 的体积，降低每次对话的基础 token 消耗。

二、Skill 文件结构

位置：.claude/skills/<skill-name>/SKILL.md

常见 frontmatter 字段：

字段	必填	说明	默认值
name	✅	技能名称，也是 / 命令名	无
description	✅	一句话描述，模型用来判断是否匹配	无
when_to_use	❌（推荐）	详细触发条件，自然语言描述	无
paths	❌（推荐）	glob 路径过滤，限定适用文件范围	匹配所有文件
user-invocable	❌	是否允许用户手动 / 调用	true
allowed-tools	❌	限制 skill 内可用的工具列表	继承父级所有工具
model	❌	指定使用的模型	使用主对话模型
agent	❌	指定子代理类型	无

📌 注意：description 与 when_to_use 合计上限 1536 字符（约 500-600 个汉字）。

三、触发机制

Skill 有两种触发方式：

1. 手动触发 — 用户输入 /<skill-name>
2. 自动触发 — 模型根据 description + when_to_use 语义判断
   - 当用户问题与 skill 描述语义匹配时，模型自动调用
   - paths 字段可进一步限定：仅当对话上下文中涉及的文件匹配 glob 时才考虑触发（包括用户提及、读取或编辑的文件）

常见误解：

❌ skill 可以通过关键词列表精确触发

✅ 用 when_to_use 自然语言描述触发场景

❌ 用 paths 限定"当前编辑文件"

✅ 用 paths 限定"对话上下文涉及的所有文件"

✅ 省略 when_to_use 即可实现"仅手动触发"

四、CLAUDE.md vs Skill — 如何分工

📄 放在 CLAUDE.md（始终加载）

• 技术栈版本
• 项目结构
• 命名规范速查表
• 核心架构规则（如数据流方向）
• 明确禁止的模式
• Git 提交格式
• 工作流规范

⚡ 放在 Skill（按需加载）

• 分层架构的完整代码示例
• 模板文件清单和生成流程
• 测试工具方法详解
• DDL 建表模板
• 任何 >20 行的代码示例

💡 核心原则：CLAUDE.md 放高频使用的"骨架规则"，Skill 放低频调用的"详细内容"。

```