はじめに

Claude Desktopでskill-creatorを使いながら、新しく登場した「Agent Skills」という機能を試してみました。この機能は、従来のプロンプトエンジニアリングとは異なるアプローチで、AIエージェントの振る舞いをより確実にコントロールできる可能性を感じさせるものです。

本記事では、実際にSkillsを作成・使用した経験を基に、この技術の仕組みと実用性について詳しく紹介します。

なお、この記事自体も自作のカスタムスキルを使用して執筆しています。Agent Skillsがどのように実践的な成果を生み出すのか、記事全体を通じて体感していただければと思います。

Agent Skillsについて

概要と特徴

Agent Skillsは、Claudeの能力を拡張するモジュール式の知識パッケージです。特定のドメインやタスクに特化した知識、ワークフロー、ツールを提供することで、汎用的なAIエージェントを専門的なエージェントに変換します。

公式のskill-creatorのドキュメントでは、Skillsを「onboarding guides（オンボーディングガイド）」と表現しています。これは的確な表現で、まさに新しいプロジェクトに参加した開発者に必要な情報をまとめて提供するような役割を果たします。

既存のプロンプトエンジニアリングとの違い

従来のプロンプトエンジニアリングでは：

  • 毎回同じような指示を繰り返す必要がある
  • 複雑なタスクでは長大なプロンプトが必要
  • 出力の品質や形式にばらつきが生じやすい
  • 特定のワークフローを再現するのが困難

Agent Skillsでは：

  • 再利用可能な知識とワークフローのパッケージ化
  • 決定論的なスクリプトとの組み合わせ
  • 段階的な情報開示による効率的なコンテキスト管理
  • 一貫性のあるアウトプットの実現

Skillの構造と仕組み

ディレクトリ構成

Skillは以下のような構造を持ちます：

skill-name/
├── SKILL.md (必須)
│   ├── YAMLフロントマター（メタデータ）
│   │   ├── name: スキル名
│   │   └── description: 説明（いつ使うか）
│   └── Markdown本文（使用方法の指示）
└── バンドルリソース（オプション）
    ├── scripts/      実行可能コード
    ├── references/   参照ドキュメント
    └── assets/       出力用ファイル

Progressive Disclosure（段階的情報開示）の仕組み

Skillsは3段階のローディングシステムを採用しています：

  1. メタデータ（name + description） – 常にコンテキスト内（約100トークン）
  2. SKILL.md本文 – Skillがトリガーされた時（5kトークン未満推奨）
  3. バンドルリソース – 必要に応じてロード（サイズ制限なし）

この設計により、コンテキストウィンドウを効率的に活用できます。

Skillsの作成方法

Claudeとの対話による自動作成（skill-creator使用）

Claudeとの対話の中でskill-creatorを使うことで、必要なSkillを自動的に生成してもらうことができます。以下は、Claudeが実行するプロセスです：

Step 1: Skillの理解と具体例の収集

まず、どのような場面でSkillが使われるかを明確にします。例えば「PDFエディター」のSkillを作る場合：

- 「このPDFを回転させて」
- 「PDFの特定のページを抽出して」
- 「複数のPDFを結合して」

このような具体的なユースケースを集めます。

Step 2: 再利用可能なコンテンツの計画

各ユースケースを分析し、必要なリソースを特定：

  • scripts/: 毎回同じコードを書く作業 → rotate_pdf.py
  • references/: API仕様や使用方法 → pdf_api.md
  • assets/: テンプレートやサンプル → template.pdf

Step 3: Skillの初期化

# init_skill.pyを使用して新しいSkillを作成
scripts/init_skill.py my-pdf-editor --path ./skills

これにより、必要な構造を持つディレクトリが自動生成されます。

Step 4: SKILL.mdの作成と編集

SKILL.mdは、他のClaude インスタンスが読むドキュメントとして作成します。重要なポイント：

フロントマター

---
name: pdf-editor
description: Edit PDF files including rotation, extraction, merging, and form filling. Use when users need to manipulate PDF documents, extract pages, combine multiple PDFs, or fill out PDF forms.
---

