👌
Claude Skills (Agent Skills) 入門

_mkazutaka
2025/10/21に公開
 はじめにこんにちは、エクスプラザの@_mkazutakaです。

今回は、10/16にAnthropicが発表した、Claude Skills(Agent Skills)について入門と題して紹介したいと思います。
Claude SkillsなのかAgent Skillsなのか少し不明瞭なのですが、公式ニュースのTitleタグ以外にClaude Skillsというワードは見つけられなかったので、本記事ではClaude Skillsではなく、Agent Skillsというワードをつかっていきたいと思います。

 公式リンク集とはいえ、この記事で書く内容自体はほぼ公式ドキュメントにかいてあります。参考にしたソースを一覧で置いておくので、ぜひ一次ソースを確認することをおすすめします。
公式ニュース: Introducing Agent Skills
テックブログ: Equipping agents for the real world with Agent Skills - Engineering \ Anthropic
ドキュメント: Claude Code の Agent Skills
ドキュメント: Claude Developer Platform の Agent Skills
ドキュメント: Using Agent Skills with the API
リリースノート: Claude Developer Platform の リリースノート

 参考リンク集またすでに多くの方が言及されている記事もあるため。そちらも参考になるかと思います。
https://note.com/npaka/n/n6e221d209d90
https://blog.lai.so/claude-skills/
https://zenn.dev/canly/articles/965cc8e7e9be8d

 Agent SkillsとはClaudeもしくはClaude Codeの機能を拡張する機能の一つです。SKILL.mdを起点に、スクリプトや複数のマークダウンを一つのディレクトリに格納でき、それを一まとまりのモジュールとして配布やClaude上から参照することができます。
公式ニュースを翻訳によると以下のように紹介されています。
Claudeは現在、スキルを活用することで特定のタスクをより効率的に処理できるようになりました。スキルとは、指示書、スクリプト、リソースなどを含むフォルダ形式で、必要に応じてClaudeが読み込めるようになっています。

https://www.anthropic.com/news/skills

 Agent Skillsをゼロから実装してみる公式からAgent Skillを作るAgent Skillが提供されていたりはするのですが(anthropics/skillsのskill creator)、今回は中身がどうなっているのかを具体的に把握するためゼロから作っていきます。
今回は、文字数を数えるスキルを実装してみましょう。
ClaudeCodeの場合、以下２つのどちらかのディレクトリ上でスキルを作成すれば参照することができます。プロジェクトに依存しない形でSkillを作成したければ前者、そうでなければ後者のパスで作成できます。
$ mkdir -p ~/.claude/skills/count-character
# もしくは
$ mkdir -p .claude/skills/count-character
今回はSveltekitのHelloWorldのプロジェクトを用意し、そこでAgent Skills作ることとしました。
$ npx sv create claude-skill-demo
$ cd claude-skill-demo
$ mkdir -p .claude/skills/count-character 

 Agent Skillsの構成Agent Skills自体はシンプルで基本的には、ディレクトリの中にSKILL.mdを作成すれば終了です。実現したいスキルに応じて別のマークダウンファイルやスクリプトを準備します。
今回は、SKILL.mdと数を数えるスクリプトcount-character.pyの２つを用意します。

 SKILL.mdの構成SKILL.mdは、主に2つの要素で構成され、それぞれ異なるタイミングで読み込まれます(参照)。
メタデータ(YAML frontmatter)
ファイルの先頭に記載されるメタデータ
実行にかかわらず常に読み込まれる

指示内容
メタデータのあとに記載される指示内容
トリガー実行時に読み込まれる

具体的には以下のようになります。
 SKILL.md
---
name: XXX
description: YYYYY
---

Say `Hello World`
今回は、以下のように用意します。
 .claude/skills/count-character/SKILL.md
---
name: Counting Characters
description: Count Character from text.
---

# Count Character Guideline

## Overview

A User can count character from text.

## Count character

RUn exactly this script:

