Skills 开发指南：YAML 规范与工程实践
想让 AI 帮你自动清理电脑、分析股票或者发日报？你需要给它编写一个 Skill (技能)。
其实写一个 Skill 并不难，它本质上就是一个配置文件加上一段代码。
本文档将手把手教你如何创建一个标准的 Skill，并避开新手最容易踩的坑。
一、 YAML 头部元数据 (Frontmatter)
每个 Skill 的入口文件（通常叫 SKILL.md），由 “身份证” (YAML) 和 “躯干” (文件结构) 组成，最开头都必须有一段被三根短横线 --- 包裹的内容。
这叫做 YAML Frontmatter (头部元数据)。
通俗地说，这就是给 AI 看的身份证。AI 通过它来知道这个技能叫什么、能干什么。
1. 一个标准的身份证长这样：
--- name: system-cleaner description: "清理电脑里的垃圾文件，释放C盘空间" tags: ["清理", "系统", "优化"]
version: 1.0.0 ---2. 这里的每一行代表什么？
td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | String | 是 | 技能 ID。建议使用 kebab-case (小写短横线)，如 git-helper。 |
| description | String | 是 | 核心 Prompt。智能体依靠这句话来理解技能用途。建议包含具体动词（如 "清理"、“生成”）。 |
| tags | Array | 是 | 关键词列表。用于模糊匹配和分类检索。 |
| version | String | 否 | 版本号。遵循语义化版本 (Major.Minor.Patch)。 |
二、文件夹要怎么放？(目录结构)
写代码最怕乱。为了以后好维护，建议你按照下面的结构来整理文件。
这就好比把衣服、裤子和袜子分开放进不同的抽屉，找起来才快。
推荐的 “三抽屉” 结构：
my-skill/ # 你的技能总文件夹
├── SKILL.md # [身份证] 上面写的 YAML 就放这里
├── scripts/ # [工具箱] 所有的代码脚本放这里
│ ├── main.ps1 # 比如 PowerShell 脚本
│ └── utils.py # 比如 Python 脚本
├── config/ # [设置] 配置文件放这里
│ └── settings.json # 比如你想让用户设置“清理哪个盘”，就写在这里
└── data/ # [仓库] 存放运行结果
└── logs/ # 如果有日志，就生成在这里 三、 代码实战 (The Code)
光有配置是不够的，Skill 的灵魂在于代码。
Skill 的本质是命令行工具 (CLI)。智能体通过命令行调用你的脚本，并读取打印的输出。
我们来编写一个简单的 Python 脚本，它接收一个名字参数，并输出问候语。
import argparse
import sys
# 1. 设置参数解析 (让脚本能听懂 AI 的指令) # AI 会以 `python main.py --name "LO"` 的方式调用
parser = argparse.ArgumentParser(description="Greeter Skill")
parser.add_argument("--name", type=str, required=True, help="要问候的名字")
# 2. 解析参数
args = parser.parse_args()
# 3. 执行逻辑 (这里可以写任何业务逻辑)
greeting = f"👋 你好，{args.name}！Skill 运行成功！" # 4. 输出结果 (这是 AI 唯一能看到的东西！) # 必须使用 print 输出。AI 会捕获 stdout 作为执行结果。 print(greeting)
- 错误处理: AI 看不到报错弹窗。如果出错，必须打印错误信息并以非 0 状态码退出。
try:
# 业务逻辑... except Exception as e:
print(f"❌ 发生错误: {str(e)}")
sys.exit(1) # 告诉 AI 任务失败 - 依赖管理：如果用了第三方库，请在根目录创建
requirements.txt。
你已经建了 config 文件夹，现在教你怎么用它。
2.1 读取外部配置 (Reading Config)
不要把参数写死在代码里！用 json 库读取 settings.json。
import json
import os
# 动态找到 config 文件夹 (不管用户把 Skill 放在哪)
current_dir = os.path.dirname(os.path.abspath(__file__))
config_path = os.path.join(current_dir, "..", "config", "settings.json")
# 读取配置
with open(config_path, "r", encoding="utf-8") as f:
config = json.load(f)
print(f"✅ 读取到配置: {config}")
2.2 与用户对话 (Interaction)
有时候需要问用户 “确定吗？”。
# 1. 打印问题 (AI 会展示给用户) print("❓ 确认执行操作吗？(y/n)")
# 2. 等待输入 (脚本会暂停)
user_input = input().strip().lower()
if user_input == 'y':
print("🚀以此执行...")
else:
print("🛑 操作取消")
四、 新手避坑指南 (千万别踩这些雷！)
YAML 这种格式虽然看起来简单，但它脾气很怪。很多新手写代码一次过，却在 YAML 上卡半天。
YAML 依靠缩进来分层级。
雷区：千万不要用键盘左上角的
Tab键来缩进！正确做法：老老实实按 空格键。一般按 2 下或 4 下空格。
这是最容易被忽略的错误。
错误写法：
name:my-skill(冒号后面紧挨着字)正确写法：
name: my-skill(冒号后面加了个空格)
路径别写死 (No Absolute Paths)：
不要在代码里写
D:\我的项目\scripts这种绝对路径。别人的电脑可能只有 C 盘。- 建议：使用 “相对路径”。也就是告诉程序 “就在当前文件夹的下一级找”。
幂等性 (Idempotency)：
- 脚本应支持重复运行。比如创建文件夹前，先检查它是否已经存在。
自测 (Self-Test)：
- 在提交给 AI 之前，先自己在终端里跑一遍命令：
python scripts/main.py --name "Test"，确保没有报错。
- 在提交给 AI 之前，先自己在终端里跑一遍命令：
总结
写 Skill 其实就三句话：
写好 YAML 身份证，注意冒号后要空格
把代码和配置分开放，保持目录整洁
代码里多打印进度提示，方便 AI 理解
