skill-validator

Skill 验证器

根据生产级质量标准验证任意 Skill。

实施前

来源	收集内容
Skill 目录	SKILL.md、references/、scripts/、assets/
Skill 类型	Builder、Guide、Automation、Analyzer 或 Validator
对话	验证目的（审计、改进、评审）

此 Skill 不会做什么

• 在生产环境中测试 Skill
• 自动修复已发现的问题
• 验证 Skill 的运行时行为（仅验证结构和内容）
• 取代人类对领域准确性的判断

验证工作流

阶段 1：收集上下文

1. 完整阅读 Skill 的 SKILL.md
2. 根据 frontmatter 描述确定 Skill 类型：
   • Builder Skill（创建产物）
   • Guide Skill（提供说明）
   • Automation Skill（执行工作流）
   • Analyzer Skill（提取见解）
   • Validator Skill（执行质量要求）
   • Hybrid Skill（以上类型的组合）
3. 阅读 references/ 目录中的所有参考文件
4. 检查是否存在 assets/scripts 目录
5. 记录 frontmatter 字段（name、description、allowed-tools、model）

阶段 2：应用标准

根据 9 个标准类别进行评估。每项标准评分为 0-3：

• 0：缺失/不存在
• 1：存在但不充分
• 2：实现充分
• 3：实现出色

---

标准类别

1. 结构与组成（权重：12%）

标准	检查内容
SKILL.md 存在	根目录文件存在
行数	<500 行（上下文很宝贵）
Frontmatter 完整	YAML 中包含 name 和 description
名称限制	1-64 个字符；小写字母、数字和连字符；不能有连续连字符；不能以连字符开头或结尾；必须与目录名一致
描述格式	[内容] + [适用时机] 格式；≤1024 个字符
描述风格	第三人称：“This skill should be used when...”
无多余文件	Skill 目录中没有 README.md、CHANGELOG.md、LICENSE
渐进式披露	详细内容放在 references/ 中，不要让 SKILL.md 臃肿
资源组织	模板放在 assets/ 中，脚本放在 scripts/ 中
大型文件指导	如果 references 超过 10k 个单词，在 SKILL.md 中注明 grep 模式

失败条件：缺少 SKILL.md 或超过 800 行 = 自动判定失败

2. 内容质量（权重：15%）

标准	检查内容
简洁性	不写冗长说明；上下文是公共资源
祈使语气	使用“执行 X”，而非“你应该执行 X”
适当的自由度	需要约束之处设置约束，安全之处保持灵活
范围明确	明确 Skill 的功能和非功能
无幻觉风险	不包含鼓励编造信息的说明
输出规范	明确规定预期输出

3. 用户交互（权重：12%）

标准	检查内容
澄清触发条件	遇到歧义时，在采取行动前提问
必需与可选信息	区分必须了解的信息和锦上添花的信息
妥善处理	说明用户未作答时该如何处理
不过度提问	不询问显而易见或可推断的问题
提问节奏	避免在一条消息中提出过多问题
上下文感知	提问前先利用现有上下文

需要关注的关键模式：

## Required Clarifications
1. Question about X
2. Question about Y

## Optional Clarifications
3. Question about Z (if relevant)

Note: Avoid asking too many questions in a single message.

4. 文档与参考资料（权重：10%）

标准	检查内容
来源 URL	提供官方文档链接
参考文件	将复杂细节放在 references/ 中，而非主文件
获取指导	为未列出的模式提供获取文档的说明
版本意识	提醒检查最新模式
示例覆盖	为关键模式提供优质示例和反例

需要关注的关键模式：

| Resource | URL | Use For |
|----------|-----|---------|
| Official Docs | https://... | Complex cases |

5. 领域标准（权重：10%）

标准	检查内容
最佳实践	遵循领域惯例（例如，WCAG、OWASP）
执行机制	检查清单、验证步骤、必须核实的事项
反模式	列出不应采用的做法
质量门槛	交付前的输出检查清单

需要关注的关键模式：

### Must Follow
- [ ] Requirement 1
- [ ] Requirement 2

### Must Avoid
- Antipattern 1
- Antipattern 2

6. 技术稳健性（权重：8%）

标准	检查内容
错误处理	针对故障场景的指导
安全注意事项	输入验证、密钥处理（如适用）
依赖项	记录外部工具/API
边缘情况	处理常见边缘情况
可测试性	能否验证输出？

7. 可维护性（权重：8%）

标准	检查内容
模块化	引用内容为独立主题
更新路径	标准变更时便于更新
无硬编码值	在适当情况下使用占位符/变量
组织清晰	章节顺序合乎逻辑

8. 零样本实现（权重：12%）

技能应支持通过单次交互实现任务，并内嵌专业知识。

