CCCMKホールディングス TECH LABの Tech Blog

TECH LABのエンジニアが技術情報を発信しています

ブログタイトル

トップ > AI > Agent Skillsについて調べてまとめてみました。

Agent Skillsについて調べてまとめてみました。

AI Github Copilot 開発環境

はじめに

こんにちは、CCCMKホールディングスAIエンジニアの三浦です。

3月になり、今年度もあと1か月になりました。節目の時は色々と考えることが多くなるな、と感じています。

Claude Code関連の情報で「Agent Skills」というコーディングAgentをカスタマイズする機能をよく目にします。私自身はGithub CopilotユーザーなのでClaude Codeユーザーじゃないと使えないのかな、と思っていたのですが、Agent Skills自体はオープンスタンダードで公開されているため、AIツールが対応していればClaude Code以外でも利用することが出来ます。もちろんGithub CopilotでもAgent Skillsは利用することが可能です。

Github CopilotのAgent Skillsの仕様はVS Codeのこちらのページが参考になりました。

code.visualstudio.com

Claude Codeで使う時と大きな違いはないと思いますが、Skillsの置き場所にログインユーザーごとだと~/.copilot/skills、プロジェクトごとだと.github/skillsを選べるようになっています。

さっそく自分でもSkillsを作ってみよう、と思ったのですが、まずはドキュメントに目を通してみたいと考え、Anthropic社が公開している「The Complete Guide to Building Skills for Claude」というガイドを読んでみました。

https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf?hsLang=en

またClaude API Docsの中に掲載されているAgent SkillsのBest practicesのページも参考になりました。

platform.claude.com

今回はこれらのドキュメントを読んでAgent Skillsについて知ったことをまとめてみたいと思います。

Agent Skillsとは

Agent SkillsはClaudeやGithub Copilotに特定のタスクやワークフローを実行させるための指示やスクリプトをまとめたものです。SkillごとにSkill名を付けたフォルダを配置して必要なファイルを格納して作ることが出来ます。

Github Copilotをカスタマイズする機能として「Custom Instructions」というものがあります。こちらもGithub Copilotに守らせたい指示を指定するものなので最初「おんなじじゃない？」と思いました。

Custom InstructionsとAgent Skillsの大きな違いは、Custom Instructionsが常に読み込まれるのに対し、Agent Skillsは必要な時に読み込まれる、という点にあります。ですのでCustom Instructionsにはプロジェクトに関する作業中に常に守らせたいルール、たとえば使う技術スタックなどを指示し、Agent SkillsにはPRを出すときの手順やルールをまとめておく、といった使い分けをすることが出来ます。

また、ToolやMCPともAgent Skillsは異なります。Agent SkillsはToolやMCPをどのように使ってタスクを実行するのかを指示するもので、個人的にはToolやMCPを調理器具、Agent Skillsを料理のレシピにたとえた説明が分かりやすかったです。

Agent Skillsの構成

「The Complete Guide to Building Skills for Claude」に掲載されているAgent Skillsの構成例を掲載します。

your-skill-name/
├── SKILL.md # Required - main skill file
├── scripts/ # Optional - executable code
│ ├── process_data.py # Example
│ └── validate.sh # Example
├── references/ # Optional - documentation
│ ├── api-guide.md # Example
│ └── examples/ # Example
└── assets/ # Optional - templates, etc.
 └── report-template.md # Example

まずSkillを格納するフォルダ名には命名規則があります。notion-project-setupのようにkebab-case（ケバブケース）を使用します。Notion Project Setupのようにスペースを使う、notion_project_setupのようにアンダースコアを使う、NotionProjectSetupのように大文字を使うのは全て不可とされています。

格納するファイルの中で必ず含めなければならないのがSKILL.mdです。このファイルにSkillの名前や何が出来てどういう時に使うものなのかの説明や、具体的なタスクやワークフローの進め方の指示を記述します。ファイル名には大文字小文字の区別があり、skill.mdやSKILL.MDは不可、必ずSKILL.mdにする必要があります。

