Claude Code Skills: 最初のSKILL.mdを書く

公式Claude Code skillsドキュメントによれば、skillはYAMLフロントマターとマークダウン命令を含むSKILL.mdファイルを持つフォルダです。Claudeは起動時に名前と説明を読み込み、スキルが必要になったときだけ本体全体を取得します。このプログレッシブディスクロージャー設計はコンテキストを無駄なく保ちます。このページで提供するもの：ゼロから書いた内部リンク監査用のオリジナルスキル、トリガーテストケース、結果ルーブリック、そして反復可能にするためのパッケージステップです。

動作するSKILL.mdの例

完成した成果物から始めましょう。これであなたが目指す方向が見えます。以下はサイト全体の内部リンクを監査するスキルです。コピーしてインストールしてから、このポストの残りを読んで、すべての判断を理解してください。

description: >

Audits internal links in a project's HTML or Markdown output.

Use when the user asks to check broken links, find dead anchors,

audit site links, or review internal navigation before a deploy.

## Internal Link Audit

Run a link audit against the built output or source files.

### Steps

1. Collect all internal links (href or markdown link targets starting

with / or a relative path).

2. Resolve each link against the project root.

3. Check whether the resolved target file or anchor exists on disk.

4. Report broken links grouped by source file. For each broken link,

show: source file, link text, href, and the reason it fails

(missing file, missing anchor, or redirect loop if detectable).

5. List passing links only in a summary count, not individually.

6. If zero broken links are found, say so explicitly.

### Output format

- Broken links: grouped table per source file.

- Summary line: "X of Y internal links are broken."

- If scripts/ contains check-links.sh, run it first and append

Claude's analysis below the script output.

これは実在する、機能するスキルです。~/.claude/skills/internal-link-audit/SKILL.mdに保存すれば、すべてのプロジェクトで即座に利用可能になります。

注意すべき点：公式ドキュメントは、カスタムコマンドがスキルに統合されたことを確認しています。両者は/nameで呼び出せます。つまり/internal-link-auditはダイレクトコマンドとして機能し、Claudeは自然言語リクエストからも自動的にマッチします。これらは別々のメカニズムではありません。

狭いタスクを選んでDescriptionを書く

descriptionフィールドはドキュメントではありません。これはトリガーです。その中のすべての単語は、スキルを正しい場面にマッチさせるのに役立つか、マッチングを悪化させるノイズを追加するかのいずれかです。

Hidekazu Konishiのガイドは明確に述べています：曖昧な説明がスキルが発火しない最も一般的な理由です。三人称で書きます。主要なユースケースで始めます。次に、ユーザーが実際に入力するフレーズをリストアップします。マッチングはあなたの内部アイデアではなく、これらのフレーズに対して行われるからです。

悪い説明：ウェブプロジェクトのリンクと関連事項を支援します。

より良い説明：プロジェクトのHTMLまたはMarkdownの出力における内部リンクを監査します。

Use when the user asks to check broken links, find dead anchors,

audit site links, or review internal navigation before a deploy.

2番目のバージョンではアクション（「内部リンクを監査」）を前置き、ファイルタイプを名前付け、その後4つの具体的なトリガーフレーズをUse whenの節に記載しています。各フレーズは開発者が実際に入力することでしょう。

狭いことの方が優れています

「汎用リンクチェッカー」を構築する誘惑に抵抗します。1つのことを上手にやるスキルは信頼性高くトリガーされます。リンク確認、リダイレクト検証、ページスピード報告を約束するスキルは信頼性低く発火し、出力が一貫しません。最小限の有用なスライスを選びます。残りの部分には常に2番目のスキルを書くことができます。

内部リンク監査の場合、狭めの判断は：

外部ではなく内部リンクのみ（異なるツール、異なる失敗モード）
HTTPステータスではなく、ファイル存在とアンカー存在をチェック
フラットリストではなく、ソースファイルでグループ化された壊れたリンクを報告

すべての絞り込み決定により、トリガーフレーズはより具体的になり、出力フォーマットの検証がより容易になります。

コントロール呼び出しとサポートファイル