标准	检查内容
实现前章节	是否提供收集上下文的指导
代码库上下文	是否指导扫描现有结构/模式
对话上下文	是否使用已讨论的需求/决策
内嵌专业知识	领域知识是否放在 references/ 中，而非运行时发现
仅询问用户需求	只询问用户需求，不询问领域知识

需要关注的关键模式：

## Before Implementation

Gather context to ensure successful implementation:

| Source | Gather |
|--------|--------|
| **Codebase** | Existing structure, patterns, conventions |
| **Conversation** | User's specific requirements |
| **Skill References** | Domain patterns from `references/` |
| **User Guidelines** | Project-specific conventions |

危险信号：技能指示在运行时“研究”或“发现”领域知识，而不是将其内嵌。

9. 可复用性（权重：13%）

技能应能处理多种情况，而非单一需求。

标准	检查内容
处理多种情况	不针对单一用例硬编码
可变元素	澄清问题能捕捉变化内容
固定模式	将领域最佳实践编码为常量
不针对特定需求	避免硬编码数据、工具、配置
抽象层级	针对该领域进行适当泛化

优秀示例：

"Create visualizations - adaptable to data shape, chart type, library"

不佳示例（过于具体）：

"Create bar chart with sales data using Recharts"

关键检查：该技能能否用于其领域内的多个用例？

---

按类型验证

对通用标准评分后，验证特定类型的要求：

类型	必须具备
构建器	澄清问题、输出规范、领域标准、输出检查清单
指南	工作流步骤、示例（好/坏）、官方文档链接
自动化	scripts/ 中的脚本、依赖项、错误处理、I/O 规范
分析器	分析范围、评估标准、输出格式、综合分析
验证器	质量标准、评分细则、阈值、补救措施

评分：如果已识别类型缺少特定类型的要求，则扣 10 分。

---

评分指南

类别得分

计算各类别得分：

Category Score = (Sum of criterion scores) / (Max possible) * 100

总分

Overall = Σ(Category Score × Weight)

评级阈值

得分	评级	含义
90-100	生产就绪	可广泛使用
75-89	良好	需要少量改进
60-74	合格	功能可用，但仍需完善
40-59	开发中	存在明显缺口
0-39	未完成	需要大幅返工

---

输出格式

生成验证报告：

# Skill Validation Report: [skill-name]

**Rating**: [Production/Good/Adequate/Developing/Incomplete]
**Overall Score**: [X]/100

## Summary
[2-3 sentence assessment]

## Category Scores

| Category | Score | Weight | Weighted |
|----------|-------|--------|----------|
| Structure & Anatomy | X/100 | 12% | X |
| Content Quality | X/100 | 15% | X |
| User Interaction | X/100 | 12% | X |
| Documentation | X/100 | 10% | X |
| Domain Standards | X/100 | 10% | X |
| Technical Robustness | X/100 | 8% | X |
| Maintainability | X/100 | 8% | X |
| Zero-Shot Implementation | X/100 | 12% | X |
| Reusability | X/100 | 13% | X |
| **Type-Specific Deduction** | -X | - | -X |

## Critical Issues (if any)
- [Issue requiring immediate fix]

## Improvement Recommendations
1. **High Priority**: [Specific action]
2. **Medium Priority**: [Specific action]
3. **Low Priority**: [Specific action]

## Strengths
- [What skill does well]

---

快速验证检查清单

如需快速评估，请检查以下关键项目：

结构与 Frontmatter

• SKILL.md <500 行
• Frontmatter：name（≤64 个字符，仅小写字母和连字符）+ description（≤1024 个字符）
• Description 使用第三人称风格（“This skill should be used when...”）
• 技能目录中没有 README.md/CHANGELOG.md

内容与交互

• 是否包含澄清问题（必需 vs 可选）
• 是否包含输出规范
• 是否包含官方文档链接

零样本与可复用性

• 是否包含“实施前”部分（收集上下文）
• 是否将领域专业知识嵌入 references/（而非在运行时发现）
• 是否能处理各种变化（而非针对特定需求）

类型特定检查（根据 skill 类型检查）

• Builder：澄清 + 输出规范 + 标准 + 检查清单
• Guide：工作流 + 示例 + 文档
• Automation：脚本 + 依赖项 + 错误处理
• Analyzer：范围 + 标准 + 输出格式
• Validator：标准 + 评分 + 阈值 + 补救措施

勾选 10 项以上：很可能达到生产级（90+） 勾选 7–9 项：很可能表现良好（75–89） 勾选 5–6 项：很可能达到合格水平（60–74） 勾选少于 5 项：需要进行大量改进

---

参考文件

文件	何时阅读
references/detailed-criteria.md	深入评估特定标准
references/scoring-examples.md	用于校准的验证示例
references/improvement-patterns.md	常见问题的修复方法

---

使用示例

验证一个 skill

Validate the chatgpt-widget-creator skill against production criteria

快速审查

Quick validation check on mcp-builder skill

重点审查

Check if skill-creator skill has proper user interaction patterns