Skill触发机制：参数传递与文件读取

核心概念：Skill触发机制是Claude Code中通过斜杠命令调用预设行为的能力。参数系统允许在调用时动态传递上下文信息，使Skill行为更加灵活和智能化。本文深入解析参数传递的完整链路，包括位置参数、命名参数、文件读取、环境变量引用等核心机制。

一、斜杠命令的解析过程

当用户在Claude Code中输入 /command 并按下回车后，系统会触发一条完整的处理链路。理解这条链路是掌握Skill参数系统的基础。

1.1 命令识别阶段

用户输入以斜杠开头的命令（如 /explain），Claude Code会首先解析输入字符串，提取斜杠后的命令名称。系统会扫描所有已注册的Skill，通过命令名称进行匹配。匹配成功后，进入参数提取阶段。

1.2 参数提取阶段

在命令名称之后，用户输入的所有内容被视为参数串。系统根据Skill的prompt模板中定义的变量占位符（如 {{1}}、{{name}}、{{FILE:path}} 等），从参数串中提取对应的值。

1.3 模板填充阶段

提取的参数值被注入到Skill的prompt模板中，替换对应的变量占位符。填充完成后，prompt模板变为一个完整的、包含具体上下文信息的指令。

1.4 执行阶段

填充后的完整prompt被发送给Claude模型执行。模型接收到指令和上下文后，生成相应的响应。

关键理解：斜杠命令的本质上是一种"模板填充"机制。Skill定义的prompt是模板，用户输入的参数是数据，两者结合生成最终的执行指令。理解这一点，就理解了Skill参数系统的核心。

# 处理链示意图
用户输入:  /explain python "print('hello')"

步骤1: 识别命令 -> "explain"
步骤2: 提取参数 -> arg1="python", arg2="print('hello')"
步骤3: 填充模板 -> "请解释以下python语言的代码：\nprint('hello')"
步骤4: 执行 -> 模型生成解释

二、位置参数（{{arg}}）

位置参数是最基础的参数传递方式，通过数字索引 {{1}}、{{2}}、{{3}} 等来引用用户在命令后输入的参数，按顺序一一对应。

2.1 基本用法

在Skill的prompt模板中使用 {{1}} 表示第一个参数，{{2}} 表示第二个参数，以此类推。用户输入时，空格分隔的各个部分按顺序填充到对应的占位符中。

# 使用位置参数的Skill
- name: 解释代码
  command: explain
  prompt: |
    请解释以下{{1}}语言的代码：
    {{2}}

当用户输入 /explain python print('hello') 时，{{1}} 被替换为 python，{{2}} 被替换为 print('hello')，最终prompt为：

请解释以下python语言的代码：
print('hello')

2.2 灵活的参数位置设计

位置参数不要求连续使用，可以在prompt模板的任何位置出现。同一个位置参数也可以在模板中多次引用，实现参数复用。

# 参数复用示例
- name: 代码审查
  command: review
  prompt: |
    请审查以下{{1}}代码，重点关注{{1}}的编码规范：

    {{2}}

    以上是{{1}}代码，请给出改进建议。

2.3 多参数场景

对于需要多个参数的Skill，位置参数的数量需要与用户输入匹配。参数数量不够时，模型可能无法正确理解意图。

模板定义	用户输入	填充结果
翻译{{1}}到{{2}}	/translate 英文中文	翻译英文到中文
对比{{1}}和{{2}}	/compare react vue	对比react和vue
{{1}}与{{2}}的区别	/diff TCP UDP	TCP与UDP的区别

三、命名参数（{{name}}）

命名参数通过在模板中使用有意义的变量名（如 {{language}}、{{code}}），并通过 --name value 或 --name="value" 语法传递。命名参数比位置参数具有更好的可读性和灵活性。

3.1 基本语法

用户在斜杠命令后使用 --参数名值 的格式传递参数。模板中使用 {{参数名}} 接收。支持短横线参数名（如 --lang）和等号语法（如 --lang="python"）。

# 使用命名参数的Skill
- name: 解释代码
  command: explain
  prompt: |
    请解释以下{{language}}语言的代码：
    {{code}}

使用方式：/explain --language python --code "print('hello')"

3.2 命名参数的优势

命名参数相比位置参数有以下几个关键优势：

可读性强：参数名称自文档化，一眼就能看出参数的含义
顺序无关：参数可以任意顺序传递，不受位置约束
可选支持：可以设置默认值，某些参数可以不提供
清晰度高：在多参数场景下不会混淆

最佳实践：当Skill的参数数量超过2个时，建议使用命名参数而非位置参数。命名参数虽然输入时稍长，但在可维护性和清晰度方面有显著优势。

3.3 参数默认值

命名参数支持默认值设置。当用户在调用时没有提供某个命名参数时，模板中可以使用预设的默认值，确保prompt仍然完整可用。

# 带默认值的命名参数
- name: 解释代码
  command: explain
  prompt: |
    请解释以下{{language}}语言的代码，使用{{style}}风格：
    {{code}}

    # 默认值配置（在Skill定义中处理）
    # language默认: python
    # style默认: 简洁

四、文件内容读取（{{FILE}}）

{{FILE:path}} 语法用于在Skill模板中引用文件内容。当Skill被触发时，系统会自动读取指定路径的文件内容，并将其注入到prompt模板中。这是处理大量上下文信息的重要机制。

4.1 基本语法

