# 01 · Skill 的基本结构

第一次接触 Markdown？可以先看[Markdown 使用](../Markdown使用.md)，了解怎样打开预览。

建议依次阅读：**基本结构 → [怎样使用](02-Skill怎样使用.md) → [借助 skill-creator 创建](03-借助skill-creator创建.md)**。三篇都以“把学习笔记整理成复习卡”为例。

## Skill 是什么

Skill 是供 AI 助手反复使用的一组任务说明，可以附带脚本、参考资料和模板。它把你的做事方法、偏好和检查规则保存下来，方便以后处理同类任务。

例如，你每次整理笔记都希望“按主题分组、用问答形式、保留公式、把疑点单列”。这些规则可以保存为一个 Skill；每次使用时，再提供新的笔记。

**执行任务的仍然是 AI 助手。** Skill 告诉它怎样做；搜索、读写文件、运行代码等能力由所用平台提供。

## 一个 Skill 包含什么

最简单的 Skill 只需要一个文件夹和其中的 `SKILL.md`。任务复杂时，可以按需添加资源：

```text
my-skill/
├── SKILL.md       必需：用途与操作说明
├── scripts/       可选：处理数据等用到的代码
├── references/    可选：规则、资料、操作文档
└── assets/        可选：输出时使用的模板等资源
```

添加资源时，应在 `SKILL.md` 中说明何时、怎样使用。

本例为方便教学理解而做了简化，只包含 SKILL.md。实际任务是否需要脚本、参考资料等，由具体需求决定。

## 看懂 SKILL.md

文件开头由两行 `---` 包住的部分叫“元数据”，后面是 Markdown 正文。下面是**结构示意**，帮助你读懂 AI 生成的文件，无需先手写：

```markdown
---
name: note-review-cards
description: 将已有学习笔记整理成问答复习卡，适用于复习材料整理。
---

# 笔记复习卡

按主题整理用户提供的笔记，每张卡只问一个问题。
保留公式和必要条件，将相互矛盾的信息单列为“待核对”。
（省略）……
```

| 部分 | 作用 |
| --- | --- |
| `name` | Skill 的名称，方便识别和点名使用；与文件夹同名 |
| `description` | 说明做什么、何时用，帮助 AI 判断是否适合当前任务 |
| 正文 | 说明具体方法、个人偏好、输出形式，以及如何处理异常情况 |

正文可以用中文，标题和段落按任务组织。命名与格式可交给 skill-creator 处理；你主要检查skill实现效果是否符合自己的需求。

结构依据：[Agent Skills 格式规范](https://agentskills.io/specification)。