SKILL.mdの書き方完全ガイド｜Claude Codeスキルを自作する5ステップ

最終更新: 2026年2月18日

SKILL.mdとは、Claude Codeの振る舞いをカスタマイズするための構造化された指示ファイルです。YAMLフロントマターとMarkdownを組み合わせた形式で、自分だけのAIスキルを作成・共有できます。

この記事では、SKILL.mdの書き方を5ステップで解説します。初めてスキルを作る方でも、この手順に沿えば高品質なスキルを公開できます。

SKILL.mdとは？

SKILL.mdは、Anthropicが策定したAIスキルの標準フォーマットです。Claude Codeがネイティブにサポートしており、プロジェクトに配置するだけでAIの振る舞いを拡張できます。

ファイル構成:

.claude/skills/<スキル名>/
├── SKILL.md       ← メインの指示ファイル（必須）
├── scripts/       ← 補助スクリプト（任意）
└── resources/     ← 参照データ（任意）

ステップ1: スキルの目的を明確にする

良いスキルは1つの明確な目的を持っています。まず以下を決めましょう。

• 誰のためのスキルか？（例: Next.js開発者、SEO担当者、デザイナー）
• 何を解決するのか？（例: テスト自動化、LP制作、コードレビュー）
• どのツールで使うのか？（例: Claude Code、Cursor、Copilot）

良いスキルの例

ステップ2: SKILL.mdのフロントマターを書く

SKILL.mdの冒頭にはYAMLフロントマターを記述します。これはスキルのメタデータです。

---
name: nextjs-app-router-guide
description: >
  Next.js App Routerのベストプラクティスに沿ったコードを生成するスキル。
  Server/Client Componentの使い分け、データフェッチ、メタデータ設定をガイド。
---

フロントマターの書き方のコツ

• name: ケバブケース（小文字 + ハイフン）で記述
• description: Claude Codeがスキルを使うかどうかを判断する際の基準になる。何ができるスキルかを具体的に説明する
• 1〜3文で簡潔にまとめるのがベスト

ステップ3: Markdown本文で指示を書く

フロントマターの後に、AIへの具体的な指示をMarkdown形式で記述します。

基本構造

# スキル名

あなたは[専門分野]の専門家です。以下のルールに従って[タスク]を実行してください。

## 基本ルール

- ルール1: [具体的な指示]
- ルール2: [具体的な指示]
- ルール3: [具体的な指示]

## コーディング規約

### ファイル構成
- [ディレクトリ構成のルール]

### 命名規則
- [変数名、関数名、ファイル名のルール]

## テンプレート

[コードテンプレートや出力例]

## 禁止事項

- [やってはいけないこと]

効果的な指示の書き方

1. 具体的に書く

# ❌ 曖昧な指示
きれいなコードを書いてください。

# ✅ 具体的な指示
- 関数は1つの責務のみを持つこと（単一責任原則）
- 関数の行数は30行以内に収める
- 引数は4つ以下にする
- ネストは3段階以内にする

2. 例を示す

## コンポーネントの書き方

以下のパターンに従ってReactコンポーネントを作成:

\`\`\`tsx
// ✅ 推奨パターン
export function UserCard({ user }: { user: User }) {
  return (
    <div className="rounded-xl border p-4">
      <h3 className="font-semibold">{user.name}</h3>
      <p className="text-sm text-muted">{user.email}</p>
    </div>
  );
}
\`\`\`

3. 段階的に開示する（プログレッシブディスクロージャー）

スキルの冒頭に最も重要なルールを配置し、詳細は後半に記述します。AIはコンテキストの冒頭部分をより重視するためです。

ステップ4: テスト・検証する

スキルを書いたら、実際にClaude Codeで動作確認します。

テスト手順

1. スキルファイルを配置する

mkdir -p .claude/skills/my-skill
# SKILL.mdを配置

2. Claude Codeを起動してタスクを依頼する

claude "このプロジェクトに新しいAPIエンドポイントを追加して"

3. スキルの指示が反映されているか確認する

• コーディング規約が守られているか
• ファイル構成が正しいか
• 指定したパターンが使われているか

よくある問題と対処法

ステップ5: AgentSkills.tokyoに公開する

スキルが完成したら、AgentSkills.tokyoで公開して他の開発者と共有しましょう。

公開手順

1. AgentSkills.tokyo で無料アカウントを作成
2. ダッシュボードから「スキルを投稿する」を選択
3. スキル名、説明、カテゴリーを入力
4. SKILL.mdファイルをアップロード
5. 「公開する」をクリック

自動モデレーション（スパム・不適切表現チェック）を通過すれば、即座に公開されます。

公開時のコツ

• 説明文は丁寧に: 何ができるスキルかを具体的に書くと、ダウンロードされやすくなる
• タグを適切に設定: 対応ツール（Claude Code、Cursor等）やカテゴリーを正確に設定
• デモ画像を追加: スキルの出力例をスクリーンショットで添付すると、品質の高さが伝わる

SKILL.mdテンプレート（コピペ用）

以下をコピーして、自分のスキルの基礎として使えます。

---
name: my-awesome-skill
description: >
  このスキルの説明を1〜3文で記述。
  Claude Codeがスキルを使うかどうかを判断する基準になります。
---

# スキル名

あなたは[専門分野]の専門家です。

## 基本方針

- [方針1]
- [方針2]
- [方針3]

## コーディング規約

### ファイル構成

- [ルール]

### 命名規則

- [ルール]

## テンプレート・パターン

[コード例]

## 禁止事項

- [禁止事項1]
- [禁止事項2]

よくある質問（FAQ）

Q1. SKILL.mdの最大サイズはありますか？

明確な上限はありませんが、実用的には500行〜1000行程度が推奨です。長すぎるとAIのコンテキストを圧迫し、重要な指示が埋もれる可能性があります。

Q2. 複数のスキルを同時に使えますか？

はい、.claude/skills/ ディレクトリに複数のスキルフォルダを配置できます。Claude Codeはタスクの内容に応じて、適切なスキルを自動的に選択します。

Q3. スキルを更新したらすぐ反映されますか？

はい、SKILL.mdを保存するだけで、次のClaude Codeとの対話から新しい内容が反映されます。再起動は不要です。

Q4. Cursor用に変換するにはどうすればいいですか？

SKILL.mdのMarkdown本文部分を .cursorrules ファイルにコピーするだけで動作します。YAMLフロントマターはCursor固有の形式では不要です。

まとめ

SKILL.mdの作成は、以下の5ステップで完了します。

1. 目的を明確にする — 誰のための、何を解決するスキルか
2. フロントマターを書く — name + descriptionのメタデータ
3. Markdown本文で指示を書く — 具体的で段階的な指示
4. テスト・検証する — 実際のClaude Codeで動作確認
5. 公開する — AgentSkills.tokyoで他の開発者と共有

自分だけのAIスキルを作って、開発ワークフローを最適化しましょう。作ったスキルはAgentSkills.tokyoで公開できます。

この記事を書いた人 AgentSkills.tokyo編集部 | AIスキルマーケットプレイス運営チーム