一、本篇定位

本篇是 AI Skill 全套教程的核心奠基章节。YAML 头部是每一个 Skill 的唯一身份标识，也是 AI 识别、加载、触发技能的核心依据，直接决定 Skill 是否生效、触发是否精准、运行是否稳定。新手遇到的技能不触发、乱触发、加载失败、执行错乱等问题，90% 都是 YAML 头部书写不规范导致。

本篇全程适配零基础小白，摒弃晦涩理论，只讲可落地的语法规则、对照案例、通用模板。读完即可独立写出格式标准、触发精准、可直接商用的 Skill YAML 头部配置。

二、本篇学习目标

• 掌握 Skill 专属 YAML 基础语法与书写禁忌，彻底规避所有格式报错、加载异常问题
• 吃透 name、description 两大核心必填字段，熟练套用标准化编写公式，精准管控技能触发逻辑
• 熟练掌握各类可选字段用法，适配个人练习、团队协作、复杂项目等不同场景
• 精通 triggers 文件触发规则，完成实操配置，实现文件打开自动触发技能的高阶效果
• 直接套用两套万能模板，快速产出规范、稳定、高适配的商用级 Skill 头部配置

三、前置认知：什么是 Skill YAML 头部？

标准的 SKILL.md 文件分为两大核心模块，分工明确、缺一不可：

1. YAML Frontmatter上部：（头部元数据）：Skill 的身份配置中心，专供 AI 读取识别，用于定义技能身份、触发条件、生效范围、操作权限、依赖关系等核心属性。
2. 下部：Markdown 正文：Skill 的核心执行逻辑，用于写明任务流程、执行规则、参考示例、校验步骤，是技能具体工作的执行手册。

YAML 头部有硬性规范：必须使用 --- 包裹，放置在文件最顶部，无前置空行、无多余注释、无冗余内容，否则会直接解析失败。

标准基础形态示例：

1
2
3
4
5
6
7

---
# 所有技能配置均写在此区域
name: demo-skill
description: 示例技能基础描述
---

# 下方为Markdown正文执行逻辑

四、零基础必学：Skill YAML 基础语法与书写规则

YAML 属于高敏感严格语法，一个缩进、空格、符号错误，就会导致 Skill 加载失败、无法触发、功能异常。本节专为 Skill 场景提炼小白专属书写规则，熟记即可规避 100% 基础格式问题。

4.1 缩进规则（重中之重）

• 所有层级缩进统一使用 2 个英文空格，严禁使用 Tab 制表符
• 子字段必须相对父字段缩进一级，对齐错乱直接解析报错
• 禁止参差不齐、多空格、少空格、混用缩进方式

✅ 标准正确示范：

1
2
3
4
5
6

---
name: python-format
metadata:
  version: "1.0"
  author: "test"
---

❌ 错误示范（Tab缩进、层级错乱、格式缺失）：

1
2
3
4
5

---
name: python-format
   metadata: # 缩进层级过多，格式错乱
    version:1.0 # 冒号后无空格，语法违规
---

4.2 符号与换行规则

• 标准键值对格式：字段名: 空格 值，冒号后方必须保留1个英文空格
• 长文本、多行描述统一使用 >** 符号换行**，自动适配缩进、规整格式，专属适配 description 场景
• 禁止行尾遗留多余空格、配置块内无意义空行
• 常规特殊字符（冒号、引号、斜杠）无需手动转义，正常书写即可

4.3 Skill YAML 专属禁忌（小白必避）

• 禁止使用中文名称、中文空格、中文标点符号
• 所有字段名统一小写，禁止大小写混用
• 禁止保留空值字段，未使用的字段直接删除，不占位留空
• 文件顶部禁止添加注释、空行，必须顶格书写--- 起始标记

五、核心必填字段：name + description（决定技能触发成败）

name、description 为 Skill 强制必填字段，缺一不可。二者是 AI Level1 常驻加载的核心内容，是 AI 识别、匹配、触发技能的唯一核心依据，直接决定触发准确率与适配场景。

5.1 name 字段：技能唯一标识

核心作用

作为 Skill 的全局唯一 ID，用于技能识别、手动触发、路径匹配、子技能关联，全局不可重复、不可冲突。

强制规范（硬性红线标准）

• 全部使用小写英文字母
• 多单词组合统一使用连字符 - 连接
• 必须与技能文件夹名称完全一致（核心红线规则，90%触发异常源于此）
• 禁止中文、空格、下划线、特殊符号

✅ 规范案例：go-test-gen、python-code-sort、auto-comment

❌ 违规案例：GoTestGen（大写混用）、python sort（含空格）、代码排序（中文命名）

5.2 description 字段：触发核心逻辑（全篇重中之重）

核心作用

AI 自动语义触发的唯一依据。AI 会通过该字段的语义内容，判断用户当前指令是否需要调用当前技能，是整个 YAML 头部影响效果最大、最关键的配置项。

官方标准化编写公式（可直接无脑套用）

核心功能 + 触发关键词场景 + 适用范围 + 排他场景

1. 核心功能：一句话精准概括技能核心作用
2. 触发场景：罗列用户日常口语化指令关键词，适配自然对话
3. 适用范围：明确适配的编程语言、文件类型、项目场景
4. 排他场景：明确不适配场景，杜绝技能误触发、乱抢占任务

正反案例精准对比

❌反面案例（笼统模糊、无关键词、无边界，AI 无法精准判断）

1

description: 处理代码测试和优化

✅ 正面案例（标准规范、边界清晰、关键词明确、小白可直接抄改）

