Skills: 变量与模板系统
最后更新：2026-08-31
变量让 Skill 从"写死的模板"变成"灵活的工具"——一份定义，千次复用。
1. 变量类型
(1) 用户输入变量
由调用者提供的参数：
YAML
variables:
- name: target_file
description: "要审查的文件路径"
required: true
- name: severity_level
description: "最低严重程度"
default: "warning"
choices: ["info", "warning", "error", "critical"]
(2) 环境变量
从运行环境自动获取：
YAML
variables:
- name: current_branch
type: env
source: "GIT_BRANCH"
- name: project_root
type: env
source: "PROJECT_ROOT"
(3) 上下文变量
从对话或项目上下文注入：
YAML
variables:
- name: tech_stack
type: context
source: "project.language"
- name: changed_files
type: context
source: "git.changed_files"
2. 模板语法
(1) 基本替换
MARKDOWN
请审查 {{target_file}}，重点关注 {{severity_level}} 级别以上的问题。
(2) 条件渲染
MARKDOWN
## 审查策略
{{#if tech_stack == "python"}}
按 Python 规范审查：type hints、docstring、PEP 8
{{/if}}
{{#if tech_stack == "typescript"}}
按 TypeScript 规范审查：类型安全、any 检测、接口定义
{{/if}}
(3) 循环渲染
MARKDOWN
## 变更文件清单
{{#each changed_files}}
- {{this}}
{{/each}}
(4) 默认值与回退
MARKDOWN
代码风格遵循 {{linter_config || "行业默认标准"}}。
3. 变量验证
(1) 类型校验
YAML
variables:
- name: max_lines
type: integer
min: 10
max: 500
default: 100
- name: output_format
type: enum
choices: ["markdown", "json", "table"]
default: "markdown"
(2) 必填检查
TEXT
📖 仅展示
变量验证流程：
1. 检查所有 required 变量是否提供
2. 检查类型是否匹配
3. 检查值是否在 choices 范围内
4. 检查 min/max 约束
5. 未提供且有 default → 使用默认值
6. 验证失败 → 提示用户补充
4. 变量实战
▶ 示例：参数化部署 Skill
Alice 创建了一个灵活的部署 Skill：
YAML
---
name: smart-deploy
variables:
- name: environment
description: "部署环境"
required: true
choices: ["staging", "production"]
- name: skip_tests
description: "是否跳过测试"
type: boolean
default: false
- name: rollback_on_fail
description: "失败时是否回滚"
type: boolean
default: true
---
MARKDOWN
# 部署到 {{environment}}
{{#if skip_tests}}
⚠️ 跳过测试，直接部署
{{/if}}
{{#if !skip_tests}}
1. 运行完整测试套件
2. 确认所有测试通过
{{/if}}
3. 部署到 {{environment}}
{{#if rollback_on_fail}}
4. 验证部署成功，失败则自动回滚
{{/if}}
Bob 评价："参数化让一个 Skill 顶十个——staging 和 production 不用写两份，一个变量搞定。"
❓ 常见问题
Q 变量太多会不会让 Skill 变复杂？
A 会。建议核心变量不超过 5 个，可选变量不超过 3 个。超过则考虑拆分为多个 Skill。
Q 不同平台的模板语法一样吗？
A 不同。Claude Code 用
{{var}}，Cursor 用 $var，Copilot 用 ${var}。本课语法以 Claude Code 为例，概念跨平台通用。Q 变量能不能在运行时动态计算？
A 可以，通过上下文变量和环境变量实现。但复杂计算建议在 Skill 提示词中用自然语言描述逻辑，让 AI 自行推导。
📖 小节
- 三类变量：用户输入、环境变量、上下文变量
- 模板语法：替换、条件、循环、默认值
- 变量验证：类型、必填、范围约束
- 设计原则：核心变量 <5 个，合理设置默认值
📝 作业
- 基础题（难度⭐）：为 code-review Skill 添加
severity_level变量，控制审查输出级别。 - 进阶题（难度⭐⭐）：创建一个参数化部署 Skill，支持环境选择、是否跳过测试、回滚策略三个变量。
- 挑战题（难度⭐⭐⭐）：设计一个变量验证系统，处理类型校验、依赖关系（如选了 production 必须提供审批人）和动态默认值。
