Introduction to agent skills ｜ Lesson 2「Creating your first skill」（全文ナレッジ）
テキストレッスン＋埋め込み動画 4分（YouTube: Wx6_vjFFyHM）／ 2026-07-03
日本語ナレッジ（レッスン本文・完全版）
このレッスンで学ぶこと（What you'll learn）
所要時間の目安：20分
このレッスンを終えると、次のことができるようになります：
- 正しい frontmatter 構造を持つスキルをゼロから作成できる
- スキルが Claude Code で正しくロードされることをテスト・検証できる
- Claude Code が入ってくるリクエストを利用可能なスキルにどう照合するかを説明できる
- スキルの優先順位ヒエラルキー（Enterprise・Personal・Project・Plugins）を説明できる
動画「Creating your first skill」（4分）
この動画では、スキルをゼロから作る手順を追います——すべてのプロジェクトで使える個人用の PR 説明文スキルです。SKILL.md ファイルの正確な構造、テスト方法、そして Claude Code がスキルを発見してリクエストに照合する仕組みが分かります。名前が衝突した時にどのスキルが勝つかを決める優先順位ヒエラルキーも扱います。
キーテイクアウェイ（Key takeaways）
- スキルとは、frontmatter にメタデータ（name・description）、その下に指示を書いた SKILL.md ファイルを含むディレクトリ
- Claude は起動時にスキルの name と description だけをロードし、入ってくるリクエストをセマンティックマッチング（意味的照合）でそれらの description と照合する
- Claude がスキルの全文をコンテキストにロードする前に、確認プロンプトが表示される
- 名前衝突時の優先順位：Enterprise → Personal → Project → Plugins
- スキルの更新は SKILL.md の編集、削除はディレクトリの削除。変更を反映するには必ず Claude Code を再起動する
本文導入
スキルをゼロから作る手順を追い、その後、Claude Code が裏側で実際にどうスキルをロード・照合しているかを見ていきましょう。
スキルの作成（Creating a Skill）
一貫したフォーマットで PR の説明文を書く方法を Claude に教える個人用スキルを作ります。個人用スキルなので、ホームディレクトリに置かれ、すべてのプロジェクトで機能します。
まず、skills フォルダの中にスキル用のディレクトリを作ります。ディレクトリ名はスキル名と一致させます：
mkdir -p ~/.claude/skills/pr-description
次に、そのディレクトリの中に SKILL.md ファイルを作ります。ファイルは frontmatter のダッシュで区切られた2つの部分から成ります：
---
name: pr-description
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or when the user asks to summarize changes for a pull request.
---
When writing a PR description:
1. Run `git diff main...HEAD` to see all changes on this branch
2. Write a description following this format:
## What
One sentence explaining what this PR does.
## Why
Brief context on why this change is needed
## Changes
- Bullet points of specific changes made
- Group related changes together
- Mention any files deleted or renamed
name はスキルを識別します。description は Claude にいつ使うべきかを伝えます——これが照合基準です。2つ目のダッシュ以降のすべてが、スキル起動時に Claude が従う指示です。
スキルのテスト（Testing Your Skill）
Claude Code は起動時にスキルをロードするので、スキル作成後はセッションを再起動してください。利用可能なスキルの一覧を確認すれば、使えるようになったか検証できます。
一覧に自分のスキルが表示されるはずです。テストするには、ブランチ上で何か変更を加え、「write a PR description for my changes（変更の PR 説明文を書いて）」のように言います。Claude は PR description スキルを使っていることを示し、diff を確認して、あなたのテンプレートに従った説明文を書きます——毎回同じフォーマットです。
スキル照合の仕組み（How Skill Matching Works）
Claude Code は起動時に4つの場所をスキャンしてスキルを探しますが、ロードするのは name と description だけで、全文ではありません。これは重要なポイントです。
リクエストを送ると、Claude はあなたのメッセージを利用可能なすべてのスキルの description と比較します。例えば「explain what this function does（この関数が何をするか説明して）」は、「explain code with visual diagrams（視覚的な図解でコードを説明する）」と書かれたスキルに一致します。意図が重なるからです。
一致が見つかると、Claude はスキルのロードを確認するよう求めます。この確認ステップによって、Claude がどんなコンテキストを取り込もうとしているかを把握し続けられます。確認すると、Claude は SKILL.md ファイル全体を読み、その指示に従います。
スキルの優先順位（Skill Priority）
自分の個人用スキルと同名のスキルを持つリポジトリをクローンしたら、どちらが勝つのでしょうか？明確な優先順位があります：
- Enterprise — managed settings（管理設定）。最優先
- Personal — ホームディレクトリ（
~/.claude/skills）
- Project — リポジトリ内の
.claude/skills ディレクトリ
- Plugins — インストール済みプラグイン。最下位
これにより、組織はエンタープライズスキルで標準を強制しつつ、個人のカスタマイズも許容できます。会社にエンタープライズの「code-review」スキルがあり、あなたが同名の個人用「code-review」スキルを作った場合、エンタープライズ版が優先されます。
衝突を避けるには、説明的な名前を使いましょう。単なる「review」ではなく、「frontend-review」や「backend-review」のような名前にします。
スキルの更新と削除（Updating and Removing Skills）
スキルを更新するには、その SKILL.md ファイルを編集します。削除するには、そのディレクトリを削除します。変更後は、反映のために Claude Code を再起動してください。
レッスンの振り返り（Lesson reflection）
- あなたの日々のワークフローの中で、今すぐスキル化できるタスクは何ですか？その description はどんな内容になりますか？
- 優先順位ヒエラルキーは、チームのスキル管理戦略にどう影響するでしょうか？
次のレッスン（What's next）
次のレッスンでは、発展的な設定オプションを扱います。メタデータフィールド、allowed-tools によるツール制限、そしてプログレッシブ・ディスクロージャーとマルチファイル構成による大きなスキルの構造化です。
実務ポイント（このレッスンから持ち帰るもの）
- 作成手順は3ステップ——
mkdir -p ~/.claude/skills/<スキル名> → SKILL.md 作成（frontmatter＋指示）→ Claude Code 再起動。ディレクトリ名＝スキル名。
- 起動時は name/description のみロード——全文はマッチ成立＋ユーザー確認後にロード。確認プロンプトはコンテキストへの取り込みを可視化する安全装置。
- 照合はセマンティックマッチング——キーワード完全一致ではなく意図の重なりで判定。「explain what this function does」が「explain code with visual diagrams」にマッチする。
- 優先順位を暗記——Enterprise → Personal → Project → Plugins。同名衝突ではエンタープライズが常に勝つ。
- 名前は具体的に——「review」ではなく「frontend-review」「backend-review」。衝突予防の第一手段はリネーム。
- 変更は再起動しないと反映されない——更新・削除のどちらも Claude Code の再起動が必要。
動画逐語（日本語訳）
[0:03] では、スキルを作ってみましょう。このスキルは、視覚的な図解とアナロジーを使ってコードを説明してほしい、という私たちの好みのやり方を Claude に教えるものです。その後、Claude がスキルを使う時に内部（フードの下）で何が起きているかを見ていきます。
[0:18] まず、スキル用のディレクトリを作りましょう。今回作るのは個人用スキルで、多くのプロジェクトで使うことになるので、ホームディレクトリに置きます。skills ディレクトリの中に「スキル名のディレクトリ」を作っている点に注意してください。
[0:33] 次に、スキルを作成します。
[0:38] name はスキルを識別します。description は Claude にいつ使うべきかを伝えます。これが照合基準です。そして、2つ目のダッシュ以降のすべてが、Claude が従う指示になります。
[0:52] Claude Code は起動時にスキルをロードします。なのでセッションを再起動してください。それから、利用可能になっているか検証します。
[1:00] 一覧に「PR description」が表示されるはずです。
[1:04] では、テストしましょう。ブランチ上で何か変更を加えて、「変更の PR 説明文を書いて」と言います。
[1:11] すると Claude は、PR description スキルを使っていることを表示します。
[1:17] その後、diff を確認し、あなたのテンプレートに従って説明文を書きます。毎回まったく同じフォーマットです。
[1:24] Claude Code は起動時に、4つの場所をスキャンしてスキルを探します。エンタープライズのパス、あなたの個人用 Claude スキル、プロジェクトの Claude スキル、そしてインストール済みプラグインです。各スキルの name と description だけをロードし、全文はロードしません。これは後で重要になります。リクエストを送ると、Claude はそれをスキルの description と比較します。「この関数が何をするか説明して」は、「視覚的な図解でコードを説明する」と書かれたスキルに一致します。意図が重なるからです。すると、スキルをロードしてよいか確認を求められます。この確認ステップのおかげで、Claude がどんなコンテキストを使おうとしているかを把握できます。確認すると、Claude はファイル全体を読み、その指示に従います。
[2:00] さて、Git リポジトリをクローンして、スキル名が重複していたとしましょう。どちらが勝つのでしょうか？優先順位リストはこうです。最上位はエンタープライズで、managed settings にあります。2番目は個人用で、いままさに作っているようなホームディレクトリの設定にあります。3番目はプロジェクトで、リポジトリ内の .claude ディレクトリです。そして最下位はプラグインで、オンラインで入手したプラグインの置き場所です。
[2:27] これにより、組織は標準を強制しつつ、名前を変えたスキルによる個人のカスタマイズを許容できます。会社にエンタープライズの code review スキルがあり、あなたが個人用の code review スキルを作った場合、エンタープライズ版が優先されます。衝突を避けるには、説明的な名前を使いましょう。「review」ではなく、「front-end PR review」や「security review」のように。
[2:52] スキルを更新するには、SKILL.md ファイルを編集するだけ。シンプルです。削除するには、ディレクトリを消します。変更後は Claude Code を再起動すると反映されます。
[3:06] まとめ。スキルの作成とは、メタデータと指示を含む SKILL.md ファイルを持つディレクトリを作ることです。Claude は起動時にスキルの name と description をロードし、入ってくるリクエストをそれらの description と照合し、全文をロードする前に確認を求めます。名前の衝突は優先順位ルールで処理されます——エンタープライズが個人に優先し、個人がプロジェクトに優先し、プロジェクトがプラグインに優先します。スキルを更新するには SKILL.md ファイルを編集し、変更を反映するには Claude Code を再起動します。
英語原文
レッスン本文
[YouTube: Wx6_vjFFyHM (4 minutes)]
Creating your first skill
What you'll learn
Estimated time: 20 minutes
By the end of this lesson you'll be able to:
Create a skill from scratch with proper frontmatter structure
Test and verify that a skill loads correctly in Claude Code
Explain how Claude Code matches incoming requests to available skills
Describe the skill priority hierarchy (Enterprise, Personal, Project, Plugins)
Creating your first skill (4 minutes)
This video walks through building a skill from scratch — a personal PR description skill that works across all your projects. You'll see exactly how to structure the SKILL.md file, test it, and understand how Claude Code discovers and matches skills to your requests. The video also covers the priority hierarchy that determines which skill wins when names conflict.
Key takeaways
A skill is a directory containing a SKILL.md file with metadata (name, description) in frontmatter and instructions below
Claude loads only skill names and descriptions at startup, then matches incoming requests against those descriptions using semantic matching
You get a confirmation prompt before Claude loads the full skill content into context
Priority for name conflicts: Enterprise → Personal → Project → Plugins
To update a skill, edit its SKILL.md. To remove one, delete its directory. Always restart Claude Code for changes to take effect
Let's walk through creating a skill from scratch, then look at how Claude Code actually loads and matches skills behind the scenes.
Creating a Skill
We'll build a personal skill that teaches Claude how to write PR descriptions in a consistent format. Since it's a personal skill, it lives in your home directory and works across all your projects.
First, create a directory for your skill inside the skills folder. The directory name should match your skill name:
mkdir -p ~/.claude/skills/pr-description
Then create a SKILL.md file inside that directory. The file has two parts separated by frontmatter dashes:
---
name: pr-description
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or when the user asks to summarize changes for a pull request.
---
When writing a PR description:
1. Run `git diff main...HEAD` to see all changes on this branch
2. Write a description following this format:
## What
One sentence explaining what this PR does.
## Why
Brief context on why this change is needed
## Changes
- Bullet points of specific changes made
- Group related changes together
- Mention any files deleted or renamed
The name identifies your skill. The description tells Claude when to use it — this is the matching criteria. Everything after the second set of dashes is the instructions Claude follows when the skill is activated.
Testing Your Skill
Claude Code loads skills at startup, so restart your session after creating one. You can verify it's available by checking the available skills list.
You should see your skill listed. To test it, make some changes on a branch and say something like "write a PR description for my changes." Claude will indicate it's using the PR description skill, check your diff, and write a description following your template — same format every time.
How Skill Matching Works
When Claude Code starts, it scans four locations for skills but only loads the name and description — not the full content. This is an important detail.
When you send a request, Claude compares your message against the descriptions of all available skills. For example, "explain what this function does" would match a skill described as "explain code with visual diagrams" because the intent overlaps.
Once a match is found, Claude asks you to confirm loading the skill. This confirmation step keeps you aware of what context Claude is pulling in. After you confirm, Claude reads the complete SKILL.md file and follows its instructions.
Skill Priority
If you clone a repository that has a skill with the same name as one of your personal skills, which one wins? There's a clear priority order:
Enterprise — managed settings, highest priority
Personal — your home directory (~/.claude/skills)
Project — the .claude/skills directory inside a repository
Plugins — installed plugins, lowest priority
This lets organizations enforce standards through enterprise skills while still allowing individual customization. If your company has an enterprise "code-review" skill and you create a personal "code-review" skill with the same name, the enterprise version takes precedence.
To avoid conflicts, use descriptive names. Instead of just "review," use something like "frontend-review" or "backend-review."
Updating and Removing Skills
To update a skill, edit its SKILL.md file. To remove one, delete its directory. Restart Claude Code after any changes for them to take effect.
Lesson reflection
What's one task in your daily workflow that you could turn into a skill right now? What would the description look like?
How might the priority hierarchy affect your team's skill management strategy?
What's next
In the next lesson: advanced configuration options including metadata fields, tool restrictions with allowed-tools, and how to structure larger skills using progressive disclosure and multi-file organization.
動画字幕（重複除去済み）
So, let's create a skill. This skill will teach Claude how we would like it to explain code using visual diagrams and analogies. Then, we'll look at what happens under the hood when Claude uses it.
First, let's create a directory for your skill. We're going to be making a personal skill, so it'll live in many projects, so it will go in your home directory. Take into consideration that we're creating a directory with the skill name inside of the skills directory.
Now create the skill.
The name identifies your skill. The description tells Claude when to use it. This is the matching criteria. And then everything after the second dashes is the instructions that Claude follows.
Claude Code loads skills at startup. So restart your session. Then verify it's available. You should see PR description in the list.
Now test it. Make some changes on a branch and say, "Write a PR description for my changes." Claude will then show you that it's using the PR description skill. After that, it'll check your diff and write a description following your template. Same format every single time.
When Claude Code starts, it scans four locations for skills. Enterprise paths, your personal Claude skills, the project's Claude skills, and installed plugins. It loads only the name and description of each skill, not the full content. This is important later. When you send a request, Claude compares it to the descriptions of your skills. "Explain what this function does" matches a skill described as "explain code with visual diagrams" because the intent overlaps. It will then ask you to confirm loading up the skill. This confirmation step keeps you aware of what context Claude is using. After you confirm, Claude reads the complete file and follows its instructions.
Now, let's say you clone a Git repository and have an overlapping skill name. Well, which one wins? Here's the priority list. The highest is enterprise, which lives in the managed settings. Two is the personal, which lives in your root directory configuration like we're doing right now. Three is the project which is the .claude directory inside of your repository. And the lowest is the plugins where you store your plugins that you got online.
This lets organizations enforce standards while allowing individual customization through differently named skills. If your company has an enterprise code review skill and you create a personal code review skill, the enterprise version of that takes precedence. To avoid conflicts, use descriptive names. Instead of review, use front-end PR review or security review.
To update a skill, edit its skill.md file. Simple. To remove one, delete its directory. Restart Claude Code after changes for them to take effect.
Creating a skill means making a directory with a skill.md file containing metadata and instructions. Claude loads skill names and descriptions at startup, matches incoming requests against those descriptions and asks for confirmation before loading the full content. Priority rules handling name conflicts: enterprise overrides personal, personal overrides project, project overrides plugins. Edit the skill.md file to update a skill and restart Claude Code for changes to take effect.