\`\`\`bash
python scripts/count-character.py "<YOUR Text>"
\`\`\`
文字数を数えるスクリプト、count-character.pyも用意します。

ディレクトリの配置はどこでもいいと思いますが、公式のレポジトリ等を見るとscripts/ に配置されることが多そうなので同様に配置します。
 .claude/skills/count-character/scripts/count-character.py
import sys
print(len(sys.argv[1]) if len(sys.argv) > 1 else 0)
以上で上記のスキルは実装は完了です。

 Claude Codeからつかってみる実際につかってみましょう。フォルダにスキルを配置すれば勝手に読み込んでくれます。あとはプロンプトでスキルを使うよう指定してあげれば完了です。
実行結果> +page.svelteを200-250文字にしてください。スキルをつかって文字数は計測して 

⏺ +page.svelteファイルを200-250文字に編集します。まずファ
  イルを探して内容を確認します。

⏺ Search(pattern: "**/*+page.svelte")
  ⎿  Found 1 file (ctrl+o to expand)

⏺ Read(src/routes/+page.svelte)
  ⎿  Read 3 lines

⏺ 現在の内容は約130文字です。200-250文字に拡張します。

⏺ Write(src/routes/+page.svelte)
  ⎿  Updated src/routes/+page.svelte with 2 additions an
      1 removal
       1    <h1>Welcome to SvelteKit</h1>
       2 -  <p>Visit <a href="https://svelte.dev/docs/
         -  kit">svelte.dev/docs/kit</a> to read the 
         -  documentation</p>
       2 +  <p>Visit <a href="https://svelte.dev/docs/
         +  kit">svelte.dev/docs/kit</a> to read the 
         +  documentation
         +   and start building amazing web 
         +  applications with SvelteKit.</p>
       3 +  <p>This framework combines the power of 
         + Svelte with a flexible routing system, 
         + server-side rendering, and modern web 
         + development tools to create fast, efficient
         +  applications.</p>
       4   \ No newline at end of file

⏺ ファイルを更新しました。次にスキルで文字数を計測します
  。

⏺ Bash(python scripts/count-character.py /Users/mkazutaka/tem
      p/claude-skill-demo/src/routes/+page.svelte)
  ⎿  Error: python: can't open file '/Users/mkazutaka/temp/cla
     ude-skill-demo/scripts/count-character.py': [Errno 2] No 
     such file or directory

⏺ Search(pattern: "**/count-character.py")
  ⎿  Found 0 files 

> The "Counting Characters" skill is running 

> The "Counting Characters" skill is running 

⏺ スキルを使って文字数を計測します。

⏺ Bash(python scripts/count-character.py "<h1>Welcome to
      SvelteKit</h1>
      <p>Visit <a href=\"https://svelte.dev/docs/kit\">svelte
      .dev/docs/kit</a> to read the documentat…)
  ⎿  Error: python: can't open file '/Users/mkazutaka/temp/cla
     ude-skill-demo/scripts/count-character.py': [Errno 2] No 
     such file or directory

⏺ Search(pattern: "**/*.py")
  ⎿  Found 0 files 

⏺ Bash(ls -la /Users/mkazutaka/temp/claude-skill-demo/.claude
      /skills/count-character/)
  ⎿ total 8                                             
    drwxr-xr-x  4 mkazutaka  staff  128 10月 20 17:36 .
    drwxr-xr-x  3 mkazutaka  staff   96 10月 20 17:01 ..
    … +4 lines (ctrl+o to expand)


⏺ Bash(ls -la /Users/mkazutaka/temp/claude-skill-demo/.claude
      /skills/count-character/scripts/)
  ⎿ total 8                                             
    drwxr-xr-x  3 mkazutaka  staff   96 10月 20 17:36 .
    drwxr-xr-x  4 mkazutaka  staff  128 10月 20 17:36 ..
    … +2 lines (ctrl+o to expand)


⏺ Bash(python /Users/mkazutaka/temp/claude-skill-demo/.claude
      /skills/count-character/scripts/count-character.py
      "<h1>Welcome to SvelteKit</h1>
      <p>Visit <a href=\"https…)
  ⎿  369

⏺ 現在369文字なので、200-250文字の範囲に収めるために内容
  を調整します。

⏺ Update(src/routes/+page.svelte)
  ⎿  Updated src/routes/+page.svelte with 2 additions an
      2 removals
       1    <h1>Welcome to SvelteKit</h1>
       2 -  <p>Visit <a href="https://svelte.dev/docs/
         - kit">svelte.dev/docs/kit</a> to read the 
         - documentation and start building amazing 
         - web applications with SvelteKit.</p>
       3 -  <p>This framework combines the power of 
         - Svelte with a flexible routing system, 
         - server-side rendering, and modern web 
         - development tools to create fast, efficient
         -  applications.</p>
       2   \ No newline at end of file
       3 +  <p>Visit <a href="https://svelte.dev/docs/
         + kit">svelte.dev/docs/kit</a> to read the 
         + documentation and start building amazing 
         + web applications.</p>
       4 +  <p>SvelteKit combines powerful features 
         + with modern web development tools.</p>
       5   \ No newline at end of file

⏺ Bash(python /Users/mkazutaka/temp/claude-skill-demo/.claude
      /skills/count-character/scripts/count-character.py
      "<h1>Welcome to SvelteKit</h1>
      <p>Visit <a href=\"https…)
  ⎿  254

⏺ 254文字で目標範囲を少し超えているので、もう少し調整しま
  す。

⏺ Update(src/routes/+page.svelte)
  ⎿  Updated src/routes/+page.svelte with 1 addition and
     1 removal
       1    <h1>Welcome to SvelteKit</h1>
       2 -  <p>Visit <a href="https://svelte.dev/docs/
         -  kit">svelte.dev/docs/kit</a> to read the 
         -  documentation and start building amazing 
         -  web applications.</p>
       2 +  <p>Visit <a href="https://svelte.dev/docs/
         +  kit">svelte.dev/docs/kit</a> to read the 
         +  documentation and start building 
         +  web applications.</p>
       3    <p>SvelteKit combines powerful features 
           with modern web development tools.</p>
       4   \ No newline at end of file

⏺ Bash(python /Users/mkazutaka/temp/claude-skill-demo/.claude
      /skills/count-character/scripts/count-character.py
      "<h1>Welcome to SvelteKit</h1>
      <p>Visit <a href=\"https…)
  ⎿  246

⏺ 完了しました。+page.svelteを246文字に調整しました（目標
  : 200-250文字）。

  スキルを使った文字数計測結果: 246文字

  ファイルの内容:
  <h1>Welcome to SvelteKit</h1>
  <p>Visit <a href="https://svelte.dev/docs/kit">svelte.d
  ev/docs/kit</a> to read the documentation and start
  building web applications.</p>
  <p>SvelteKit combines powerful features with modern web
   development tools.</p>
うまくいってそうですね。これで完了です

 Agent SkillsのベストプラクティスAgent Skillsのベストプラクティスもいくつか紹介されていたので、ピックアップしてたいと思います(参考)。

 メタデータの命名規則メタデータには、いくつか制限事項があります(参考)。
nameの文字数の上限: 64文字
descriptionの文字数の上限: 1024文字
これに加えてnameとdescriptionでいくつかの規則が推奨されています。

nameの命名規則は、動名詞の使用が推奨されています。HelperやToolなどの曖昧な文章は避けるべきとのことです。例えば以下のようなものが推奨されています。
Processing PDF
Analyzing spreadsheets
descriptionは、3人称での記載が推奨されています。I can help you process Excel files” よりかは、Processes Excel files and generates reportsなどが望ましいようです。

 SKILL.mdの行数SKILL.mdが500行以内を超えそうな際は、別ファイルに分けることも推奨されています。これによって、Claudeが必要に応じて外部ファイルを読み込むようになるので、コンテキストの節約につながります。

 参照ファイルの推奨事項SKILL.md から参照されるファイルにもいくつかの推奨事項があります。

 参照したファイルからまた別の参照ファイルを見ることは非推奨SKILL.mdから参照されるファイルは、head -100などのコマンドを使用してコンテンツを読まれることがあるため、結果情報が不完全になるとのことです。SKILL.mdからの参考は1階層までに制限しましょう。
公式ドキュメントの例Bad:
 SKILL.md
See [advanced.md](advanced.md)...
 advanced.md
See [details.md](details.md)...
 details.md
Here's the actual information...
Good
 SKILL.md
**Basic usage**: [instructions in SKILL.md]
**Advanced features**: See [advanced.md](advanced.md)
**API reference**: See [reference.md](reference.md)
**Examples**: See [examples.md](examples.md)

 参照ファイルが100行を超える場合は冒頭に目次を設定する同様の理由で、参考ファイルの全体像を把握できるように参照ファイルが多くの行になる場合は、目次を設定することが推奨されています。

 複雑なタスクの実行複雑な操作は、明確で段階的な手順を提供することが推奨されています。例えば、チェックリストなど提供してClaudeがタスクの状態を管理できるようにするべきとのことです。
公式ドキュメントの例## Research synthesis workflow

Copy this checklist and track your progress:

Research Progress:

 Step 1: Read all source documents

 Step 2: Identify key themes

 Step 3: Cross-reference claims

 Step 4: Create structured summary

 Step 5: Verify citations

**Step 1: Read all source documents**

Review each document in the `sources/` directory. Note the main arguments and supporting evidence.

**Step 2: Identify key themes**

Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree?

**Step 3: Cross-reference claims**

For each major claim, verify it appears in the source material. Note which source supports each point.

**Step 4: Create structured summary**

Organize findings by theme. Include:
- Main claim
- Supporting evidence from sources
- Conflicting viewpoints (if any)

**Step 5: Verify citations**

Check that every claim references the correct source document. If citations are incomplete, return to Step 3.
その他にも複数のベストプラクティスが共有されているので、ぜひ御覧ください

 まとめ / 感想ClaudeのAgent Skillsについて紹介しました。
いままでサブエージェントなどよりより強力になった気がします。いくつかの公式ドキュメントを眺めていたのですが、100種類以上のスキルを使うことが想定としてあるようです。スキルを簡単に追加できるスキルもあるので、今までコマンドでやっていたフローを渡してスキルを作る癖をつけると今度強い武器になるのでは...と思っております
株式会社エクスプラザPublication
「プロダクトの力で、豊かな暮らしをつくる」をミッションに、法人向けに生成AIのPoC、コンサルティング〜開発を支援する事業を展開しております。エンジニア募集しています。カジュアル面談応募はこちらから: herp.careers/careers/companies/explaza
Claude Skills (Agent Skills) 入門

はじめに

公式リンク集

参考リンク集

Agent Skillsとは

Agent Skillsをゼロから実装してみる

Agent Skillsの構成

`SKILL.md`の構成

Claude Codeからつかってみる

Agent Skillsのベストプラクティス

メタデータの命名規則

`SKILL.md`の行数

参照ファイルの推奨事項

参照したファイルからまた別の参照ファイルを見ることは非推奨

参照ファイルが100行を超える場合は冒頭に目次を設定する

複雑なタスクの実行

まとめ / 感想

Discussion