SKILL.mdの中でスクリプトを実行する指示を含んでいるときは、スクリプトをscriptsの中に格納します。また文章を作らせる時のテンプレートなどはassetsの中に格納します。最後に特定の条件下でのみ読む必要がある指示や、SKILL.mdが長くなり過ぎたとき(500行以上が目安のようです。)に分割したものをreferencesの中に格納することが出来ます。

SKILL.mdの仕様

SKILL.mdはSkillの名前や説明などを記述するYAML形式のフロントマターとMarkdownの指示本文パートで構成されます。

YAML フロントマター

「The Complete Guide to Building Skills for Claude」に掲載されている最小限の内容を掲載します。

---
name: your-skill-name
description: What it does. Use when user asks to [specific 
phrases].
--

Github Copilotの動作として、最初にSkillsのフロントマター部分だけを読み込み、関連するユーザーの指示があった時にSkillsの指示本文パートが読まれるようになっているようです。なのでこのフロントマターが正しく書かれていないとGithub Copilotが必要な時にSkillを使ってくれなかったり、反対に使わなくていい時に使ってしまう、といった事態につながってしまいます。

nameとdescriptionのフィールドは必須です。nameにはSkillのフォルダ名と一致させる必要があります。また予約語である"claude"と"anthropic"はnameに含めることが出来ません。

Skillの名前の付け方について、Best practicesではSkillが提供する機能を明確にするため動名詞を使うことが推奨されています。たとえばprocessing-pdfsやtesting-codeなどです。一方避けるべきものとして曖昧だったり一般的すぎるhelper, utils, documentsなどが挙げられています。

descriptionはこのSkillが何をするのかといつ使うのかを必ず含め、1,024文字以内にする、XML Tagを含めないといった制限があります。先にも述べたように、この内容を元にGithub CopilotがSkillを使うべきか否かを判断するため、重要なパーツになります。

指示本文パート

Markdown形式で指示を書くパートです。「The Complete Guide to Building Skills for Claude」に掲載されている例を掲載します。

---
name: your-skill
description: [...]
---
# Your Skill Name
# Instructions
### Step 1: [First Major Step]
Clear explanation of what happens.
Example:
```bash
python scripts/fetch_data.py --project-id PROJECT_ID
Expected output: [describe what success looks like]
```

指示の書き方の原則がBest practicesで挙げられていました。この内容がかなり参考になったので、次のセクションでいくつか取り上げてみたいと思います。

指示の書き方の原則

Claudeは十分賢い前提で書くこと

Skill.mdはSkill実行時にコンテキストにロードされるため、冗長になり過ぎずに本当に必要なことを簡潔に書くことが重要です。

そのため、Claudeがすでに知っていると思われることを書くことはただただコンテキストを無駄に消費するだけになってしまいます。

たとえば、PDFからテキストを抽出するSkillを作る場合、以下のような内容は冗長といえます。

## PDF からテキストを抽出する

PDF（Portable Document Format）ファイルは、テキストや画像、
その他のコンテンツを含む一般的なファイル形式です。
PDF からテキストを抽出するには、ライブラリを使用する必要があります。
PDF を処理するライブラリは多数ありますが、pdfplumber は使いやすく、
多くのケースに対応できるため推奨されます。
まず pip を使ってインストールし、その後以下のコードを使用します…

ClaudeはPDFもpdfplumberも知っていて、pdfplumberをインストールするのにpipを使うこともすでに知っているはずだからです。 以下のように簡潔に書くだけでもClaudeは理解することが出来ます。

# PDF からテキストを抽出する

テキスト抽出には pdfplumber を使用します。

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

適切な自由度を設定すること

Skillで実行するタスクやワークフローにどれだけの自由度が許容されるのかを「壊れやすさ」と「ブレ」で評価し、自由度の高さで3タイプに分類してそれぞれ適切なアプローチでSkillを作成していきます。

まず高い自由度の場合です。タスクに対して複数のアプローチが存在し、状況や経験に応じて判断を変える必要があるようなケースが該当します。こういったタイプのタスクではテキスト中心でSkillを記述します。

例えば以下のようになります。

## コードレビュー手順

