skillcheck

skillcheck

SKILL.md は、存在しないファイルを参照していることがあります。スキルが実行されるまで、誰も気づきません。

スキルは、名前、説明、そしてエージェントが読み込んだり実行したりするよう指示されているガイド、スクリプト、参照ファイルへのリンクを記した本文を含む、YAML フロントマター付きの Markdown ドキュメントです。リンク先や参照ファイルが見つからない場合、その失敗はタスクの途中で、他の人のワークフローの中で発生します。skillcheck は、そうなる前に SKILL.md を検証します。フロントマターの形式、名前がディレクトリ名と一致しているか、本文内の相対リンクや参照ファイルがすべてディスク上に存在するかを確認します。

できること

skillcheck は、SKILL.md ファイルまたは SKILL.md を含むディレクトリを受け取り、検出結果ごとにルール、重大度、ファイル、行番号を示す判定を 1 つ返します。決定論的に動作し、オフラインで実行でき、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 です。出力パイプを早期に閉じる読み取り側があると、プロセスは 0 ではなく 141 で終了します。

出力例：

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 ファイル、または SKILL.md を含むディレクトリ）を受け取り、CLI と同じ判定、件数、検出結果を含む完全なレポートを JSON で返します。

チェック項目

ルール	重大度	意味
NO-SKILL-FILE	高	指定されたパスに SKILL.md が見つかりません。対象が見つからない場合に検出されるのは、この項目のみです。
FRONTMATTER-MISSING	高	ファイルが --- の行で始まっていないか、閉じる --- の行がありません。
NAME-MISSING	高	フロントマターに name キーがないか、name の値が空です。
DESCRIPTION-MISSING	高	フロントマターに description キーがないか、description の値が空です。
DESCRIPTION-SHORT	低	description はありますが、20 文字未満です。
NAME-DIR-MISMATCH	中	フロントマターの name が、格納先ディレクトリの名前と一致しません。
NAME-DIR-SKIPPED	情報	対象がカレントディレクトリのように、スキル名を示さない一般的な名前のディレクトリであるため、name とディレクトリ名の一致チェックはスキップされました。
LINK-DEAD	中	相対 Markdown リンクまたは画像参照のリンク先が、スキルディレクトリを基準とした場所に存在しません。検出結果には行番号が含まれます。
REF-MISSING	中	ファイルらしい形式のバッククォート付き相対パス（スラッシュを含むか、既知のファイル拡張子で終わるもの）が、スキルディレクトリを基準とした場所に存在しません。
NO-HEADINGS	低	本文に # または ## の見出しがありません。

リンク内の絶対 URL（https:// で始まるリンクなど）はスキップされます。レポートでは externalLinks に数えられ、検出結果にはなりません。アンカーのみのリンクもスキップされます。フェンス付きコードブロック内のリンクや参照はチェックされません。

レポートの件数は findings、high、medium、low、info、linksChecked、refsChecked、externalLinks です。

判定ルール

• VALID：高または中の検出結果がありません。低および情報の検出結果は含まれる場合があります。終了コードは 0 です。
• INVALID：高または中の検出結果が 1 つ以上あります。終了コードは 1 です。

制限事項を明確に示します

• フロントマターパーサーは、意図的に YAML の単純なサブセットのみを扱います。--- 行で始まり、閉じる --- 行があり、その間に単純な key: value 行が並ぶファイルを読み取ります。複数行の値、折りたたみ形式またはブロック形式のスカラー、ネストされたマップ、リスト、アンカー、値の中のコメントには対応していません。こうした機能が必要な SKILL.md は、より豊かな形式で実際には値を持っていても、キーが欠けていると報告される場合があります。
• 単純な key: value 形式のフロントマターのみを認識するため、name と description は引用符の有無にかかわらず、1 行のプレーンな値である必要があります。
• リンクチェックは文字どおりに行われます。フラグメントやクエリ文字列を除いた相対リンクのターゲットは、スキルディレクトリを基準に、記述どおりのパスで存在している必要があります。リダイレクト、生成ファイル、ビルド手順によって作成されるリンクは予測されません。
• バッククォートで囲まれた参照は、ヒューリスティックに判定されます。トークンがファイル参照として扱われるのは、スペースを含まず、絶対パスでもホームディレクトリのパスでもなく、スラッシュを含むか、既知のファイル拡張子で終わる場合のみです。ツール名、コマンド、ドットを含む識別子はファイルとして扱われません。
• スキルのテキストの意味的な品質は対象外です。skillcheck は、手順が正しいか、明確か、安全か、有用か、リンク先の内容がリンクテキストの主張どおりか、参照されたスクリプトがスキルの説明どおりに動作するかを判断しません。存在と形式のみをチェックします。
• name と description 以外のフロントマターの値は検証されず、追加のキーは無視されます。