lxztry Skill Check - Skill 工程化平台
完整的 Skill 工程化质量管理体系
🧭 平台概览
Skill Check 不再只是"质检员"，而是覆盖 Skill 创建 → 开发 → 检查 → 测试 → 发布 全生命周期的工程化平台。
| 阶段 | 工具 | 说明 |
|---|---|---|
| 创建 | create.py |
从模板快速创建 Skill |
| 开发 | 实时检查 | 边写边检，提前发现问题 |
| 检查 | skill_check.py |
规范合规性检查 |
| 测试 | test_runner.py |
功能正确性验证 |
| 分析 | deps.py |
依赖关系图谱 |
| 优化 | profile.py |
性能与复杂度分析 |
| 迁移 | migrate.py |
版本升级迁移 |
| 发布 | ClawHub | 发布到市场 |
🚀 快速开始
创建新 Skill
# 基本模板
python scripts/create.py my-skill
# API集成模板
python scripts/create.py my-api-skill --template api-integration
# 查看所有模板
python scripts/create.py --list-templates
检查现有 Skill
# 单个检查
python scripts/skill_check.py ./my-skill
# 批量扫描
python scripts/skill_check.py ./skills --scan --concurrent
📦 创建向导 (create.py)
从模板快速创建符合规范的 Skill。
可用模板
| 模板 | 适用场景 |
|---|---|
basic |
最小化 Skill 结构 |
api-integration |
API 调用类 Skill |
web-automation |
浏览器自动化类 |
file-processing |
文件处理类 |
使用示例
# 创建基本 Skill
python scripts/create.py pdf-extractor
# 创建 API 集成 Skill
python scripts/create.py github-api --template api-integration
# 在指定目录创建
python scripts/create.py my-skill --output ~/my-skills
# 覆盖已存在的 Skill
python scripts/create.py my-skill --force
模板包含
- ✅
SKILL.md骨架 - ✅
scripts/示例代码 - ✅
references/目录 - ✅ 规范化的目录结构
🔍 规范检查 (skill_check.py)
检查项目
| 检查项 | 说明 | 级别 |
|---|---|---|
| 目录结构 | SKILL.md 存在、目录规范 | ERROR |
| Frontmatter | 必选字段、禁止字段 | ERROR |
| 命名规范 | hyphen-case、长度限制 | ERROR |
| 描述质量 | 长度、触发词、禁止 HTML | WARN |
| 内容质量 | 行数限制、token 预算 | WARN |
| 资源完整性 | shebang、引用路径 | WARN |
| 渐进式披露 | references/ 使用建议 | INFO |
使用示例
# 基本检查
python scripts/skill_check.py ./my-skill
# 详细输出
python scripts/skill_check.py ./my-skill --verbose
# 自动修复
python scripts/skill_check.py ./my-skill --fix
# JSON 输出
python scripts/skill_check.py ./my-skill --json
# 批量扫描
python scripts/skill_check.py ./skills --scan --concurrent
输出示例
══════════════════════════════════════════════════
SKILL CHECK REPORT
══════════════════════════════════════════════════
Skill: example-skill
Status: ❌ FAILED
──────────────────────────────────────────────────
ISSUES:
❌ [ERROR] Frontmatter Missing 'description' field
⚠️ [WARN] Description too long (1050 > 1024 chars)
Score: 65/100 | Grade: C
══════════════════════════════════════════════════
🔗 依赖分析 (deps.py)
分析 Skill 之间的依赖关系，检测循环依赖和孤岛 Skill。
使用示例
# 分析依赖
python scripts/deps.py ./skills
# JSON 输出
python scripts/deps.py ./skills --json
# 生成 Graphviz DOT
python scripts/deps.py ./skills --dot > deps.dot
输出内容
- 📊 统计信息：Skill 数量、引用数量
- 🔗 依赖关系列表
- ⚠️ 循环依赖检测
- 📌 孤岛 Skill（无任何依赖）
📊 性能分析 (profile.py)
分析 Skill 的复杂度和性能指标。
使用示例
# 分析单个 Skill
python scripts/profile.py ./my-skill
# 批量分析
python scripts/profile.py ./skills --scan
# JSON 输出
python scripts/profile.py ./my-skill --json -o profile.json
分析指标
| 指标 | 说明 |
|---|---|
| 复杂度评分 | 0-100 分，越高越好 |
| 复杂度等级 | A/B/C/D |
| 预估加载时间 | 基于 token 数量的估算 |
| 文件统计 | 总文件数、行数、大小 |
| SKILL.md 分析 | 行数、字符数、token 估算 |
优化建议
- SKILL.md 过大（>5000 tokens）→ 移至 references/
- 单个引用文件过大（>200 行）→ 拆分
- 缺少渐进式结构 → 添加 references/
- 大资源文件（>5MB）→ 压缩或外部托管
🔄 版本迁移 (migrate.py)
在规范版本之间迁移 Skill。
支持的迁移路径
| 源版本 | 目标版本 | 说明 |
|---|---|---|
| v1 | v2 | 添加 compatibility、检查 name 格式 |
使用示例
# 预览迁移（dry-run）
python scripts/migrate.py ./my-skill --from v1 --to v2
# 应用迁移
python scripts/migrate.py ./my-skill --from v1 --to v2 --apply
# 批量迁移
python scripts/migrate.py ./skills --from v1 --to v2 --scan --apply
v1 → v2 迁移规则
- 添加默认
compatibility: ['Python 3.8+'] - 修复 name 格式（lowercase、hyphen-case）
- 移除 forbidden 字段
- 验证 description 长度
- 清理 HTML 标签
🧪 测试框架 (test_runner.py)
运行时验证 Skill 的功能正确性。
使用示例
# 测试单个 Skill
python scripts/test_runner.py ./my-skill
# 测试所有 Skills
python scripts/test_runner.py ./skills --scan
# JSON 输出
python scripts/test_runner.py ./my-skill --json
测试项目
| 测试 | 说明 |
|---|---|
| structure | 目录结构检查 |
| frontmatter | 必选字段检查 |
| naming | 命名规范检查 |
| description | 描述质量检查 |
| trigger_words | 触发词检查 |
| content_length | 内容长度检查 |
| no_html | HTML 标签检查 |
| scripts_shebang | 脚本 shebang 检查 |
| references_naming | 引用文件命名检查 |
🔌 VS Code 插件
在编辑器中集成 Skill 检查和创建功能。
安装
cd vscode-extension
npm install
npm run compile
npx vsce package
code --install-extension skill-check-1.0.0.vsix
命令
| 命令 | 说明 |
|---|---|
Skill Check: 检查当前 Skill |
检查光标所在的 Skill |
Skill Check: 检查所有 Skills |
扫描工作区检查所有 Skills |
Skill Check: 创建新 Skill |
从模板创建新 Skill |
📁 项目结构
skill-check/
├── scripts/
│ ├── skill_check.py # 规范检查
│ ├── create.py # 创建向导
│ ├── deps.py # 依赖分析
│ ├── profile.py # 性能分析
│ ├── migrate.py # 版本迁移
│ └── diagnose.py # 诊断报告
├── skill_check/
│ ├── checker.py # 检查核心
│ └── config.py # 配置管理
├── templates/ # Skill 模板
│ ├── basic/
│ ├── api-integration/
│ ├── web-automation/
│ └── file-processing/
├── references/ # 规范文档
│ ├── rules.md
│ └── rules_zh.md # 中文规则
└── tests/ # 测试套件
🎓 成熟度等级
| 等级 | 名称 | 要求 |
|---|---|---|
| L1 | 基础合规 | 目录结构 + frontmatter 正确 |
| L2 | 命名规范 | name + description 符合标准 |
| L3 | 内容质量 | 无冗余、触发词完整 |
| L4 | 渐进式设计 | 正确使用 references/ |
| L5 | 工程化 | 有测试、有文档、有版本管理 |
配置
.skill-check.md
在项目根目录创建 .skill-check.md 来自定义规则：
allowed_frontmatter_fields:
- name
- description
- license
- compatibility
- metadata
- allowed-tools
forbidden_files:
- README.md
- CHANGELOG.md
rules:
max_name_length: 64
max_description_length: 1024
max_body_tokens: 5000
依赖
- Python 3.8+
- PyYAML
Skill Check - 让 Skill 工程化成为可能