Claude Code Skills入門｜作り方と呼び出し方

そら／公式情報と一次資料で整理

この記事は、2026年8月24日時点のAnthropic公式ドキュメントをもとに整理しています。Claude Code Skillsは仕様変更が速い分野です。画面やフィールドの扱いが変わる可能性があるため、実際に作るときは公式ドキュメントの現在の記載も確認してください。

記事中の英語引用に続く日本語は、公式日本語版ではなく当サイトによる訳です。

結論：Skillは手順書をファイルにして必要なときに読ませる仕組み

Claude CodeのSkillは、繰り返し使う手順をSKILL.mdというファイルにまとめ、必要な場面でClaudeに読み込ませる仕組みです。毎回チャットへ同じチェックリストを貼る代わりに、決まった場所へ手順書を置いておけます。

たとえば、毎回「差分を読み、変更点をまとめ、危険な箇所を確認して」と頼んでいるなら、その流れを1つのSkillにできます。descriptionに合う依頼で自動起動させるか、/skill-nameで直接呼び出します。

Claude Codeそのものの概要や、どの作業を任せる道具なのかはClaude Codeとは何かを整理した記事で扱っています。本記事では、Claude Codeの全機能ではなく、Skillのファイル構造・置き場所・呼び出され方・最小の作り方に絞ります。

毎回チャットに手順を貼る場合とSKILL.mdに1回書く場合の対比。貼り忘れると手順が抜けるのに対し、Skillはdescriptionに合う依頼で自動起動し、/skill-nameでも呼び出せる。

SKILL.mdには何を書く？ Claude Codeとclaude.ai・APIを分けて考える

SKILL.mdは、---で囲むYAMLフロントマターと、実行時に読むMarkdown本文で構成します。ここで重要なのは、Claude Codeとclaude.ai・APIでは必須フィールドが違うことです。

Claude Codeでは全フィールドが任意、descriptionが推奨

Claude Codeの公式ドキュメントは、フロントマターについて次のように記載しています。

“All fields are optional. Only description is recommended so Claude knows when to use the skill.”

訳（当サイト）: 「すべてのフィールドは任意である。ClaudeがいつSkillを使うべきか分かるように、descriptionだけは推奨される。」

出典：Extend Claude with skills（2026年8月24日閲覧）。

Claude Codeでは、nameを省略するとディレクトリ名が一覧上の名前になります。自動起動の判断材料を明確にするため、最初の自作ではdescriptionを書く形が分かりやすいでしょう。公式チュートリアルの実例は後の「最小の自作手順」で紹介します。

claude.ai・API側ではnameとdescriptionが必須

一方、プラットフォーム側のAgent Skills解説では、SKILL.mdの必須フィールドを次のように示しています。

“Every Skill requires a SKILL.md file with YAML frontmatter”

“Required fields: name and description”

訳（当サイト）: 「すべてのSkillにYAMLフロントマター付きのSKILL.mdが必要で、必須フィールドはnameとdescriptionである。」

出典：Agent Skills overview（2026年8月24日閲覧）。

つまり、Claude Codeの最小例はdescriptionだけでも動く一方、claude.aiやAPIではnameとdescriptionが必須です。Claude Code独自のフィールドは、別の面へ持ち出すとアップロード等が失敗する場合があります。本記事の自作手順はClaude Code向けです。

SKILL.mdの構造図。上がYAMLフロントマター、下がMarkdown本文の2層で、Claude Codeは全フィールド任意（description推奨）、claude.aiとAPIはnameとdescriptionが必須。

Skillの置き場所で使える範囲が決まる

Claude Codeでは、SKILL.mdを置く場所によって適用範囲が変わります。初心者がまず使い分けたいのはPersonalとProjectです。

種類パス使える範囲
Personal~/.claude/skills/<skill-name>/SKILL.md自分のすべてのプロジェクト
Project.claude/skills/<skill-name>/SKILL.mdそのプロジェクト
Plugin<plugin>/skills/<skill-name>/SKILL.mdプラグインが有効な場所
Enterprisemanaged settingsで管理組織の全ユーザー

どの作業でも使う手順はPersonal、特定プロジェクトだけの手順はProjectが候補です。Project Skillは.claude/skills/をバージョン管理へ含めて共有できます。同名ならenterprise、personal、projectの順で優先され、Plugin Skillはplugin-name:skill-nameという名前空間で衝突を避けます。

どう呼ばれる？ 自動起動と明示起動の違い

ここがClaude Code Skillsの使い方で最も迷いやすいところです。Skillには、次の2つの起動経路があります。

