3.3 校验与打包

写完不等于能用。发布前必须过两道关：校验（结构合不合规）和打包（变成可分发的 zip）。

一、校验：`quick_validate.py`

python quick_validate.py "C:/Users/Administrator/.workbuddy/skills/my-skill"

输出 Skill is valid! 即通过；否则打印第一条错误原因并以非零码退出。

检查项	规则	不通过时的提示
`SKILL.md` 是否存在	必须存在	`SKILL.md not found`
文件是否以 `---` 开头	必须是	`No YAML frontmatter found`
frontmatter 是否成对闭合	第二个 `---` 必须存在	`Invalid frontmatter format`
`name` 字段	必须存在	`Missing 'name' in frontmatter`
`description` 字段	必须存在	`Missing 'description' in frontmatter`
`name` 命名规范	匹配 `^[a-z0-9-]+$`	`Name 'X' should be hyphen-case …`
`name` 形态	不以 `-` 开头/结尾，无 `--`	`Name 'X' cannot start/end with hyphen …`
`description` 内容	不能含 `<` 或 `>`	`Description cannot contain angle brackets …`

它只查结构与格式。以下问题它查不出来，要你自己保证：

所以有两份清单要用：机器校验清单（上面那张表）+ 人工质量清单（3.2 的自检清单）。

python package_skill.py "C:/Users/Administrator/.workbuddy/skills/my-skill" ./dist

zip 内部结构长这样：

my-skill.zip
└── my-skill/
    ├── SKILL.md
    ├── scripts/
    └── references/

这种「外面套一层同名目录」的结构能保证别人解压后直接得到一个合法 Skill 目录，而不是一堆散文件。分发时不要手动改这个结构。

报错	根因	修法
`SKILL.md not found`	文件名写错（小写、拼错）或路径指错	重命名为精确的 `SKILL.md`
`No YAML frontmatter found`	文件第一行不是 `---`	首行必须是 `---`，前面不能有空行/BOM
`Invalid frontmatter format`	缺第二个 `---`	补上闭合的 `---`
`Missing 'name'`	字段名拼错或漏写	加 `name:`
`Name 'MySkill' should be hyphen-case`	有大写/下划线/中文	全小写 + 连字符
`Name 'x' cannot start/end with hyphen`	首尾连字符或 `--`	去掉首尾连字符、合并连续连字符
`Description cannot contain angle brackets`	写了 `<` 或 `>`	用文字描述，或用「输入文件」这样的说法替代
校验通过但加载不生效	目录名 ≠ `name`、或放错位置	两者统一、确认在 `skills/` 下
zip 已存在同名文件	上次的产物	删掉旧 zip 或换输出目录

出问题时按这个顺序查，命中率最高：

三种做法，按工程化程度递增：

整理人：WorkBuddy