skill-check

SkillCheck

概述

根据 agentskills specification 和 Anthropic 最佳实践验证 SKILL.md 文件。通过一次只读检查，发现结构错误、语义矛盾、命名反模式和质量不足。

何时使用此技能

• 用户说“check skill”“skillcheck”或“validate SKILL.md”时使用
• 在将技能发布到市场前进行审核时使用
• 在排查技能无法正确触发的原因时使用
• 在帮助团队了解技能编写标准时使用
• 请勿用于检测低质内容、安全扫描或令牌分析；这些情况请使用 SkillCheck Pro

工作原理

步骤 1：解析

读取目标 SKILL.md 文件并提取 YAML 前置元数据。

步骤 2：验证

此文件总结了检查类别，但不包含完整的编号规则集或验证器。声称具体的检查 ID、数量或分数前，请先检查实际的上游规则或已安装的验证器。仅凭此文件，请按类别提供定性审核，并将无法执行的检查标记为未评估。

按顺序应用 Free 层级检查：

类别	检查项	检查内容
结构（1.x）	名称格式、描述中的 WHAT+WHEN、allowed-tools、类别、XML 注入	格式错误的前置元数据、缺少字段
正文（2.x）	行数、硬编码路径、过时日期、空章节、已弃用语法、MCP 工具限定	内容质量问题
命名（3.x）	含糊词语、单词名称、动名词建议	可发现性差
语义（4.x）	矛盾、含糊术语、缺少输出格式、空泛说教、触发条件错置	逻辑不一致
质量（8.x）	示例、错误处理、触发条件、输出格式、先决条件、负向触发条件	优点（积极模式）

步骤 3：评分

计算总分（0-100）。扣分规则：严重问题 = -20，警告 = -5，建议 = -1。

步骤 4：报告

返回结构化结果：分数、等级（Excellent/Good/Needs Work/Poor）、包含检查 ID、行号、说明和修复建议的问题列表。

示例

示例 1：验证技能

User: check my skill at ~/.claude/skills/weekly-report/SKILL.md

SkillCheck output:
## weekly-report Check Results [FREE]

Score: 85/100 (Good)

### Warnings (2)
  - 1.2-desc-when (line 3): Description missing WHEN clause
  - 4.5-desc-no-triggers (line 3): Description lacks triggering conditions

### Suggestions (1)
  - 3.4-gerund-naming (line 2): Skill name could use gerund form

### Passed Checks: 28

示例 2：技能通过所有检查

User: skillcheck ~/.claude/skills/processing-pdfs/SKILL.md

Score: 100/100 (Excellent)
All 31 checks passed. No issues found.

限制

• 只读：不会修改任何文件
• Free 层级仅涵盖结构、语义和命名检查
• 检测低质内容、安全、WCAG、令牌、企业和工作流需要使用 SkillCheck Pro
• 语义检查基于启发式规则；此目录副本不包含任何评估证据来支持量化的误报率。
• 不会验证引用的文件或脚本；仅检查 SKILL.md 内容
• 仅验证单个文件；不会与同一目录中的其他技能进行交叉检查

最佳实践

• 向任何市场提交技能前，先运行 SkillCheck
• 修复所有严重问题和警告；建议可酌情处理
• 使用检查 ID（例如 1.2-desc-when）在技能正文中查找确切规则
• 修复后重新运行，以确认分数有所提高

常见问题

• **问题：**由于有很多建议，分数看起来很低
  **解决方案：**建议最多总计扣 15 分。请先处理警告和严重问题。

• **问题：**代码块中的含糊术语被误报
  **解决方案：**SkillCheck 会跳过代码块和行内代码。如果仍出现误报，请将该术语用反引号括起来。

• **问题：**空泛说教检查将合理的指令标记为问题
  **解决方案：**将泛泛的建议（“请记住，测试很重要”）改写为具体指令（“提交前运行测试”）。