自動起動はClaudeに選ばせる方法、明示起動は使うSkillを自分で指定する方法です。

自動起動ではdescriptionが入口になる

公式ドキュメントは、自動起動を判断するときに、ユーザーの依頼とdescriptionを照合すると説明しています。

“The description is what Claude matches your request against when determining whether to trigger the Skill, so it must say both what the Skill does and when to use it.”

訳（当サイト）: 「descriptionは、Skillを起動するか判断するときにClaudeが依頼と照合する対象である。そのため、Skillが何をするかと、いつ使うかの両方を書かなければならない。」

出典：Agent Skills overview（2026年8月24日閲覧）。

たとえば、次のdescriptionでは用途が広すぎます。

description: ファイルを手伝う。

何のファイルに何をするのか、どんな依頼で使うのかが分かりません。次のように2つの情報を分けて入れると、起動場面を判断しやすくなります。

description: Gitの差分を読み、変更点と注意点を要約する。変更内容の説明、コミットメッセージの準備、差分レビューを頼まれたときに使う。

前半の「Gitの差分を読み、変更点と注意点を要約する」が何をするか、後半の「変更内容の説明、コミットメッセージの準備、差分レビューを頼まれたとき」がいつ使うかです。

「何を変更した？」「この差分をレビューして」は上のdescriptionと対応しますが、「見ておいて」だけでは対象と目的が薄くなります。公式は三人称で書き、主要な用途を先頭に置くよう案内しています。

明示起動は/skill-nameで「これを使う」と指定する

フォルダ名がsummarize-changesなら、明示起動は次の入力です。

/summarize-changes

ディレクトリ名がコマンド名になります。まず明示起動で本体を確認し、そのあとdescriptionと依頼文の対応を調整すると、問題を切り分けやすくなります。公式例では「What did I change?」が自動起動、/summarize-changesが明示起動です。

Skillの2つの入口。自動起動はClaudeが依頼文とdescriptionを照合して選び、明示起動は/skill-nameで自分で指定する。公式例はWhat did I change?と/summarize-changes。

自動だけ・手動だけに制限することもできる

初期状態ではユーザーとClaudeの両方が起動できます。disable-model-invocation: trueはClaudeの自動起動を止め、user-invocable: falseはユーザーによる/skill-name実行を止めます。副作用のある手順を手動だけにしたい場合は前者を使います。初心者はまず初期状態で明示起動を確認し、descriptionを整えて自動起動も試す順序で十分です。

呼び出されたSKILL.mdの指示はセッション中に残りますが、allowed-toolsの権限は次のメッセージで消えます。

公式チュートリアルに沿った最小の自作手順

Claude Code公式のsummarize-changesをなぞります。契約経路はClaude Codeの料金プランで確認してください。

1. Personal Skillのフォルダを作る

公式例では、すべてのプロジェクトで使えるPersonal Skillとして次のフォルダを作ります。

mkdir -p ~/.claude/skills/summarize-changes

保存先は~/.claude/skills/summarize-changes/SKILL.mdです。summarize-changesというフォルダ名が、明示起動時の/summarize-changesになります。

2. SKILL.mdを書く

公式チュートリアルの最小例にはnameがなく、descriptionと本文で構成されています。

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

この例のdescriptionも、「未コミットの変更を要約し、危険な点を示す」という役割と、「変更内容、コミットメッセージ、差分レビューを頼まれたとき」という起動場面を含んでいます。Claude Code用の最小例では、descriptionのみのフロントマターでも動くことを確認できます。

3. 自動起動と明示起動を別々に試す

公式手順では、Gitプロジェクトで小さな変更を作り、Claude Codeを起動して2通りを試します。

What did I change?

これはdescriptionに合う依頼をして、Claudeに自動で選ばせる試し方です。次はSkill名を指定します。

/summarize-changes

明示起動では動くのに自動起動しない場合は、descriptionに利用者が自然に使う言葉があるかを確認します。YAMLが壊れていると/skill-nameは動いても自動照合ができないため、公式は--debugでの確認を案内しています。

Skillを自作する3ステップ。1でPersonal Skillのフォルダを作り、2でSKILL.mdにdescriptionを書き、3で自動起動と明示起動を別々に試す。動かないときは--debugでYAMLを確認する。

公式が明記する制限と安全上の注意

同じ書式でも、Claude Code・claude.ai・APIへ自動同期されない

