SkillLint - AI技能可用性诊断工具

概述

SkillLint诊断一个或多个Skill能否被Agent正确、稳定地调用。通过自动推断Skill性格并适配审查标准，确保Skill在实际使用中可用。

---

输入（Input Schema）

必填参数

参数	类型	说明
skill_paths	array	要诊断的Skill文件路径列表，支持.yaml和.json

可选参数

参数	类型	默认值	说明
check_level	string	"basic"	检查级别：basic/standard/deep
output_format	string	"markdown"	输出格式：json/markdown/report
dry_run	boolean	false	模拟调用测试
fail_below	integer	0	低于此分数返回fail，0=不启用

---

Skill性格推断（核心创新）

自动推断Skill的4种性格，按性格适配审查标准：

性格	icon	input_style	output_style	说明
宽宽型	🍜	loose	loose	输入宽松，输出宽松
宽严型	👔	loose	strict	输入宽松，输出严格
严宽型	🏥	strict	loose	输入严格，输出宽松
严严型	🏦	strict	strict	输入严格，输出严格

推断依据

• 输入风格：参数是否有默认值、是否有示例、类型是否明确
• 输出风格：是否有status字段、错误是否明确、输出是否结构化

---

审查维度（7维评分）

维度	说明
身份清晰度	name/description/version/emoji是否完整
参数可猜测性	参数名是否清晰、是否有示例、类型是否明确
输出可预测性	输出结构是否固定、status字段是否存在
错误可恢复性	错误是否有明确处理方式、是否有suggestion
副作用透明度	副作用是否声明、风险等级是否标注
示例完整性	examples是否包含输入输出、是否覆盖主要场景
组合兼容性	多Skill协作是否兼容（仅deep级别）

---

输出（Output Schema）

output:
  personality:
    input_style: "loose" | "strict"
    output_style: "loose" | "strict"
    icon: "🍜" | "👔" | "🏥" | "🏦"
    label: string
    confidence: "high" | "medium" | "low"
    reasons: array
  score:
    total: int          # 0-100
    grade: "S" | "A" | "B" | "C" | "D" | "F"
    dimensions:
      identity: int
      param_guessable: int
      output_predictable: int
      error_recoverable: int
      side_effect_transparent: int
      example_complete: int
      combo_compatible: int  # 仅deep
  issues:
    - severity: "error" | "warning" | "info"
      dimension: string
      message: string
      suggestion: string
  dry_run_result:        # 仅dry_run=true时
    attempted_input: object
    matches_example: boolean
    confidence: string
    notes: string
  summary: string
  status: "pass" | "warning" | "fail"

---

错误处理（Error Schema）

错误类型	可恢复	提示
PATH_NOT_FOUND	✅	Skill文件路径不存在，检查路径拼写
PARSE_ERROR	❌	文件无法解析，确认文件为有效YAML或JSON
EMPTY_INPUT	✅	未提供任何路径，至少提供一个路径

---

副作用

类型	风险	说明
file_read	low	读取Skill文件，不修改任何文件

---

使用示例

示例1：标准检查

input:
  skill_paths: ["./skills/web-search.yaml"]
  check_level: "standard"
output:
  personality:
    input_style: "loose"
    output_style: "loose"
    icon: "🍜"
    label: "宽进宽出型"
    confidence: "high"
  score:
    total: 72
    grade: "B"
  summary: "🍜 宽进宽出型，整体可用，建议补充错误恢复建议"
  status: "warning"

示例2：带模拟调用的深度检查

input:
  skill_paths: ["./skills/csv-to-json.yaml"]
  check_level: "deep"
  dry_run: true
  fail_below: 60
output:
  personality:
    input_style: "loose"
    output_style: "strict"
    icon: "👔"
    label: "宽进严出型"
    confidence: "high"
  score:
    total: 91
    grade: "S"
  dry_run_result:
    attempted_input: { csv_text: "name,age\n张三,25" }
    matches_example: true
    confidence: "high"
    notes: "参数定义清晰，能准确构造调用"
  summary: "👔 宽进严出型，质量优秀，模拟调用成功"
  status: "pass"

示例3：模拟调用失败

input:
  skill_paths: ["./skills/bad-skill.yaml"]
  dry_run: true
output:
  personality:
    input_style: "strict"
    output_style: "strict"
    icon: "🏦"
    label: "严进严出型"
    confidence: "medium"
  score:
    total: 35
    grade: "F"
  dry_run_result:
    attempted_input: null
    matches_example: false
    confidence: "low"
    notes: "无法确定data参数应该传什么内容，参数名模糊且无描述无示例"
  summary: "🏦 严进严出型，质量不合格，模拟调用失败，Agent大概率无法正确调用"
  status: "fail"

---

CI/CD集成

# 设置质量门槛，低于60分返回fail
skilllint ./skills/*.yaml --fail-below 60

# 输出JSON格式，便于解析
skilllint ./skills/*.yaml --output-format json

---

与现有方案对比

维度	现有skill-schema-auditor	SkillLint
性格推断	❌	✅ 自动推断4种
模拟调用	❌	✅ dry_run测试
评分维度	5维	7维
质量门槛	❌	✅ fail_below
CI/CD	❌	✅ 支持

---

version: 2.1.0 | 用于Skill上线前质量把关 + 批量体检