一、教程目标与适用场景

本教程旨在帮助开发者掌握通过结构化文档（Skill）定制AI业务逻辑的核心方法，重点解决三个问题：1）如何用Markdown文件定义AI可执行的业务流程；2）如何通过YAML配置实现意图识别与Skill触发；3）如何通过模板、脚本和示例提升AI输出的准确性。适用于需要构建智能客服、自动化报告生成、数据清洗等场景的开发者和技术负责人。

二、前置准备与核心概念

1. 基础环境要求

   • 具备Markdown语法基础（重点掌握YAML frontmatter和列表语法）
   • 理解JSON/YAML数据结构（用于配置解析）
   • 掌握基础Shell脚本编写能力（可选，用于脚本集成）

2. 核心概念澄清

   • Skill≠插件：不同于传统插件机制，Skill通过文档定义行为而非代码扩展能力
   • 意图识别机制：当用户输入匹配YAML中定义的trigger_phrases时，AI加载对应Skill
   • 多步骤工作流：通过Markdown列表定义操作顺序，每个步骤可包含变量替换、条件判断等逻辑

三、Skill目录结构规范

典型Skill目录包含5类核心文件，其组织方式直接影响AI处理效率：

my-skill/
├── SKILL.md          # 主指令文件（必需）
├── templates/        # 模板目录（可选）
│   └── report.md     # 输出模板文件
├── references/       # 参考文档（可选）
│   └── style-guide.md
├── examples/         # 示例输出（可选）
│   └── sample.md
└── scripts/          # 可执行脚本（可选）
    └── validate.sh

关键设计原则：

1. 文件层级不超过3层（避免AI路径解析复杂度过高）
2. 模板文件必须使用.md扩展名（确保AI能正确解析）
3. 脚本文件需具备可执行权限（chmod +x validate.sh）

四、SKILL.md核心配置解析

主指令文件由YAML frontmatter和Markdown正文组成，其结构直接影响AI行为：

1. YAML配置规范

---
skill_name: "Data Processing Pipeline"
version: "1.0.0"
description: "处理用户上传的CSV数据并生成可视化报告"
trigger_phrases:
  - "分析数据"
  - "生成报表"
  - "处理CSV"
variables:
  - name: "input_file"
    type: "string"
    required: true
  - name: "chart_type"
    type: "enum"
    options: ["bar", "line", "pie"]
    default: "bar"
---

配置项详解：

• trigger_phrases：支持正则表达式匹配，建议包含3-5个核心触发词
• variables：定义输入参数时，enum类型需配合options使用以限制取值范围
• version：遵循语义化版本规范，便于技能迭代管理

2. Markdown正文设计

正文部分采用”步骤-说明-示例”三段式结构：

# 数据处理流程
## 步骤1：数据验证
执行以下验证逻辑：
1. 检查文件扩展名是否为.csv
2. 验证首行是否包含预期列名
3. 统计数据行数
**失败处理**：若验证失败，返回错误模板`error_template.md`
## 步骤2：数据转换
使用Pandas库执行以下操作：
```python
# 伪代码示例
df = pd.read_csv(input_file)
df['new_column'] = df['old_column'] * 2

步骤3：可视化生成

根据chart_type参数选择图表类型：

• bar: 生成柱状图
• line: 生成折线图
• pie: 生成饼图
  ```

设计要点：

1. 每个步骤保持原子性（避免跨步骤状态依赖）
2. 关键操作需提供伪代码示例（即使AI不直接执行代码）
3. 明确失败处理路径（避免AI陷入无限循环）

五、模板系统深度集成

模板文件通过变量替换机制实现动态内容生成，其核心语法如下：

1. 基础变量替换

# 报告标题
{{skill.name}}执行结果报告
# 数据概览
处理文件：{{variables.input_file}}
生成时间：{{current_timestamp}}

2. 条件渲染语法