Claude が説明にマッチすると、スキルは自動的にロードされます。また、明示的な /skill-name コマンドにも応答します。公式ドキュメントによると、Claude は起動時に 4 つの場所をスキャンします：パーソナル（~/.claude/skills/）、プロジェクト（.claude/skills/）、プラグイン、エンタープライズです。エンタープライズはパーソナルをオーバーライドし、パーソナルはプロジェクトをオーバーライドします。ローカル個別化が競合する可能性のあるチームにスキルを展開する場合、この階層構造を理解することが重要です。

呼び出しについては、2 つのパスがあります：

自動：Claude があなたのリクエストを読み、ロードされた説明にマッチさせ、スキルを起動します。スラッシュコマンドは不要です。
明示的：/internal-link-audit と入力します。Claude は完全な SKILL.md 本体をロードして実行します。自動マッチがトリガーされない場合のテストと状況で役立ちます。

両方のパスは同じ指示を実行します。区別は「手動対自動」ではなく、スキルが適用されることを決定するために Claude が使用するシグナルについてです。

サポートファイル

スキルフォルダは SKILL.md 以上のものを保持できます：

scripts/：スキル本体が参照する実行可能コード（Bash、Python）。internal-link-audit スキルは scripts/check-links.sh が存在する場合はそれを参照するため、指示を変更することなく後で実際のリンク確認スクリプトに置き換えることができます。
references/：詳細なドキュメント。Claude は要求時にロードします。毎回の呼び出しでロードされません。ダース単位のエッジケースをインラインで処理することで指示が長くなるのを避けたい場合に適しています。
assets/：テンプレートと出力フォーマット。

最初のスキルとしては、SKILL.md だけで十分です。実際に実行したいコマンドがある場合は scripts/ を追加してください。グローバル指示ファイルに属さない指示が長くなり始めたら references/ を追加してください。

すでにプロジェクト全体の指示用に CLAUDE.md を管理している場合、スキルはそれに沿って配置されます。これは置き換えではありません。エージェンシー向け Claude.md ポストではそのファイルを個別に構造化する方法について説明します。スキルはグローバル指示ファイルに属さない、狭くて再利用可能なタスクを処理します。

ポジティブおよびネガティブトリガーテストを実行する

執筆は簡単な部分です。テストは、ほとんどの人が早すぎる段階で止まるところです。Towards Data Science ガイド（本番対応の Claude Code スキル）によると、ここでの「テスト」はリアルなプロンプトをスキルにぶつけ、動作が正しいかどうかを確認することを意味します。ソフトウェアの意味でのユニットテストではありません。

2 つのテストケースが必要です：ポジティブ（トリガーされるべき）とネガティブ（トリガーされるべきでない）。

internal-link-audit のポジティブトリガーケース

これらのプロンプトはすべてスキルを自動的に呼び出すはずです：

「デプロイ前に壊れた内部リンクを確認してください。」
「マークダウン出力のデッドアンカーを見つけてください。」
「ビルドフォルダ内のサイトリンクを監査してください。」
サイトにリンク切れはありますか？
プロジェクト全体の内部ナビゲーションをレビューしてください。

ネガティブトリガーケース

これらのプロンプトはスキルをトリガーしてはいけません。トリガーした場合、過度なトリガー問題があります。

「READMEの外部リンクがまだ機能しているか確認してください。」（外部リンク、異なるスキル領域）
「sitemap.xmlを検証してください。」（まったく異なるタスク）
「ページの破損した画像を見つけてください。」（リンクではなく画像）
「APIエンドポイントのHTTPステータスを確認してください。」（ファイルシステムではなくHTTP）

結果ルーブリック

/internal-link-auditからの良好な出力は以下のすべてを満たす必要があります：

評価基準	合格条件
リンク切れをソースファイル別にグループ化	はい、ファイルごとに表で表示
ソースファイル、リンクテキスト、href、失敗理由を表示	リンク切れごとに4つのフィールドすべてが存在
正常なリンクはサマリーカウントにのみ表示	正常なリンクの長いリストなし
リンク切れがない場合は明示的な「リンク切れなし」メッセージを表示	該当する場合に表示
check-links.shが存在する場合、スクリプト出力を先頭に追加	スクリプトが最初に実行され、分析を下に追加
外部リンクをチェックしない	外部リンクはレポートに含まれない

ポジティブケースを最初に実行してください。5つすべてでスキルが発動する場合は、ネガティブケースに進んでください。ネガティブケースのいずれかで発動した場合、説明に問題があります。