1. コード構造と設計を分析する
2. 潜在的なバグやエッジケースを確認する
3. 可読性・保守性向上のための改善案を提案する
4. プロジェクト規約への準拠を確認する

次に中程度の自由度の場合です。ドキュメント生成のようなある程度のパターンが決まっていて、ある程度のバリエーションや設定による変動が許容されるようなケースです。この場合は疑似コードを提示したり、スクリプトをパラメータの指定を許容して実行させる指示をSKILL.mdに記述します。

例えば

## レポートを生成する

このテンプレートを使うか、必要に応じて変更して使うこと:

```python
def generate_report(data, format="markdown", include_charts=True):
    # データを処理
    # 指定フォーマットで出力生成
    # 必要に応じて可視化を含める

```

最後は低い自由度の場合です。データベースの移行など、必要な処理を正確な手順で実行しないとタスクの失敗や重大な事態につながるケースです。この場合は作成済みのスクリプトを正確に実行させるようにSkillに記述します。

例えば

## データベースマイグレーション

以下のスクリプトをそのまま正確に実行すること:

```bash
python scripts/migrate.py --verify --backup
```

このコマンドは変更しないでください。また、追加のフラグを付けることも禁止します。

Skillを作る方法

Agent Skillsの概要をつかめてきたところで具体的にどうやって作るのかも知りたくなってきました。

まずSkillを作るためのSkill、skill-creatorというものがあるそうです。こちらはAnthropicのSkillsというレポジトリで公開されています。Skillを作るためのSkillって面白いですね。

github.com

もう一つはBest practicesの「Develop Skills iteratively with Claude」のセクションで述べられている方法なのですが、まずSkillにしたいワークフローやタスクをSkillを使わずにClaudeとやり取りをしながら一通り解決まで進めます。そして一連の作業が完了した後でClaudeにこれまでの流れを踏まえてSkillを生成するように依頼すると、これまでの手順を含んだSkillが生成できる、という方法です。

この方法はClaudeが出来ることを確認しながら進められるので、より実行精度の高いSkillを作ることが出来そうです。

Skillを作ってみる

Best practicesで紹介されていた方法で実際にSkillを作ってみようと思いました。私は実験や検証の用途で月に2, 3個開発用のプロジェクトを立てるのですが、プロジェクトの初期化作業は毎回ある程度やることが決まっているため、これをSkillに出来ないかな、と考えました。

プロジェクトを初期化する時は、大体以下の手順を実行しています。

  • プロジェクト名を決める
  • プロジェクトテンプレートをコピーする
  • プロジェクトに応じて依存関係を調整する
  • Gitの初期化をする

Best Practicesで紹介されているように、まずSkillを使わずにGithub Copilotと会話をしながら上記のフローを進め、プロジェクトの初期化作業を進めてみました。

プロジェクト名を決める

プロジェクト名の最適化

プロジェクトの初期化が完了したら、これまでの一連のやり取りをSkillにしてほしいと依頼しました。

Skill作成を依頼

生成されたSKILL.md

SKILL.mdが生成されたので、ログインユーザーごとのSkill格納場所~/.copilot/skillsにproject-initフォルダを作成し格納し、あとは次のようにGithub Copilotに指示を出すと、Skillを使って初期化作業を進めてくれました。めちゃくちゃ便利・・・！！

Skillを使ってプロジェクトの初期化を開始

とりあえず動くSkillは出来たものの、Best practicesの原則とは少しズレているところもあります。たとえばプロジェクト名はinitializing-projectの方が望ましいですし、SKILL.mdもそれほど複雑なタスクでないのに100行以上あるものが出来てしまいました。今度はSkill作成を依頼する時のプロンプトにもう少し要件を入れて試してみようと思いました。

まとめ

今回はGithub Copilotでも利用できる、Agent Skillsについて調べたことをまとめてみました。Agent Skills自体はフォルダとマークダウンファイルで構成されるとてもシンプルなものですぐに自分で作ってみることが出来ましたし、上手に設計すればかなり複雑なことも実現出来そうだと思いました。作ったAgent Skillsはチーム内の共有資産にするのもよさそうです！