Skill 的加载与触发机制
你只需要把 Markdown 文件放在正确的位置，Claude Code 就会自动发现并注册它为斜杠命令。理解这个机制，能帮助你在组织 Skills 文件结构时做出正确决策。
文件发现规则
Claude Code 在启动时会按以下优先级搜索 Skills 目录：
搜索路径（从高优先级到低优先级）：
1. 当前项目目录 → .claude/skills/
（仅对当前项目生效，最常用）
2. 用户主目录 → ~/.claude/skills/
（对当前用户所有项目生效）
3. 系统级目录 → /etc/claude/skills/
（对所有用户生效，通常用于企业部署）
优先级规则：当同名 Skill 在多个位置存在时，项目级 > 用户级 > 系统级。项目级的 Skill 会覆盖用户级同名 Skill。
文件命名与命令映射
Skill 文件名直接决定斜杠命令名称：
| 文件路径 | 触发命令 |
|---|---|
.claude/skills/review-pr.md | /review-pr |
.claude/skills/check-migration.md | /check-migration |
.claude/skills/deploy/pre-check.md | /deploy/pre-check 或 /pre-check |
命名规则： - 使用小写字母和连字符（kebab-case） - 避免空格和特殊字符 - 名称应能在命令行中直观理解
加载流程
sequenceDiagram
participant User as 用户
participant CLI as Claude Code CLI
participant FS as 文件系统
participant LLM as Claude 模型
User->>CLI: 启动 claude 命令
CLI->>FS: 扫描 .claude/skills/ 目录
FS-->>CLI: 返回 Skill 文件列表
CLI->>CLI: 注册斜杠命令（/skill-name）
User->>CLI: 输入 /review-pr --branch feat/auth
CLI->>FS: 读取 review-pr.md
FS-->>CLI: 返回 Skill 文件内容
CLI->>CLI: 解析参数（branch=feat/auth）
CLI->>LLM: 发送 Skill 提示词 + 参数注入 + 上下文
LLM->>CLI: 推理并执行工具调用
CLI-->>User: 输出 Skill 执行结果
关键点：Skills 文件在 Claude Code 启动时就已注册，不需要重新启动 Claude Code 才能更新——如果你修改了 Skill 文件，下次调用时 Claude Code 会读取最新版本。
Skill 文件的基本结构
一个完整的 Skill 文件包含以下部分：
---
description: 这个 Skill 做什么（在 /help 中显示）
allowed-tools: Read, Write, Bash, Grep # 可选，声明允许使用的工具
---
# Skill 标题
## 背景与目标
（告诉 Claude 这个 Skill 的用途和背景）
## 执行步骤
（详细描述要做什么，按什么顺序）
## 输出格式
（指定输出的结构和格式）
## 参数说明
（如果有参数，说明每个参数的含义和用法）
frontmatter（前置元数据）：
- description：在 /help 命令列出所有 Skills 时显示的简短说明
- allowed-tools：限制这个 Skill 可以调用的工具类型（安全边界）
触发方式详解
基本触发
# 无参数调用
/review-pr
# 带位置参数
/analyze-logs error.log
# 带具名参数
/review-pr --branch feature/auth --focus security
# 带多个参数
/deploy-check --env staging --service api --dry-run
从上下文触发
在已有的对话上下文中，Skills 能读取当前会话的上下文：
# 先粘贴了一段错误日志，然后调用 Skill
[粘贴了 500 行错误日志]
/analyze-error --severity critical
Skill 中的提示词可以引用 {{CONTEXT}} 来利用当前会话中已有的信息。
查看已注册的 Skills
# 查看所有可用的斜杠命令（包括 Skills）
/help
# 查看特定 Skill 的说明
/help review-pr
Skills 的生命周期
创建文件 → 自动注册 → 调用执行 → 修改文件 → 下次调用生效
↓
.claude/skills/review-pr.md
↓
/review-pr 命令可用
↓
用户调用 → 读取最新文件 → 执行
↓
修改 review-pr.md（添加新的检查步骤）
↓
下次 /review-pr 调用自动使用新版本
无需重启，无需重新编译——这是 Skill 作为 Markdown 文件的最大优势之一。
本节记录清单
- [ ] 确认 Claude Code CLI 已安装，
claude命令可用 - [ ] 在当前项目根目录创建
.claude/skills/目录 - [ ] 理解项目级 vs 用户级 Skills 的优先级关系
- [ ] 在
.claude/skills/中创建一个测试文件，运行/help验证是否注册成功
下一章：创建你的第一个 Skill——有了理论基础，现在开始动手：从零写一个真正可以运行的 Skill。