自学教程

Skills 基本结构

Skills 教程

一个 Skill（技能包）本质上是一个独立文件夹，用来存放AI智能体执行任务所需的全部资料。它不是单一的文本，而是一套完整、可分发、可版本管理的文件集合。其中 SKILL.md 是核心必选文件，其他文件属于可选资源，可以根据场景按需增减。

核心文件：SKILL.md

SKILL.md 是整个技能包的入口，AI智能体读取这个文件，就知道这个技能什么时候触发、任务怎么做、输出要遵守什么规范。文件一般分为两大部分：头部元信息，以及主体任务指引。

  1. 头部元信息（YAML 配置段）
    放在文件最顶部，用来描述技能的基础信息，供智能体快速扫描识别，不会占用过多 Token。
    一般包含：
  • name：技能唯一名称，英文小写，短横线分隔，例如 excel-data-analysis
  • description：简短描述，说明这个技能能解决什么问题，最重要的是定义触发关键词。AI 就是靠这段描述判断是否启用当前技能。
  • version：技能版本号，用于迭代管理
  • author：作者或团队名称

示例片段

---
name: excel-data-analysis
description: 处理Excel表格，读取数据，统计汇总并生成分析报告。用户提到excel、表格统计、数据分析时触发本技能。
version: 1.0.0
author: demo-team
---
  1. 主体内容（Markdown）
    元信息下面就是正文，编写给AI阅读的操作规范，通常包含：
  • 任务目标：明确这个技能要达成的最终效果
  • 触发规则补充：边界条件，什么场景不适用该技能
  • 分步执行流程：AI需要遵循的操作步骤
  • 输出格式规范：返回结果的格式、排版、约束要求
  • 注意事项与错误处理：遇到异常情况该如何应对

可选配套文件与目录

除了 SKILL.md，我们可以在同一个技能文件夹下增加辅助资源，丰富技能能力。完整目录结构示例：

excel-data-analysis/
├── SKILL.md          # 【必选】技能主文件
├── metadata.json     # 可选，扩展元数据
├── examples/         # 可选，存放输入输出示例
│   └── sample-report.md
├── templates/        # 可选，结果输出模板
│   └── report-template.md
├── scripts/          # 可选，配套脚本，供技能调用
│   └── parse_excel.py
└── tests/            # 可选，测试用例，验证技能是否正常工作
    └── test-case.md

各目录简单说明：

  • examples：存放样例，给AI参考正确的输入和输出，减少结果偏差
  • templates：固定模板，让AI输出内容保持统一格式
  • scripts：可执行脚本，处理文件、计算、接口请求等动作
  • tests：测试用例，用来验证技能逻辑是否符合预期

Skill 的加载机制和结构设计思路

Skills 使用渐进式加载，这个特性决定了为什么要把结构拆成「元信息」和「详细正文」：

  1. 智能体只会一次性读取所有技能的简短描述，快速筛选匹配的技能；
  2. 只有任务匹配成功，才加载该技能完整的 SKILL.md 和相关资源；
  3. 不会一次性加载全部技能内容，节省 Token，避免上下文溢出。

设计要点：
元信息描述要简洁；详细流程写在正文；资源文件单独存放，不要全部堆在 SKILL.md 里。

简单对比：最小Skill vs 完整Skill

  • 最小Skill：仅一个 SKILL.md 文件，适合简单任务，快速上手开发
  • 完整Skill：包含示例、模板、脚本、测试目录，适合企业团队长期维护、多人协作

小结

Skill 的核心骨架就是 SKILL.md，YAML头部负责让AI快速识别技能，Markdown正文定义任务流程。其他文件夹都是可选扩展资源。
这种目录结构把规则、模板、脚本、测试分开管理，方便使用Git做版本控制，一次编写，跨平台复用。

标签：

0 条笔记