Skill Review#

审查 Agent Skills 的规范性、完整性和代码质量。

使用场景#

• 安装 skills 前进行质量检查
• 发布 skills 前的合规验证
• 代码审查和最佳实践检查
• 目录结构和文件引用验证

审查项目#

1. SKILL.md 格式审查#

• YAML frontmatter 存在且格式正确
• name 字段符合命名规范（小写字母、数字、连字符，1-64字符）
• description 字段存在且长度在 1-1024 字符之间
• license 字段（如有）格式正确
• compatibility 字段（如有）长度在 500 字符以内
• metadata 字段（如有）为键值对格式
• allowed-tools 字段（如有）格式正确

2. 目录结构审查#

• 技能目录名与 name 字段一致
• SKILL.md 文件存在于根目录
• scripts/ 目录（如有）结构合理
• references/ 目录（如有）结构合理
• assets/ 目录（如有）结构合理
• 无深层嵌套（建议不超过 2 层）

3. 脚本代码审查#

• 脚本文件有执行权限（如需要）
• 脚本包含清晰的错误处理
• 脚本有适当的注释说明
• 脚本依赖关系明确
• 无硬编码的敏感信息
• 代码风格一致

4. 文件引用审查#

• 所有引用的文件存在
• 相对路径正确（从 skill 根目录开始）
• 无循环引用
• 引用的文件大小合理

使用方法#

基本用法#

bash

# 审查单个 skill
bash scripts/review.sh /path/to/skill-name

# 详细审查（包含代码分析）
bash scripts/review.sh /path/to/skill-name --verbose

# 生成 JSON 格式报告
bash scripts/review.sh /path/to/skill-name --json

Python API#

python

from scripts.review_skill import SkillReviewer

reviewer = SkillReviewer()
result = reviewer.review("/path/to/skill-name")
print(result.to_markdown())

审查报告格式#

Markdown 报告#

markdown

# Skill 审查报告: skill-name

## 概要
- 总分: 85/100
- 状态: ✅ 通过 / ❌ 未通过
- 审查时间: 2024-01-01 12:00:00

## 详细结果

### SKILL.md 格式
- 状态: ✅ 通过
- 得分: 25/25
- 问题: 无

### 目录结构
- 状态: ✅ 通过
- 得分: 20/20
- 问题: 无

### 脚本代码
- 状态: ⚠️ 警告
- 得分: 30/35
- 问题:
  - [WARN] 脚本缺少错误处理: scripts/process.py:15
  - [WARN] 建议添加注释: scripts/helper.sh:8

### 文件引用
- 状态: ❌ 失败
- 得分: 10/20
- 问题:
  - [ERROR] 引用的文件不存在: references/MISSING.md
  - [WARN] 文件过大: assets/large-file.bin (5.2MB)

JSON 报告#

json

{
  "skill_name": "skill-name",
  "overall_score": 85,
  "status": "passed",
  "timestamp": "2024-01-01T12:00:00Z",
  "categories": {
    "skill_md": {
      "score": 25,
      "max_score": 25,
      "status": "passed",
      "issues": []
    },
    "directory_structure": {
      "score": 20,
      "max_score": 20,
      "status": "passed",
      "issues": []
    },
    "script_code": {
      "score": 30,
      "max_score": 35,
      "status": "warning",
      "issues": [
        {
          "level": "warn",
          "message": "脚本缺少错误处理",
          "file": "scripts/process.py",
          "line": 15
        }
      ]
    },
    "file_references": {
      "score": 10,
      "max_score": 20,
      "status": "failed",
      "issues": [
        {
          "level": "error",
          "message": "引用的文件不存在",
          "file": "references/MISSING.md"
        }
      ]
    }
  }
}

评分标准#

类别满分通过线说明SKILL.md 格式2520frontmatter 和正文格式目录结构2015目录组织和命名脚本代码3525代码质量和安全性文件引用2015引用完整性和正确性总分10075综合评分

常见问题#

SKILL.md 问题#

问题: name 字段包含大写字母

yaml

# ❌ 错误
name: PDF-Processing

# ✅ 正确
name: pdf-processing

问题: description 过短

yaml

# ❌ 错误
description: Helps with PDFs.

# ✅ 正确
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.

目录结构问题#

问题: 目录名与 name 字段不匹配

text

# ❌ 错误
my-skill/
  SKILL.md (name: different-name)

# ✅ 正确
my-skill/
  SKILL.md (name: my-skill)

脚本问题#

问题: 缺少错误处理

bash

# ❌ 错误
rm -rf $TARGET_DIR

# ✅ 正确
if [ -d "$TARGET_DIR" ]; then
  rm -rf "$TARGET_DIR" || { echo "无法删除目录"; exit 1; }
fi

文件引用问题#

问题: 引用的文件不存在

markdown

# ❌ 错误
See [reference](references/NONEXISTENT.md)

# ✅ 正确
See [reference](references/EXISTING.md)

参考文档#

• Agent Skills 规范
• 审查规则详解
• 常见问题解答

最佳实践#

1. 在安装 skill 前运行审查: 确保 skill 质量符合预期
2. 在 CI/CD 中集成: 自动化 skill 发布流程
3. 定期更新审查规则: 跟随 Agent Skills 规范更新
4. 结合人工审查: 自动化审查不能替代人工判断