descriptionは、100以上あるSkillsの中から適切に選択されるよう、具体的かつ包括的に記述します。

本文の構成例

# PDF Editor

## Quick Start

Rotate a PDF:
```python
from scripts import rotate_pdf
rotate_pdf.rotate("input.pdf", angle=90)
```

## Advanced Features

- **Form filling**: See references/forms.md for complete guide
- **Batch processing**: See references/batch.md for automation patterns

Step 5: スクリプトの実装とテスト

# scripts/rotate_pdf.py
def rotate(input_path, angle):
    """Rotate PDF by specified angle"""
    # 実装コード
    pass

作成したスクリプトは必ず実行してテストします。

Step 6: パッケージング

# .skillファイルの作成
scripts/package_skill.py ./skills/my-pdf-editor

# 出力: my-pdf-editor.skill

パッケージングスクリプトは自動的にバリデーションを実行し、問題がなければ.skillファイル（実体はzipファイル）を生成します。

手動でのSkill作成

skill-creatorを使わずに、手動でSkillを作成することも可能です：

  1. ディレクトリ構造の作成
mkdir my-skill
cd my-skill
# SKILL.md作成
# 必要に応じてscripts/, references/, assets/ディレクトリを追加
  1. SKILL.mdの作成
---
name: my-skill
description: スキルの説明
---

# スキル名

## 使用方法
...
  1. .skillファイルの作成
# ディレクトリをzipファイルとして圧縮
zip -r my-skill.skill my-skill/

.skillファイルは実質的にzipファイルなので、手動で圧縮しても同じように使用できます。

Agent Skillsの利用環境と配置方法

2025年10月現在、Agent Skillsは複数の環境で利用可能です。それぞれの環境での特徴と配置方法を整理します。

Claude.ai（Webブラウザ版）

利用可能プラン

  • Claude Pro、Max、Team、Enterprise
  • TeamとEnterpriseでは管理者による事前の有効化が必要

設定と利用方法

  1. 設定画面で有効化

    • 設定 → Capabilities → 「Code execution and file creation」を有効化
    • Anthropic提供のスキル（xlsx、pptx、docx、pdf）は自動的に利用可能

  2. カスタムスキルのアップロード

    # ZIPファイルとしてアップロード
# スキルフォルダがZIPのルートになるように注意
my-skill.zip/my-skill/SKILL.md  # 正しい構造

  3. skill-creatorを使った対話的作成

    • 設定でskill-creatorスキルを有効化
    • チャットで「I want to create a skill for [用途]」と入力
    • Claudeが対話的にガイドしてスキル作成を支援

⚠️ 重要な制限: Claude.aiにアップロードしたスキルは個人のみ利用可能で、チーム共有はできません

Claude Desktop（デスクトップアプリ）

プラットフォームサポート

  • macOS: Intel/Apple Silicon（macOS 12+推奨）
  • Windows: x64/ARM64（Windows 10/11）
  • Linux: 非公式コミュニティビルドのみ

デスクトップ特有の機能

  • MCPサーバー統合: ローカルファイル、データベース、アプリケーションとの連携
  • キーボードショートカット: Option + Space（Mac）、Ctrl + Alt + Space（Windows）
  • バックグラウンド動作: 即座にアクセス可能

スキル管理

Claude.aiと同じWeb UIを使用するため、スキル管理方法は同一です。

Claude Code（CLIツール）

インストールと設定

# インストール
npm install -g @anthropic-ai/claude-code

# APIキー設定（推奨）
export ANTHROPIC_API_KEY="your-api-key-here"

# または ~/.bashrc に追加
echo 'export ANTHROPIC_API_KEY="your-api-key"' >> ~/.bashrc
source ~/.bashrc

スキルの配置場所

個人用スキル（全プロジェクトで利用）:

~/.claude/skills/
├── my-skill/
│   ├── SKILL.md
│   ├── scripts/
│   └── resources/

プロジェクト用スキル（Gitで共有）:

.claude/skills/
├── team-skill/
│   ├── SKILL.md
│   └── scripts/