過度なトリガー、トリガー漏れ、弱い出力を修正する

3つの障害モード、3つの修正方法。これらは個別の問題で、それぞれ異なるソリューションが必要です。

過度なトリガーとは、スキルが作動すべきでない場面で発火することです。通常は説明文が広すぎることが原因です。修正方法は「Use when」句に除外言語を追加することです。

Do NOT use for external link checks, HTTP status checks,

sitemap validation, or image audits.

明示的な除外を追加すると、肯定的なトリガーを削除することなくマッチ範囲を狭めることができます。

トリガー漏れとは、スキルは存在するが自動的に発火しない場合を指します。説明文が実際のユーザー言語と一致していません。修正方法は、正式な説明ではなく、実際の使用言語を反映したトリガーフレーズを追加することです。「デッドリンクはありますか？」は「内部ナビゲーションを監査する」とは異なりますが、どちらも同じスキルを実行すべきです。

Towards Data Scienceガイドでは最適化ループについて説明しています。テストケースを分割し、トリガー率を測定し、改善された説明を生成し、最高スコアを選択します。手動で少数のプロンプトを使用して実行することも、Anthropicのスキル作成スキルを使用して半自動化することもできます。

弱い出力とは、スキルは発火するが出力が不安定または不完全な場合を指します。これは説明の問題ではなく、本体の問題です。定義したルーブリックを確認してください。どの基準が失敗していますか？より具体的なフォーマット指示を追加します。出力に失敗理由の列がない場合は、指示で明示的にそう述べてください。成功しているリンクをすべてリストアップしている場合（望ましくない場合）は「成功しているリンクを個別にリストアップしないでください」と追加します。

Claude Code自動化のスタックを管理していて、スキルがどのように適合しているかについて全体像を知りたい場合は、Claude Code超能力ポストが周囲のワークフローについて説明しています。

成長中のチームまたは複数のクライアントプロジェクトを扱うエージェンシーの場合、専用のClaude Codeエージェンシーセットアップページは一見の価値があります。複数プロジェクト環境でスキルを整理する方法について説明しています。

スキルをパッケージ化し、維持する

スキルがすべての肯定的なテストに合格し、否定的なテストには合格しない場合、適切にパッケージ化してください。

最終的なフォルダ構造

~/.claude/skills/internal-link-audit/

├── SKILL.md

├── scripts/

│ └── check-links.sh (optional, referenced in instructions)

└── references/

└── anchor-edge-cases.md (optional, for edge-case rules)

プロジェクトと人間での共有

~/.claude/skills/内の個人スキルは、あなたのマシン上のすべてのプロジェクトで利用可能です。チーム配布の場合、スキルを共有リポジトリに移動し、チームメンバーが個人スキルフォルダにシンボリックリンクするか、またはコピーするか、共有プロジェクトリポの.claude/skills/にコミットしてプロジェクトスコープのアクセスを得ます。

スキルフォーマットはオープン標準です。freeCodeCampのビルドガイドによると、同じSKILL.mdの構造はClaude Code、GitHub Copilot、Cursor、およびGemini CLIで機能し、インストールパスは異なりますが、ファイル形式は同じです。Claude Codeの場合、パスは~/.claude/skills/です。Copilotの場合は~/.copilot/skills/です。同じファイル、異なるホーム。

保守

スキルは漂流します。プロジェクト構造が変わり、出力形式を更新する必要があり、またはトリガーフレーズがチームがタスクについて話す方法と一致しなくなります。SKILL.mdをリポ内の他のドキュメントのように扱ってください。バージョン管理し、基盤となるワークフローが変わるときにレビューし、説明を編集した後にトリガーテストを再実行してください。

番号付けされた保守チェックリスト。

説明を変更したら、すべての肯定的および否定的なトリガーテストを再実行してください。
出力形式の要件が変わった場合、結果ルーブリックを更新してください。
scripts/にスクリプトを追加する場合、Claudeがそれを使用することを知るように、SKILL.mdの本体で明示的に参照してください。
個人スキルをチームスキルに昇格させるとき、トリガーフレーズを確認してください。チームメンバーはあなたと異なる言語を使用する可能性があります。
使われなくなったスキルは削除してください。予期しなく発動する古いスキルは、スキルがないよりも悪いです。

Claude Code Skills: 最初のSKILL.mdを書いてテストする