自学教程

Skills 目录结构

Skills 教程

一个 Skill（技能包）本质是独立文件夹，用来存放AI智能体执行任务所需的全部资源。目录结构支持灵活配置：最简单的技能只需要单个 SKILL.md；复杂的企业级技能，可以划分多个子目录，存放示例、模板、脚本与测试用例，方便版本管理和团队协作。

完整目录示例

my-skill/
├── SKILL.md          # 必选。技能核心文件，入口
├── metadata.json     # 可选。扩展元数据
├── examples/         # 可选。输入输出样例
│   └── demo-case.md
├── templates/        # 可选。输出模板
│   └── report-template.md
├── scripts/          # 可选。可执行脚本
│   └── helper.py
└── tests/            # 可选。测试用例
    └── test-01.md

文件与目录说明

SKILL.md（必填）

整个技能包的入口文件，AI读取这个文件来理解技能。
文件顶部一般是YAML元数据，包含技能名称、描述、版本、作者。AI依靠description判断是否触发该技能。元数据下方是Markdown正文，定义任务目标、执行步骤、输出规范、边界约束与异常处理。

metadata.json（可选）

用于存放额外扩展信息，比如依赖项、标签、平台兼容信息，部分AI工具会读取这个文件做展示和校验。简单技能可以不创建。

examples/ 示例目录

存放任务样例，包含输入指令和对应的标准输出。AI在执行时可以参考样例，减少输出偏差，保证结果稳定。适合复杂业务场景。

templates/ 模板目录

存放固定格式模板，例如报告模板、邮件模板、Markdown文档模板。AI执行任务时直接套用模板，统一输出样式。

scripts/ 脚本目录

放置可执行代码，用来处理文件解析、接口调用、数据计算等动作。SKILL.md里可以指引智能体调用这些脚本完成操作。

tests/ 测试目录

存放测试用例，用于验证技能逻辑是否符合预期。每次修改SKILL.md之后，可以运行测试用例，防止更新后技能逻辑出错，适合团队长期维护。

两种目录模式

  1. 极简模式
    只保留 SKILL.md，没有其他子文件夹。适合简单场景，快速搭建、快速调试。
simple-skill/
└── SKILL.md
  1. 完整模式
    包含上面全部文件夹，适合企业业务场景，多人协同开发、持续迭代。

目录结构示意图（可直接放进文章）

┌─────────────────────────────────────┐
│ my-skill/（技能包根目录）            │
│  ├─ SKILL.md 【核心入口】            │
│  ├─ metadata.json 扩展信息           │
│  ├─ examples/ 样例参考               │
│  ├─ templates/ 输出模板              │
│  ├─ scripts/ 执行脚本                │
│  └─ tests/ 测试用例                  │
└─────────────────────────────────────┘
        ↓ AI读取逻辑
【第一步】读取 SKILL.md 头部元信息，判断技能是否匹配当前任务
【第二步】匹配成功，加载完整 SKILL.md
【第三步】按需读取 examples、templates、scripts、tests 资源

目录设计原则

  1. 职责分离：技能规则、样例、模板、脚本分开存放，不要全部写在SKILL.md中，方便单独修改维护。
  2. 按需添加：不需要的目录可以不创建，不要为了完整而增加多余文件。
  3. 适配渐进式加载机制：AI先读取SKILL.md头部元信息判断是否匹配任务；匹配成功后，才加载正文和相关资源文件。
  4. 支持Git版本管理：目录结构是纯文本文件，可以直接提交代码仓库，实现版本追踪、多人协作。

小结

Skills目录结构没有强制要求，核心是SKILL.md。其余目录都是可选扩展，按需选用。简单技能轻量化；业务复杂的技能，可以拆分examples、templates、scripts、tests目录，实现能力解耦，便于团队维护。

0 条笔记