プラグインマーケットプレースの利用

Claude Codeでは、コミュニティが提供するスキルをプラグインとしてインストールすることも可能です：

# Claude Code内で実行
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

インストール後は、スキル名を明示的に指定して使用します：

# 例: PDFスキルを使用
"Use the PDF skill to extract the form fields from path/to/file.pdf"

この方法により、GitHubなどで公開されているコミュニティスキルを簡単に導入できます。

チーム開発のベストプラクティス

# プロジェクトスキルの作成
mkdir -p .claude/skills/code-review
cat > .claude/skills/code-review/SKILL.md << 'EOF'
---
name: code-review
description: コードレビューの自動化
---

# Code Review Skill
## 使用方法
...
EOF

# Gitで共有
git add .claude/skills/
git commit -m "Add code review skill"
git push

注意: Claude Codeでは専用のCLIコマンドはなく、ファイルシステムベースで管理します

Claude API（開発者向け）

基本的な使用方法

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02"
    ],
    container={
        "skills": [
            {
                "type": "anthropic",  # Anthropic提供
                "skill_id": "xlsx",
                "version": "latest"
            },
            {
                "type": "custom",     # カスタムスキル
                "skill_id": "skill_01AbCd...",
                "version": "latest"
            }
        ]
    },
    messages=[{"role": "user", "content": "売上データを分析"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

カスタムスキルのアップロード

# スキルをAPIにアップロード
skill = client.beta.skills.create(
    display_title="Sales Analyzer",
    files=[
        ("skill/SKILL.md", open("skill/SKILL.md", "rb")),
        ("skill/analyze.py", open("skill/analyze.py", "rb"))
    ],
    betas=["skills-2025-10-02"]
)

print(f"Skill ID: {skill.id}")

APIの利点

  • ワークスペース全体で共有: 組織内の全メンバーが利用可能
  • 完全なバージョン管理: プログラマティックな管理
  • 本番環境対応: CI/CD統合、自動化パイプライン

プラットフォーム別の特徴比較

機能 Claude.ai Claude Desktop Claude Code Claude API
Anthropic提供スキル ✅ 4種類 ✅ 4種類 ❌ なし ✅ 4種類
カスタムスキル ✅ ZIPアップロード ✅ ZIPアップロード ✅ ファイルシステム ✅ APIエンドポイント
共有方法 個人のみ 個人のみ Gitベース ワークスペース全体
管理方法 GUI設定 GUI設定 ファイルシステム プログラマティック
バージョン管理 ❌ ❌ ✅ Git ✅ 完全なAPI
最適な用途 対話的作成 クイックアクセス+MCP 開発ワークフロー 自動化・本番環境

Claude Codeにおける組み込みスキルの現状

⚠️ 重要な補足: 比較表に記載の通り、Claude Codeでは現在Anthropic提供の4つの組み込みスキル（docx、xlsx、pptx、pdf）が標準では利用できません。

しかし、コミュニティによる解決策が存在します：

  • tfriedel/claude-office-skillsなどのサードパーティリポジトリが、これらのスキルをClaude Codeで使用可能な形式で提供しています
  • これらは公式のスキルと同等の機能を提供し、手動でインストールすることで利用可能になります

スキル配置のベストプラクティス

開発フロー

  1. 開発: Claude CodeまたはClaude.aiのskill-creatorで作成
  2. テスト: 個人環境でテスト
  3. 共有:
    • チーム開発: .claude/skills/にコミット（Claude Code）
    • エンタープライズ: API経由でワークスペースにアップロード
    • 個人利用: ZIPファイルとして配布

セキュリティの考慮事項

  • 信頼できるソースからのスキルのみ使用
  • スキルのすべてのファイルを監査してから有効化
  • 機密情報はハードコードしない
  • 外部URLを参照するスキルは特にリスクが高い

⚠️ 重要: カスタムスキルはプラットフォーム間で同期されません。各環境に個別にアップロード/配置する必要があります。

Skillsの共有と配布

Agent Skillsの大きな利点の一つは、簡単に共有できることです：

共有の方法

  1. .skillファイルとしての配布

    • 単一のファイルとして簡単に共有
    • メール、Slack、GitHub等で配布可能
    • バージョン管理も容易

  2. チーム内での標準化

    • 企業固有のビジネスロジックをSkillとして標準化
    • 新メンバーのオンボーディングを効率化
    • 品質とプロセスの統一

  3. コミュニティでの共有

    • オープンソースとしての公開
    • Skillsのマーケットプレイス形成の可能性
    • ベストプラクティスの共有

詳細は公式ドキュメントを参照してください。

実際に使ってみて良かった点

1. 再現性の高さ

一度作成したSkillは、誰が使っても同じような品質のアウトプットを生成します。これは特に：

  • チーム開発での知識共有
  • 複雑なワークフローの標準化
  • 品質保証が重要なタスク

において大きな利点です。

2. コンテキストウィンドウの効率的な利用

Progressive Disclosureにより、必要な情報だけを必要なタイミングでロードするため、より大規模なプロジェクトにも対応可能です。

3. 決定論的な処理との組み合わせ

スクリプトによる確実な処理と、AIの柔軟な判断を組み合わせることで、より実用的なソリューションが構築できます。

気になった点と今後の課題

1. Skill作成の初期コスト

良いSkillを作るには、事前の設計と実装が必要です。単発のタスクには向かない場合があります。

2. バージョン管理

Skillsのアップデートや互換性管理の仕組みが今後重要になってくるでしょう。

3. Skill間の依存関係

複数のSkillsを組み合わせる際の依存関係管理が課題になる可能性があります。

どんな場面で使えそうか

最適なユースケース

  • 定型業務の自動化: 毎日行う報告書作成、データ処理など
  • ドメイン特化型の開発: 企業固有のビジネスロジックや規約に基づく開発
  • 品質重視のコンテンツ生成: ブランドガイドラインに沿った文書作成
  • 複雑なワークフロー: 複数のステップを含む処理の標準化

向いていないケース

  • 単発の簡単なタスク
  • 創造性が重要な作業
  • 頻繁に要件が変わるプロジェクト

プロンプトエンジニアリングからの転換期として

Agent Skillsの登場は、AI活用における重要な転換点だと感じています。

従来のプロンプトエンジニアリング

  • アート的側面: 効果的なプロンプトの作成は職人技
  • 不確実性: 同じプロンプトでも出力にばらつき
  • 暗黙知: ノウハウが属人化しやすい

Agent Skillsによるアプローチ

  • エンジニアリング的側面: 設計、実装、テスト、デプロイのサイクル
  • 予測可能性: 一貫性のあるアウトプット
  • 形式知化: 知識とワークフローの明文化

この転換は、AIを「魔法の箱」から「信頼できるツール」へと進化させる重要なステップです。不確実性を減らし、一定のアウトプットを担保するという点で、エンタープライズ環境でのAI活用において特に重要な意味を持つでしょう。

まとめ

Agent Skillsは、AIエージェントの能力を拡張し、より予測可能で管理しやすくする革新的な仕組みです。

主なポイント：

  1. モジュール式の知識パッケージにより、再利用可能な専門知識を提供
  2. Progressive Disclosureにより、効率的なコンテキスト管理を実現
  3. スクリプトとの組み合わせで、決定論的な処理と柔軟性を両立
  4. skill-creatorにより、構造化されたSkill開発が可能
  5. プロンプトエンジニアリングからの進化として、より工学的なアプローチを提供

今後、より多くのSkillsが共有され、エコシステムが形成されることで、AI活用の新しい標準となる可能性を秘めています。

特に、チーム開発や企業での活用において、知識の共有と標準化、品質の担保という観点から、Agent Skillsは重要な役割を果たすことになるでしょう。

参考リンク

公式ドキュメント

GitHub リポジトリ



ギャップロを運営しているアップフロンティア株式会社では、一緒に働いてくれる仲間を随時、募集しています。 興味がある！一緒に働いてみたい！という方は下記よりご応募お待ちしております。
採用情報をみる