问题现象
在 CoPaw v0.1.0post1版本后，自定义 Skill 的 SKILL.md 文件如果没有 YAML Front Matter，会导致技能加载失败：
ERROR ... Failed to register skill 'my_skill': The SKILL.md file must have a YAML Front Matter including `name` and `description` fields.
官方文档说明
根据 Skills 文档，YAML Front Matter 的描述是：
可选 在文件开头用 YAML front matter 定义元数据
文档中写的是"可选"，但实际运行时会报错，存在文档与代码不一致的问题。
正确格式
SKILL.md 文件必须以 YAML Front Matter 开头：
---
name: my_skill
description: 技能的简短描述
---
# 技能标题
技能的详细说明...
字段说明
| 字段 |
必填 |
说明 |
name |
✅ |
技能名称，用于调用 |
description |
✅ |
技能描述，用于 Agent 理解何时使用 |
metadata |
❌ |
可选元数据，如版本号、emoji 等 |
可能受影响的场景
- 从旧版本升级 — 旧版本可能不检查格式
- 手动创建 Skill — 用户可能不知道格式要求
- 复制官方 Skill 后修改 — 如果删除了 YAML 头部
建议
- 更新文档 — 将"可选"改为"必填"，明确说明格式要求
- 或修改代码 — 如果确实是"可选"，则代码不应报错
- 增加提示 — 在
copaw skill create 命令中生成模板时包含 YAML 头部
临时解决方案
如果遇到此问题，在 SKILL.md 文件开头添加 YAML Front Matter 即可：
---
name: 技能名称
description: 技能描述
---
参考
问题现象
在 CoPaw v0.1.0post1版本后，自定义 Skill 的
SKILL.md文件如果没有 YAML Front Matter，会导致技能加载失败：官方文档说明
根据 Skills 文档，YAML Front Matter 的描述是：
文档中写的是"可选"，但实际运行时会报错，存在文档与代码不一致的问题。
正确格式
SKILL.md文件必须以 YAML Front Matter 开头：字段说明
namedescriptionmetadata可能受影响的场景
建议
copaw skill create命令中生成模板时包含 YAML 头部临时解决方案
如果遇到此问题，在
SKILL.md文件开头添加 YAML Front Matter 即可：参考
active_skills/cron/SKILL.md