关于
根据 agentskills 规范验证 Claude Code 技能。在用户发现问题之前捕获结构、语义和命名问题
name: skill-check description: "根据 agentskills 规范验证 Claude Code 技能。在用户发现之前捕获结构、语义和命名问题。" category: development risk: safe source: https://github.com/olgasafonova/SkillCheck-Free date_added: "2026-03-11" author: olgasafonova tags: [validation, linter, agentskills, skill-authoring, code-quality] tools: [claude, cursor, windsurf, codex-cli] license: MIT allowed-tools: Read Glob compatibility: claude-code
SkillCheck
概述
根据 agentskills 规范 和 Anthropic 最佳实践验证 SKILL.md 文件。在单次只读扫描中捕获结构错误、语义矛盾、命名反模式和质量缺陷。
何时使用此技能
- 当用户说"check skill"、"skillcheck"或"validate SKILL.md"时使用
- 在将技能发布到市场之前进行审查时使用
- 在调试技能为何无法正确触发时使用
- 在为团队引入技能编写标准时使用
- 不要用于反冗余检测、安全扫描或 token 分析；这些请使用 SkillCheck Pro
工作原理
步骤 1：解析
读取目标 SKILL.md 文件并提取 YAML frontmatter。
步骤 2：验证
按顺序应用所有免费版检查：
| 类别 | 检查项 | 捕获内容 | |------|--------|----------| | 结构 (1.x) | 名称格式、描述 WHAT+WHEN、allowed-tools、类别、XML 注入 | 格式错误的 frontmatter、缺失字段 | | 正文 (2.x) | 行数、硬编码路径、过期日期、空节、废弃语法、MCP 工具限定 | 内容质量问题 | | 命名 (3.x) | 模糊术语、单词名称、动名词建议 | 可发现性差 | | 语义 (4.x) | 矛盾、歧义术语、缺少输出格式、空洞说教、触发器位置错误 | 逻辑不一致 | | 质量 (8.x) | 示例、错误处理、触发器、输出格式、前置条件、否定触发器 | 优势（正面模式） |
步骤 3：评分
计算总分（0-100）。扣分规则：严重 = -20，警告 = -5，建议 = -1。
步骤 4：报告
返回结构化结果：分数、等级（优秀/良好/需改进/差）、问题列表（含检查 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.
限制
- 只读：不修改任何文件
- 免费版仅涵盖结构、语义和命名检查
- 反冗余、安全、WCAG、token、企业和工作流检查需要 SkillCheck Pro
- 语义检查（矛盾检测、空洞说教）是启发式的，约有 5% 的误报率
- 不验证引用的文件或脚本；仅检查 SKILL.md 内容
- 单文件验证；不与同目录中的其他技能交叉检查
最佳实践
- 在将技能提交到任何市场之前运行 SkillCheck
- 修复所有严重和警告问题；建议是可选的
- 使用检查 ID（例如
1.2-desc-when）在技能正文中找到确切规则 - 修复后重新运行以确认分数提高
常见陷阱
-
问题： 由于建议过多导致分数偏低 解决方案： 建议最多扣 15 分。优先关注警告和严重问题。
-
问题： 代码块内的歧义术语出现误报 解决方案： SkillCheck 会跳过代码块和行内代码。如果仍然出现误报，请将术语用反引号包裹。
-
问题： 空洞说教检查标记了合理的指令 解决方案： 将通用建议（"记住测试很重要"）改写为具体指令（"提交前运行测试"）。