カスタムSkillは、製品面をまたいで自動同期しません。Claude CodeのSkillはファイルシステム上にあり、claude.aiへ上げたSkillやAPIへ上げたSkillとは別に管理されます。

“Custom Skills do not sync across surfaces. Skills uploaded to one surface are not automatically available on others.”

訳（当サイト）: 「カスタムSkillは製品面をまたいで同期しない。1つの面へアップロードしたSkillが、ほかの面で自動的に使えるようにはならない。」

出典：Agent Skills overview（2026年8月24日閲覧）。

書式は共通していても、置き場所やアップロードは面ごとに別です。claude.ai、API、Claude Codeでそれぞれ用意します。

どのAIツールをどの用途で使うかから整理したい場合は、目的別AIツールの選び方も参考になります。

信頼できるSkillだけを使い、allowed-toolsを確認する

Skillは指示やコードを含められるため、入手元の確認が必要です。

“Use Skills only from trusted sources: those you created yourself or obtained from Anthropic.”

訳（当サイト）: 「Skillは、自分で作ったものかAnthropicから入手したものなど、信頼できる出所のものだけを使う。」

出典：Agent Skills overview（2026年8月24日閲覧）。

リポジトリに含まれるProject Skillでは、Claude Code実行前にallowed-toolsを確認してください。descriptionだけでなく、SKILL.md本文、同梱ファイル、scripts/内のコードも確認します。

外部Skillを実行する前に確認する3点。SKILL.md本文、同梱ファイルとscriptsのコード、allowed-toolsの権限。前提は信頼できる出所のものだけを使うこと。

公式に記載を見つけられなかったことは断定しない

2026年8月24日時点の調査では、Claude CodeでSkillを使うこと自体に追加料金がかかるかについて、公式の記載を見つけられませんでした。そのため、「Skillは無料」「Skillには追加料金が必要」のどちらとも断定できません。Claude Codeの契約条件や料金は、料金記事と公式ページで現在の情報を確認してください。

よくある質問

Claude CodeのSkillにはnameが必須ですか。

Claude Codeではフロントマターの全フィールドが任意で、descriptionが推奨されています。公式チュートリアルの最小例にもnameはなく、ディレクトリ名がコマンド名になります。ただし、claude.aiやAPI側のAgent Skillsではnameとdescriptionが必須です。

Skillが自動で起動しないときは何を確認しますか。

まず/skill-nameで明示起動できるかを試し、Skill本体と自動照合の問題を分けます。次に、descriptionへ「何をするか」と「いつ使うか」が入り、利用者が自然に使う言葉と対応しているかを確認してください。YAMLの書式が壊れている場合は、--debugで解析エラーを確認できます。

自動起動と/skill-nameはどちらを使えばよいですか。

動作確認や、必ず特定の手順を使いたい場面では/skill-nameによる明示起動が分かりやすい方法です。自然な依頼から必要な手順を選んでほしい場合は、descriptionを具体的にして自動起動を使います。初めは明示起動で確認してから自動起動を調整すると、原因を切り分けやすくなります。

Personal SkillとProject Skillはどう選びますか。

複数のプロジェクトで共通して使う手順は~/.claude/skills/のPersonal Skill、そのプロジェクトだけの手順は.claude/skills/のProject Skillが候補です。Project Skillはバージョン管理へ含めて共有できます。同名の場合はpersonalがprojectより優先される点に注意してください。

claude.aiで作ったSkillはClaude Codeにも自動で入りますか。

入りません。公式ドキュメントは、カスタムSkillが製品面をまたいで自動同期されないと明記しています。書式が共通していても、Claude Code、claude.ai、APIで置き場所やアップロードを分ける必要があります。

まとめ

Claude Code Skillsは、繰り返す手順をSKILL.mdへまとめ、必要な場面で読み込ませる仕組みです。最初の1つを作るときは、次の順に整理すると迷いにくくなります。

  1. 毎回貼っている手順を1つ選ぶ
  2. PersonalかProjectかを決め、専用フォルダへSKILL.mdを置く
  3. descriptionへ「何をするか」と「いつ使うか」を書く
  4. まず/skill-nameで明示起動し、次に自然な依頼で自動起動を試す
  5. 外部のSkillは本文・同梱コード・allowed-toolsを確認する

最も重要な分岐は、自動起動はdescriptionとの照合、明示起動は/skill-nameによる直接指定という違いです。また、Claude Codeではdescriptionだけの最小例が動きますが、claude.aiやAPIではnameとdescriptionが必須です。製品面を混ぜず、2026年8月24日時点の公式記載と、実際に使う面を対応させて作ってください。