{{#if variables.chart_type == "bar"}}
![柱状图]({{chart_url}})
{{else if variables.chart_type == "line"}}
![折线图]({{chart_url}})
{{/if}}

3. 循环结构示例

## 数据明细
| 列名 | 最大值 | 最小值 |
|------|--------|--------|
{{#each columns as |column|}}
| {{column.name}} | {{column.max}} | {{column.min}} |
{{/each}}

最佳实践：

1. 模板变量命名采用snake_case规范
2. 复杂逻辑建议通过脚本预处理后传入模板
3. 保留原始数据作为附件（便于人工复核）

六、脚本集成与验证机制

脚本文件可实现三类核心功能：

1. 输入预处理脚本

#!/bin/bash
# validate.sh 示例
if [[ ! $1 =~ \.csv$ ]]; then
  echo "错误：仅支持CSV格式文件"
  exit 1
fi
# 验证列名是否符合预期
expected_headers=("id","name","value")
actual_headers=$(head -n 1 $1 | tr ',' '\n')
for header in "${expected_headers[@]}"; do
  if ! echo "$actual_headers" | grep -q "$header"; then
    echo "错误：缺少必要列 $header"
    exit 1
  fi
done

2. 输出后处理脚本

#!/bin/bash
# postprocess.sh 示例
# 压缩生成的图片文件
for file in *.png; do
  pngquant --quality 65-80 --output "${file%.png}-compressed.png" "$file"
done

3. 验证机制设计

1. 前置验证：在Skill触发时执行（如文件格式检查）
2. 后置验证：在输出生成后执行（如报告完整性检查）
3. 异常处理：验证失败时返回预定义的错误模板

七、结果验证与调试方法

1. 验证检查清单

1. 触发短语测试：使用不同表述验证意图识别准确性
2. 变量传递测试：检查复杂数据结构（如嵌套JSON）的解析正确性
3. 模板渲染测试：验证所有条件分支的输出结果
4. 脚本执行测试：在沙箱环境中验证脚本权限和依赖

2. 调试工具推荐

1. 日志系统：通过console.log()输出中间变量（需AI平台支持）
2. 模拟环境：使用Postman等工具模拟API调用
3. 版本对比：通过Git差异分析修改影响范围

八、常见问题与解决方案

1. 意图识别偏差

现象：用户输入未触发预期Skill
原因：trigger_phrases覆盖不足或存在歧义
解决：

• 增加同义词触发词（如”生成报表”和”创建报告”）
• 使用正则表达式实现模糊匹配
• 添加否定触发词排除干扰场景

2. 变量解析失败

现象：模板中变量显示为{{undefined}}
原因：变量名拼写错误或未在YAML中声明
解决：

• 启用严格模式（若平台支持）强制变量声明
• 使用默认值语法：{{variables.name|default:"N/A"}}
• 在开发环境添加变量存在性检查

3. 脚本执行错误

现象：AI返回脚本执行失败但无详细日志
原因：脚本权限不足或依赖缺失
解决：

• 为脚本添加执行权限：chmod +x *.sh
• 在脚本开头声明依赖：#!/bin/bash -e
• 使用绝对路径引用外部工具

九、性能优化建议

1. 模板优化：

   • 避免在模板中使用复杂逻辑（预处理数据后再传入）
   • 对大文本输出采用分页机制
   • 压缩图片等二进制附件

2. 脚本优化：

   • 使用轻量级语言（如Python替代Java）
   • 添加缓存机制避免重复计算
   • 实现并行处理（如多线程数据处理）

3. 配置优化：

   • 为高频使用的Skill设置较高优先级
   • 定期清理未使用的旧版本Skill
   • 对大型Skill拆分为多个子Skill

十、总结与展望

通过结构化文档定义AI行为，实现了业务逻辑与AI能力的解耦设计。开发者现在可以：

1. 使用Markdown这种轻量级格式快速迭代业务流程
2. 通过YAML配置实现精细化的意图识别
3. 借助模板系统确保输出格式一致性
4. 利用脚本扩展实现复杂业务规则

未来发展方向包括：Skill版本管理系统、多Skill协同工作流、以及基于使用数据的自动优化机制。掌握这种设计模式，将使开发者在构建智能应用时获得更高的灵活性和可维护性。