3.9 KiB
3.9 KiB
🏆 质量标准与验证标准
要将 Antigravity Awesome Skills 从脚本集合转变为可信平台，每个技能都必须达到特定的质量和安全标准。
"Validated" 徽章 ✅
技能只有在满足以下 6 项质量检查 后才能获得 "Validated" 徽章。其中一些检查目前已自动执行，而其他检查仍需要审查人员判断：
1. 元数据完整性
SKILL.md 前置元数据必须是有效的 YAML 并包含：
name：kebab-case 格式，与文件夹名称匹配description：200 字符以内，清晰的价值主张risk：[none, safe, critical, offensive, unknown]之一。仅对遗留或未分类技能使用unknown；新技能优先使用具体级别source：指向原始源的 URL（如果是原创则为 "self"）
2. 清晰的触发条件（"使用时机"）
技能必须有一个明确说明何时触发它的部分。
- 良好："当用户要求调试 React 组件时使用"
- 不佳："此技能帮助你处理代码"
接受的标题：
## When to Use、## Use this skill when、## When to Use This Skill
3. 安全与风险分类
每个技能必须声明其风险级别：
- 🟢 none：纯文本/推理（例如：头脑风暴）
- 🔵 safe：读取文件、运行安全命令（例如：代码检查器）
- 🟠 critical：修改状态、删除文件、推送到生产环境（例如：Git 推送）
- 🔴 offensive：渗透测试/红队工具。必须有 "授权使用" 警告
4. 可复制粘贴的示例
至少有一个代码块或交互示例，用户（或代理）可以立即使用。
5. 明确的限制
已知边缘情况或技能_无法_做的事情列表。
- 示例："在没有 WSL 的 Windows 上不工作"
6. 指令安全审查
如果技能包含命令示例、远程获取步骤、密钥或变更指导，PR 必须记录风险并通过 npm run security:docs 以及正常验证。
对于添加或修改 SKILL.md 的拉取请求，GitHub 还会运行自动化的 skill-review 工作流。将该审查视为正常 PR 质量门槛的一部分，并在合并前解决任何可操作的发现。
npm run security:docs 强制执行仓库范围的扫描：
- 命令管道，如
curl ... | bash、wget ... | sh、irm ... | iex - 内联令牌/密钥风格的命令示例
- 通过
<!-- security-allowlist: ... -->明确允许的高风险文档命令
额外的维护者审计
当您需要超出架构验证的仓库范围报告时，使用 npm run audit:skills 并回答：
- 哪些技能结构有效但仍需要可用性清理
- 哪些技能仍有截断的描述（问题
#365） - 哪些技能缺少示例或限制
- 哪些技能具有最高浓度的警告/错误
支持级别
我们还按维护者分类技能：
| 级别 | 徽章 | 含义 |
|---|---|---|
| Official | 🟣 | 由核心团队维护。高可靠性。 |
| Community | ⚪ | 由生态系统贡献。尽力支持。 |
| Verified | ✨ | 已通过深度手动审查的社区技能。 |
如何验证您的技能
规范的验证器是 tools/scripts/validate_skills.py，但在提交 PR 之前推荐的入口点是 npm run validate：
npm run validate
npm run audit:skills
npm run validate:references
npm test
npm run security:docs
注意：
npm run validate是操作性的贡献者门槛npm run audit:skills是面向维护者的整个库的合规性/可用性报告npm run security:docs对于命令繁重或风险技能内容是必需的- 触及
SKILL.md的 PR 还会获得自动化的skill-reviewGitHub Actions 检查 npm run validate:strict是一个有用的加固过程，但仓库仍包含尚未满足严格验证的遗留技能- 示例和限制即使当前验证器未完全自动强制执行，仍是质量标准的一部分