skillcheck

skillcheck

SKILL.md 可以指向不存在的文件。直到技能运行时，才会有人发现。

技能是带有 YAML frontmatter 的 Markdown 文档：包含名称、描述，以及正文；正文会链接到 Agent 被要求阅读或运行的指南、脚本和参考文件。如果链接或引用的文件缺失，问题就会在任务中途、在别人的工作流里暴露出来。skillcheck 会在此之前验证 SKILL.md：检查 frontmatter 格式、名称是否与目录匹配，以及正文中的每个相对链接和引用文件是否确实存在于磁盘上。

功能

skillcheck 接受 SKILL.md 文件或包含该文件的目录，并返回一份单一判定，其中每项发现都附有证据：规则、严重程度、文件和行号。它的行为是确定性的，可离线运行，只使用 Node 标准库，并且绝不会执行正在检查的技能中的任何内容。

安装

npx @reneturcios/skillcheck check

也可以全局安装：

npm install -g @reneturcios/skillcheck
skillcheck check path/to/skill

CLI

# Check the current directory (expects ./SKILL.md)
skillcheck check

# Check a skill directory
skillcheck check path/to/skill

# Check a SKILL.md file directly
skillcheck check path/to/skill/SKILL.md

# Machine readable output
skillcheck check path/to/skill --json

# Run as an MCP server (stdio)
skillcheck mcp

# Print the version
skillcheck --version

退出码：判定为 VALID 时返回 0，INVALID 时返回 1，用法错误时返回 2。如果读取输出管道的一方提前关闭管道，进程会以 141 退出，绝不会返回 0。

输出示例：

skillcheck check path/to/skill: INVALID
  findings: 2 (high: 0, medium: 2, low: 0, info: 0), links checked: 1, refs checked: 1, external links skipped: 0
  [MEDIUM] SKILL.md:8 LINK-DEAD Markdown link target "missing-guide.md" does not exist relative to the skill directory.
  [MEDIUM] SKILL.md:10 REF-MISSING Referenced file "scripts/missing-helper.py" does not exist relative to the skill directory.
INVALID: 2 finding(s) (0 high, 2 medium, 0 low, 0 info).

MCP 服务

添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "skillcheck": {
      "command": "npx",
      "args": ["-y", "@reneturcios/skillcheck", "mcp"]
    }
  }
}

工具：check_skill 接受 path 参数（SKILL.md 文件或包含该文件的目录），并以 JSON 格式返回完整报告，其中判定、计数和发现与 CLI 相同。

检查内容

规则	严重程度	含义
NO-SKILL-FILE	高	在目标路径下未找到 SKILL.md。目标不存在时，这是唯一的发现。
FRONTMATTER-MISSING	高	文件未以一行 --- 开始，并且没有以一行 --- 结束。
NAME-MISSING	高	frontmatter 中没有 name 键，或 name 值为空。
DESCRIPTION-MISSING	高	frontmatter 中没有 description 键，或 description 值为空。
DESCRIPTION-SHORT	低	description 存在，但长度少于 20 个字符。
NAME-DIR-MISMATCH	中	frontmatter 中的名称与所在目录名称不匹配。
NAME-DIR-SKIPPED	信息	由于目标目录名称是通用名称、不包含技能名称，因此跳过名称与目录匹配检查；例如，目标是当前目录时。
LINK-DEAD	中	相对于技能目录解析的 Markdown 相对链接或图片引用不存在。该发现包含行号。
REF-MISSING	中	反引号括起的相对路径看起来像文件（包含斜杠，或以已知文件扩展名结尾），但相对于技能目录不存在。
NO-HEADINGS	低	正文中没有 # 或 ## 标题。

链接中的绝对 URL（例如 https:// 链接）会被跳过：它们会计入报告的 externalLinks，且不会产生发现。仅含锚点的链接也会跳过。围栏代码块中的链接和引用不会检查。

报告计数包括 findings、high、medium、low、info、linksChecked、refsChecked 和 externalLinks。

判定规则

• VALID：没有高或中严重程度的发现。可以存在低严重程度和信息类发现。退出码为 0。
• INVALID：至少存在一项高或中严重程度的发现。退出码为 1。

明确说明限制

• 前置元数据解析器有意只支持 YAML 的一个简单子集。它会读取以一行 --- 开头、以一行 --- 结束，且中间由简单的 键: 值 行组成的文件。它不支持多行值、折叠或块标量、嵌套映射、列表、锚点，也不支持值中的注释。需要这些功能的 SKILL.md 可能会被报告为缺少某些键，尽管它实际上可能以更丰富的形式包含这些键。
• 只支持简单的 键: 值 前置元数据，因此 name 和 description 必须是带引号或不带引号的纯单行值。
• 链接检查采用字面匹配。相对链接目标去除片段或查询字符串后，必须按原样存在于相对于技能目录的位置。不会预测重定向、生成的文件，以及构建步骤会创建的链接。
• 反引号括起的引用只是一种启发式判断。只有当令牌不含空格、不是绝对路径或主目录路径，并且包含斜杠或以已知文件扩展名结尾时，才会被视为文件引用。工具名称、命令和带点号的标识符不会被视为文件。
• 技能文本的语义质量不在检查范围内。skillcheck 不会判断说明是否正确、清晰、安全或有用，不会判断链接内容是否与链接文本所声称的内容相符，也不会判断被引用的脚本是否执行了技能所述的操作。它只检查内容是否存在及其形式。
• 不会验证 name 和 description 之外的前置元数据值，并会忽略额外的键。