1
2
3
4

description: >
  为Go语言函数自动生成表驱动风格单元测试。
  用户提出写单测、补充测试用例、函数测试、生成单元测试时自动触发。
  仅适用于Go语言项目，不处理Python、前端代码优化、文档编写等场景。

小白优化实操技巧

• 字数控制在100字以内，适配 Level1 常驻 Token 限制，避免资源占用过高
• 植入用户高频口语指令，大幅提升技能触发命中率
• 明确排他场景，彻底解决多技能冲突、抢占任务的问题

六、可选字段全解：适配个人/团队高阶场景

可选字段不影响 Skill 基础运行，但能完善技能属性、约束操作权限、实现版本迭代、适配模块化架构，是团队规范化、复杂项目高阶 Skill 的必备配置。

6.1 metadata 元数据（版本、作者、更新时间）

用于记录技能基础溯源信息，方便版本迭代管理、维护者追溯，适配个人沉淀、团队协作场景。

1
2
3
4

metadata:
  version: "1.0" # 语义化版本：大版本.小版本
  author: "个人/团队名称"
  update_time: "2026-06-09"

6.2 tags 标签（技能分类管理）

用于批量归类技能，方便后期批量检索、筛选、统一管理大量 Skill。

1
2
3
4

tags:
  - 代码优化
  - Python
  - 自动化工具

6.3 permissions 权限约束（安全必备）

严格限制技能操作权限，规避误删文件、私自联网、篡改系统文件等安全风险，所有商用、高阶技能必须配置。

1
2
3
4

permissions:
  allow_delete: false # 禁止删除本地文件
  allow_network: false # 禁止发起网络请求
  allow_write: true # 允许修改当前项目文件

6.4 dependencies 依赖配置（模块化必备）

声明当前技能依赖的子技能，用于主/子技能模块化架构，保障技能执行顺序正确、依赖闭环。

1
2

dependencies:
  - env-check # 依赖环境检测子技能

6.5 disabled 禁用配置

临时禁用技能，无需删除文件、无需改动配置，仅关闭生效状态，适合暂停迭代、临时停用的技能。

1

disabled: true

七、重点实操：triggers 文件自动触发规则

triggers 是高阶自动化触发方案，无需用户手动输入指令，打开指定后缀、指定目录的文件即可自动加载并启用技能，是打造无感自动化 Skill 的核心配置。

7.1 核心作用

摆脱语义匹配、手动指令的局限性，基于文件路径、文件后缀刚性精准触发，触发准确率100%，彻底杜绝误触发、漏触发问题。

7.2 通配符规则（小白熟记、直接套用）

• *.py：匹配项目内所有 Python 后缀文件
• src/**/*.go：匹配 src 目录下所有子文件夹的 Go 文件
• **/*.md：匹配项目所有目录下的 Markdown 文件

7.3 完整实操案例

实操需求：打开项目内任意 Python 文件，自动触发代码导入语句格式化技能

1
2
3
4
5
6
7
8
9
10
11
12
13
14

---
name: python-code-sort
description: >
  自动整理Python代码import导入语句，统一代码格式。
  用户指令：整理导入、排序import、美化代码时触发，仅适配Python项目。
triggers:
  file_patterns:
    - "*.py"
metadata:
  version: "1.0"
  author: "test"
permissions:
  allow_delete: false
---

八、两套通用万能模板（零基础直接复制即用）

整理两套全覆盖通用模板，分别适配新手个人练习、团队商用复杂场景，覆盖99%的 Skill 开发需求，无需手动拼凑配置。

8.1 极简模板（新手个人练习首选）

1
2
3
4
5
6
7

---
name: 你的技能名
description: >
  核心功能描述。
  触发关键词：xxx、xxx、xxx。
  适用场景：xxx，不处理xxx场景。
---

8.2 完整版模板（团队协作/复杂项目/商用上线）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

---
name: 你的技能名
description: >
  清晰完整的核心功能。
  用户输入xxx、xxx、xxx指令时自动触发。
  适配xxx语言/项目，不处理文档、新增功能、其他语言代码场景。
metadata:
  version: "1.0"
  author: "团队名称/个人"
  update_time: "2026-06-09"
tags:
  - 分类1
  - 分类2
triggers:
  file_patterns:
    - "*.后缀"
permissions:
  allow_delete: false
  allow_network: false
dependencies:
  - 可选依赖技能名
---

九、高频报错避坑清单（新手必看）

1. 技能不触发：description 描述笼统、无核心触发关键词、未标注适用场景、文件夹名与 name 字段不一致
2. YAML 解析失败：使用 Tab 缩进、冒号后无空格、存在中文符号、行尾残留多余空格
3. 技能误触发：description 未设置排他场景，语义适配范围过宽，导致抢占无关任务
4. triggers 不生效：通配符书写错误、文件路径匹配规则不精准、后缀配置错误
5. Token 占用过高：description 内容冗余、字数超标，超出 Level1 常驻加载规范

十、课后练习（实操巩固、落地掌握）

1. 独立仿写一套完整 YAML 头部配置，实现「JS 代码自动格式化」技能，需包含标准 name、规范 description、文件自动触发规则、基础安全权限配置。

2. 自查纠错：对照本篇避坑清单，逐一排查自己编写的配置，修复所有格式错误、语义漏洞、规范问题。

3. 双场景测试验证：分别通过「语义对话指令」和「打开对应后缀文件」两种方式，验证技能触发精准、无误触发、无加载异常。