SkillHub 技能发布验证器 v1.0.0
> 文档版本：1.0.0
> 创建日期：2026-05-25
> 核心定位：自动化 SkillHub 发布合规性检查工具
一、核心功能
1.1 验证范围
| 验证类别 | 检查项 |
|---|---|
| Frontmatter 规范 | name, version, description, tags, icon, author, license, schema_version, metadata |
| 文件规范 | 文件数 < 200, 总大小 < 10MB, 无 pycache, 无 .pyc |
| 格式规范 | SKILL.md 存在, YAML frontmatter 格式正确 |
| 内容规范 | 无虚假宣传, 版本一致性 |
| 命名规范 | Skill ID 仅小写字母/数字/连字符 |
二、验证规则详解
2.1 SKILL.md Frontmatter 必需字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name |
string | ✅ | Skill 唯一标识，仅小写字母、数字、连字符 |
version |
string | ✅ | 语义化版本号，如 "1.0.0" |
description |
string | ✅ | 技能描述，建议 50-500 字符 |
tags |
array | ✅ | 标签数组，用于分类搜索 |
icon |
string | ✅ | emoji 图标 |
author |
string | ✅ | 作者名称 |
license |
string | ✅ | 许可证类型，推荐 "MIT" |
schema_version |
string | ✅ | 契约版本，当前为 "1.0" |
metadata |
object | ✅ | 元数据对象 |
2.2 文件规范
| 检查项 | 标准 | 严重度 |
|---|---|---|
| 文件数量 | < 200 个 | 🔴 P0 |
| 总大小 | < 10 MB | 🔴 P0 |
__pycache__/ 目录 |
不存在 | 🔴 P0 |
.pyc 文件 |
不存在 | 🔴 P0 |
.DS_Store 文件 |
不存在 | 🟡 P2 |
| SKILL.md | 必须存在 | 🔴 P0 |
2.3 虚假宣传检测
检查以下关键词是否在代码中有实际实现：
| 宣传关键词 | 检查方法 |
|---|---|
| AI剧本生成 | 检查 search.py 和 scripts/ 中是否有生成逻辑 |
| 内置工具 | 检查 tools/ 目录是否存在且有实现 |
| 特定API | 检查代码中是否有对应实现 |
2.4 版本一致性
| 检查文件 | 应与 SKILL.md version 一致 |
|---|---|
_meta.json |
version 字段 |
metadata.json |
version 字段 |
三、使用方法
3.1 验证单个 Skill
python3 validator.py --path /path/to/skill
# 示例
python3 validator.py --path /Users/lin/Documents/Agents配套/Skills/剧本类/找剧本
3.2 输出格式
{
"status": "pass|warning|fail",
"skill_name": "技能名称",
"version": "版本号",
"checks": {
"frontmatter": {"status": "pass|fail", "issues": []},
"file规范": {"status": "pass|fail", "issues": []},
"content规范": {"status": "pass|fail", "issues": []},
"naming规范": {"status": "pass|fail", "issues": []}
},
"summary": {
"total_checks": 20,
"passed": 18,
"warnings": 1,
"failed": 1
},
"recommendations": ["建议1", "建议2"]
}
3.3 返回码
| 返回码 | 含义 |
|---|---|
| 0 | 所有检查通过 |
| 1 | 存在警告（可发布） |
| 2 | 存在错误（不可发布） |
| 3 | 路径不存在或无法访问 |
四、错误代码
| 错误码 | 说明 | 对应检查项 |
|---|---|---|
FM001 |
SKILL.md 不存在 | frontmatter |
FM002 |
frontmatter 缺少必需字段 | frontmatter |
FM003 |
frontmatter 格式错误 | frontmatter |
FM004 |
version 格式无效 | frontmatter |
FM005 |
tags 不是数组或为空 | frontmatter |
FL001 |
文件数超限 (>200) | file规范 |
FL002 |
总大小超限 (>10MB) | file规范 |
FL003 |
存在 pycache | file规范 |
FL004 |
存在 .pyc 文件 | file规范 |
FL005 |
存在 .DS_Store | file规范 |
CN001 |
name 含非法字符 | naming规范 |
CN002 |
name 长度超限 (>50) | naming规范 |
VC001 |
_meta.json version 不一致 | version一致性 |
VC002 |
metadata.json version 不一致 | version一致性 |
FP001 |
疑似虚假宣传 | content规范 |
五、输出报告模板
# SkillHub 发布验证报告
## 基本信息
- **Skill 名称**: xxx
- **版本**: x.x.x
- **验证时间**: 2026-05-25 12:00:00
## 验证结果: ✅ 通过 / ⚠️ 警告 / ❌ 不通过
---
## 检查详情
### ✅ Frontmatter 规范
- name: ✅
- version: ✅
- description: ✅
- tags: ✅
- icon: ✅
- author: ✅
- license: ✅
- schema_version: ✅
- metadata: ✅
### ✅ 文件规范
- 文件数量: 17 ✅ (< 200)
- 总大小: 176KB ✅ (< 10MB)
- __pycache__: ✅ 不存在
- .pyc 文件: ✅ 不存在
- .DS_Store: ✅ 不存在
### ✅ 内容规范
- 版本一致性: ✅
- 无虚假宣传: ✅
---
## 总结
| 类型 | 数量 |
|------|------|
| 通过 | 20 |
| 警告 | 0 |
| 错误 | 0 |
**结论**: ✅ 该 Skill 符合 SkillHub 发布规范，可以上传。
六、技术实现
6.1 依赖
- Python 3.8+
- 标准库:
os,re,yaml,pathlib,json
6.2 目录结构
SkillHub/
├── SKILL.md # 主技能文档
├── metadata.json # 元数据
├── _meta.json # Agent 契约
├── validator.py # 验证脚本
└── references/
├── validation_rules.md # 验证规则详解
└── error_codes.md # 错误码说明
文档版本: 1.0.0
创建日期: 2026-05-25
核心能力: Frontmatter验证、文件规范检查、虚假宣传检测、版本一致性验证
