文件顶部用 — 包裹，包含必需和可选字段：

---
name: your-skill-name        # 必需：唯一标识，小写+连字符，≤64字符
description: >               # 必需：功能和触发场景，≤1024字符
  清晰描述这个 Skill 做什么、什么时候用。
  这是 AI 判断是否调用的关键依据。
license: MIT                 # 可选：许可证
version: "1.0"               # 可选：版本号
metadata:                    # 可选：扩展信息
  author: YourName
---

关于命名的硬性规则：

长度 2-64 字符，只能含小写字母、数字、连字符 -

首尾不能是 -，不能有连续的 –

不能使用 admin、api、auth 等保留字

元数据之后就是自由格式的 Markdown 指令，告诉 AI 具体怎么执行。可以参考这个结构：

# Skill 名称

## 概述
说明这个 Skill 解决什么问题，核心价值是什么。

## 适用场景 / 触发条件
明确什么时候该用、什么时候不该用。
- ✅ 适用情况：...
- ❌ 不适用情况：...

## 前置条件
执行前需要满足的条件。

## 处理步骤
### Step 1: 具体动作
### Step 2: 具体动作
### Step 3: 具体动作

## 输入/输出示例
给出具体例子，让 AI 理解期望的结果。

## 失败处理
告诉 AI 遇到问题怎么办。

任务变得复杂时，可以把内容拆分到不同目录，而不是全部塞进 SKILL.md：

my-skill/
├── SKILL.md              # 必需：入口指令文件
├── references/           # 可选：参考资料（模板、配置、术语表等）
│   ├── config.yaml
│   └── output-template.md
├── scripts/              # 可选：稳定动作脚本（解析、排序、去重等）
│   └── data_processor.py
└── assets/               # 可选：静态资源（图片、字体等）
    └── template.json

每个目录的职责：

SKILL.md：只写触发条件、核心流程、边界规则

references/：放模板、配置、示例、偏好说明——AI 按需读取

scripts/：放可稳定执行的脚本——确定性动作交给代码，比让 AI 临场发挥更可靠

assets/：放图片、模板文件等静态资源

description 是 AI 判断“什么时候用这个 Skill”的唯一入口。写得越具体，触发越准。

❌ 差的描述："翻译相关"
✅ 好的描述："将中文内容翻译成英文。当用户说'翻译'、'translate'或要求把中文转成英文时使用，保留专业术语和原有的语气。"

口诀：动作 + 触发关键词 + 关键约束。

下面这些事不应该让 AI 每次“临场发挥”：

解析 XML/JSON

去重、排序

读取固定格式文件

格式转换和字段校验

这些动作一旦写成脚本，每次结果一致，不会出现“这次漏一条、下次排序变了”的问题。AI 的价值在判断价值、归纳总结、风格把控这些语义层面。

Skill 的加载是分层的：

原则：Level 1 越精准越好，Level 2 越精简越好，Level 3 放心放（按需加载不占常驻空间）。

每个 Skill 只做一件事。把“运行测试 + 更新状态 + 发通知”塞进一个 Skill，AI 容易搞混，触发也容易错。

如果你手头有一个重复流程想做成 Skill，可以按这个步骤来：

写清楚触发场景——一句话说清什么情况下用

拆出固定流程——写成“先做什么、后做什么”的顺序步骤

把材料移到 references/——模板、配置、风格偏好别塞进 SKILL.md

把稳定动作脚本化——解析、排序、去重交给脚本

把 AI 留给真正需要判断的部分——价值判断、风格把控、归纳总结

一个简单的判断标准：同样的规则跟 AI 纠正了 3 次以上，就该写 Skill 了。 一次性的任务直接用提示词，别折腾。