发布前 checklist
发布 Skill 前，不要只检查“能不能运行”。一份可分享、可团队复用的 Skill 至少要通过四类检查：格式、触发、执行、安全。
最后校验：2026-05-30
一页版
复制下面清单到 PR、Issue 或发布说明里即可：
markdown
## Skill 发布前检查
### 格式
- [ ] 目录名与 `SKILL.md` 的 `name` 完全一致
- [ ] `name` 使用 kebab-case
- [ ] `description` ≤ 1024 字符
- [ ] `description` 只说明能力与触发，不写执行步骤
- [ ] 没有把 `README.md` 放在 Skill 根目录
- [ ] 路径使用 `/`，不用 Windows 反斜杠
### 内容
- [ ] `SKILL.md` 第一屏能看出任务边界
- [ ] SOP 有编号步骤和完成标准
- [ ] 示例覆盖正常、边界、错误场景
- [ ] 长文档已拆到 `references/`
- [ ] 模板已拆到 `assets/`
- [ ] 确定性操作已考虑 `scripts/`
### 评估
- [ ] 至少 5 条 should-trigger query 通过
- [ ] 至少 3 条 should-not-trigger query 通过
- [ ] 至少 2 条 with / without 对照证明 Skill 有改善
- [ ] 修改 description 后重跑触发评估
- [ ] 修改正文或脚本后重跑执行评估
### 安全
- [ ] 没有硬编码密钥或真实隐私数据
- [ ] 高风险操作需要用户确认
- [ ] 脚本不会默认删除、覆盖、联网或上传
- [ ] 第三方依赖和外部 URL 已说明
- [ ] 第一次运行已在临时目录或沙箱验证格式检查
格式问题最容易自动化，也最适合放进 CI。
| 检查项 | 原因 |
|---|---|
目录名等于 name | 平台依赖这个映射加载 Skill |
description 不超长 | 过长会降低触发稳定性 |
不用 README.md | 部分平台可能优先读取或混淆入口 |
路径使用 / | 跨 Windows / macOS / Linux 稳定 |
| 引用文件存在 | 避免 agent 读取不存在的 references |
建议至少跑一次：
bash
skills-ref validate ./my-skill触发检查
触发检查回答：agent 是否在正确场景加载 Skill。
最低样例：
| 类型 | 数量 | 来源 |
|---|---|---|
| should-trigger | 5 条以上 | 真实用户说法 |
| should-not-trigger | 3 条以上 | 相邻但不归该 Skill 的任务 |
记录结果：
markdown
|query|期望|实际|结论|
|-|-|-|-|
|老板发了个 pdf 合同让我提取金额|触发|触发|通过|
|帮我把 Word 导出 PDF|不触发|不触发|通过|执行质量检查
触发后还要看任务有没有变好。
推荐用 with / without 对照：
markdown
|case|without skill|with skill|结论|
|-|-|-|-|
|合同金额汇总|漏掉罚息条款|完整列出金额并标页码|Skill 有明显改善|如果 with skill 没有明显改善，不要急着发布，先回到正文模式、脚本或 examples 调整。
安全检查
任何包含 scripts/、外部 URL 或工具权限声明的 Skill 都要额外审查。
高风险信号：
- 默认递归读取用户主目录
- 默认联网或上传文件
- 默认覆盖原文件
- 下载远程脚本后立即执行
- 把密钥、token、cookie 写在示例里
- 要求忽略系统或团队规则
详见 安全与信任模型。
版本信息
发布到团队或社区前，建议在 metadata 中记录：
yaml
metadata:
author: your-team
version: '1.0.0'
last_reviewed: '2026-05-30'如果平台不读取这些字段，也可以保留给人类 review。
推荐发布说明
markdown
## 发布内容
- Skill 名称：
- 适用平台：
- 主要能力：
- 依赖工具：
- 安全注意事项：
## 验证结果
- 格式校验：通过 / 未跑
- 触发评估：x/y 通过
- 执行评估：x/y 通过
- 安全审查：通过 / 待补充
## 变更风险
- 是否包含脚本：是 / 否
- 是否联网：是 / 否
- 是否写文件：是 / 否
- 是否需要人工确认：是 / 否主要参考
- agentskills.io Specification
- agentskills.io Best Practices
- Anthropic skills repository
- OpenAI Skills repository