在prompt模板中使用 {{FILE:路径}} 占位符，路径可以是相对于项目根目录的相对路径，也可以是绝对路径。系统在执行时自动读取文件内容替换占位符。

# 使用{{FILE}}读取配置
- name: 分析配置
  command: config-analyze
  prompt: |
    请分析以下配置文件的内容：

    {{FILE:config/settings.json}}

    请指出配置中的潜在问题和优化建议。

4.2 适用场景

大文件内容传递：当需要分析大段代码或日志时，不适合通过命令行参数传递，使用 {{FILE}} 自动读取
项目配置文件分析：读取 package.json、tsconfig.json 等配置文件进行分析
日志分析：读取日志文件内容进行分析和排查
代码审查：读取指定源文件进行代码审查

注意：{{FILE}} 读取的是Skill定义所在项目中的文件。如果文件路径不存在，系统会报错。建议在使用前确认文件路径正确且存在。

4.3 路径写法

路径写法	示例	说明
相对路径	`{{FILE:src/main.py}}`	相对于项目根目录
绝对路径	`{{FILE:/home/user/project/config.yml}}`	完整文件系统路径
带变量路径	`{{FILE:{{1}}}}`	结合位置参数动态指定路径

五、环境变量引用（{{ENV}}）

{{ENV:VAR_NAME}} 语法用于在Skill模板中引用环境变量。这对于管理API密钥、访问令牌等敏感信息特别有用，避免在CLAUDE.md或Skill定义中硬编码密钥。

5.1 基本语法

在prompt模板中使用 {{ENV:变量名}} 占位符。系统执行时自动读取当前进程中的环境变量值替换占位符。

# 使用{{ENV}}引用环境变量
- name: 部署检查
  command: deploy-check
  prompt: |
    当前部署环境：{{ENV:DEPLOY_ENV}}
    项目版本：{{ENV:APP_VERSION}}

    请根据以上环境信息检查部署配置是否正确。

5.2 使用场景

API Key管理：引用 {{ENV:OPENAI_API_KEY}} 等密钥信息，用于API调用场景
环境区分：引用 {{ENV:NODE_ENV}} 判断当前是开发/测试/生产环境
用户信息：引用 {{ENV:USER}} 或 {{ENV:USERNAME}} 获取当前用户名
路径信息：引用 {{ENV:HOME}} 或 {{ENV:PATH}} 获取系统路径

安全提醒：环境变量虽然可以避免硬编码密钥，但环境变量本身可能被其他进程读取。对于高度敏感的信息，建议配合专门的密钥管理服务使用。

5.3 环境变量与文件读取的对比

特性	{{FILE}}	{{ENV}}
数据源	文件系统	进程环境
适用场景	大文本、配置文件、代码	短值、密钥、配置标志
敏感性	取决于文件权限	可能被 `ps` 等工具窥探
动态性	文件内容可变	进程启动后固定

六、参数验证与错误处理

完善的参数验证和错误处理是构建可靠Skill的关键环节。当用户提供的参数不符合预期时，系统应当给出清晰的提示，而不是生成误导性的响应。

6.1 必填参数缺失检查

对于Skill执行所必需的参数，需要在prompt中明确要求并提供缺失时的处理逻辑。可以在prompt模板中使用条件判断逻辑，或直接在prompt中说明参数要求。

# 带参数验证的Skill定义
- name: 代码修复
  command: fix
  prompt: |
    请修复以下{{1}}代码中的bug：

    {{2}}

    # 验证说明
    如果用户没有提供{{1}}，请假设为python。
    如果用户没有提供代码内容，请询问用户提供。

6.2 参数类型验证

不同类型的参数需要不同的验证策略。例如，数字类型的参数需要验证是否为有效数字；路径类型的参数需要验证文件是否存在。

# 参数类型验证示例
- name: 性能测试
  command: bench
  prompt: |
    对 {{1}} 模块运行性能测试，迭代 {{2}} 次。

    # 如果{{2}}不是有效数字，提示用户
    注意：{{2}} 必须是正整数（如 100、1000）。
    如果 {{2}} 无效或缺失，默认使用 1000 次迭代。

6.3 友好的错误提示

当参数验证失败时，prompt应当引导用户提供正确的参数。好的错误提示应该包含问题描述、期望格式和示例。

错误提示设计原则：

1. 明确指出缺少哪个参数

2. 说明期望的参数格式

3. 给出具体的使用示例

4. 提供帮助命令（如 /help skill-name）的指引

6.4 常见错误场景及处理

错误场景	原因	处理方式
参数不足	用户提供的位置参数少于模板中的占位符	使用默认值或提示用户补充
参数顺序错误	用户混淆了参数的先后顺序	使用命名参数避免此问题
文件不存在	`{{FILE}}` 引用的路径无效	检查路径是否正确，文件是否存在
环境变量未设置	引用的环境变量不在当前进程中	提示用户设置对应环境变量
特殊字符转义	参数中包含引号、空格等特殊字符	使用引号包裹参数或进行转义

6.5 最佳实践总结

明确参数要求

在Skill的description中清晰说明所需参数和可选参数的格式。

提供默认值

对非关键参数提供合理的默认值，降低用户使用门槛。

合理的错误提示

参数缺失时给出清晰的指引，而不是让模型胡乱猜测。

优先命名参数

参数超过2个时优先使用命名参数，提高可读性和容错性。

善用FILE和ENV

大内容用FILE读取，敏感信息用ENV引用，避免硬编码。

持续测试

在多种参数组合下测试Skill行为，确保边缘情况处理正确。