Claude Code で Elastic Agent Skills を試す、 Part 2 ローカル接続編

Laptop with a burst of colorful abstract shapes bursting from the screen, overlaid with 'Tech Blog' logo and Japanese title text. BLOG
Saman

サイオステクノロジー株式会社

Saman

Part 1 では、Elastic Agent Skills の概要とインストール方法を紹介しました。

Part 2 では、Claude Code とローカル Elasticsearch を実際につなぐ手順を、ステップバイステップで紹介します。最後まで進むと、自然言語で Elasticsearch にクエリを投げられるようになります。

本記事の手順はすべてローカル環境で実際に動作を確認しています。Elastic Cloud Serverless との接続は Part 3 で紹介します。

検証環境

本記事で使用した環境は以下の通りです。

  • macOS（Apple Silicon、M4）
  • Docker Desktop
  • Elasticsearch 9.3.1（Docker、3ノード構成、セキュリティ有効）
  • Node.js
  • Claude Code v2.1.117

OS や Elasticsearch のバージョンが異なると、パスや挙動が変わる可能性があります。

全体像：接続に必要なもの

Claude Code からローカル Elasticsearch にアクセスするには、3 つのものが必要です。

1. CA 証明書

Docker で起動した Elasticsearch は HTTPS 通信を使っており、自己署名証明書（自分で発行した証明書）が使われています。通常の通信ではブラウザや CLI がこの証明書を信頼しないので、証明書ファイルを取り出して Claude Code に渡す必要があります。

2. .env ファイル

Elasticsearch に接続するには、URL、ユーザー名、パスワード、証明書のパスといった情報が必要です。これを環境変数として一箇所にまとめておくファイルが .env です。

.env を使うメリット：

  • 接続情報を一箇所で管理できる
  • パスワードをコードに書かなくて済む
  • スキルのスクリプトが環境変数を自動で読み込める

3. Agent Skills

Claude Code に Elasticsearch の使い方を教えるスキルです。Part 1 で紹介した通り、npx skills add コマンドでインストールします。

Step 1：プロジェクトフォルダを作る

接続情報と証明書を管理するフォルダを作ります。

mkdir ~/claude_skills
cd ~/claude_skills

このフォルダで Claude Code を起動することが重要です。 Claude Code はスキルを、起動したディレクトリの .claude/skills/ から読み込みます。

Step 2：CA 証明書を取得する

コンテナ名を確認する

まず、Docker コンテナ名を確認します。

docker ps --format "{{.Names}}"

Elasticsearch のコンテナは、利用している Docker Compose やセットアップによって様々な名前になります。例えば次のような名前です：

  • es01
  • deploy_stack-es01-1
  • elasticsearch-master-0
  • elasticsearch

Elasticsearch 関連のコンテナ名をメモしておいてください。 以降の手順で使います。

証明書をコピーする

コンテナ名が確認できたら（本記事では es01 を例にします）、証明書をコピーします。

docker cp es01:/usr/share/elasticsearch/config/certs/ca/ca.crt ./http_ca.crt

証明書の場所は Docker の設定によって異なります。上記のパスで見つからない場合は、以下で探せます。

docker exec es01 find /usr/share/elasticsearch -name "*.crt" 2>/dev/null

Step 3：.env ファイルを作る

~/claude_skills/ フォルダに .env ファイルを作り、接続情報を書きます。

export ELASTICSEARCH_URL=https://localhost:9200
export ELASTICSEARCH_USERNAME=elastic
export ELASTICSEARCH_PASSWORD=<your-password>
export ELASTICSEARCH_CA_CERT=/Users/<username>/claude_skills/http_ca.crt

注意点が 2 つあります

1. 各行の先頭に export を付ける

export がないと、source .env を実行しても環境変数がスキルのスクリプトまで渡りません。後述する「よくあるエラー」の原因になります。

2. ELASTICSEARCH_CA_CERT は絶対パスで書く

./http_ca.crt のような相対パスにすると、スキルが実行されるディレクトリによっては証明書を見つけられません。

Step 4：接続を確認する

.env ファイルが正しく書けているか、curl で確認します。

source ~/claude_skills/.env && curl --cacert "$ELASTICSEARCH_CA_CERT" \
  -u "$ELASTICSEARCH_USERNAME:$ELASTICSEARCH_PASSWORD" \
  "$ELASTICSEARCH_URL/_security/_authenticate"

成功すると、以下のようなレスポンスが返ります。

{
  "username": "elastic",
  "roles": ["superuser"],
  "authentication_type": "realm"
}

Step 5：Agent Skills をインストールする

~/claude_skills/ フォルダで以下のコマンドを実行します。

npx skills add elastic/agent-skills -a claude-code \
  -s elasticsearch-authn \
  -s elasticsearch-esql \
  --yes

フラグの意味

GitHub リポジトリに記載されているフラグの一覧です。

フラグ説明
-a, --agentインストール先のエージェントを指定（例：-a claude-code）
-s, --skillスキル名を指定してインストール（例：-s elasticsearch-esql）
-g, --globalプロジェクトではなくホームディレクトリにインストール
-y, --yes確認プロンプトをスキップ
--all全スキルを全エージェントにインストール
--listインストールせずにスキル一覧を表示

--yes を付けると、「インストールしますか？」という確認が自動的にスキップされます。

出典： elastic/agent-skills GitHub Repository

なぜこの 2 つから始めるのか

GitHub のリポジトリには次のように書かれています。

原文（英語）: “Install the cloud and elasticsearch auth skills — most other skills depend on them — then add only the skills relevant to your workflow.”

日本語訳: cloud スキルと elasticsearch auth スキルをインストールし（多くのスキルがこれらに依存しています）、それからワークフローに関連するスキルだけを追加してください。

まず認証スキルを入れ、その上に必要なスキルを追加していくのが推奨の順序です。

インストール後の確認

スキルは Claude Code を起動したプロジェクトフォルダの .claude/skills/ に配置されます。

ls ~/claude_skills/.claude/skills/
# elasticsearch-authn/  elasticsearch-esql/

Step 6：Claude Code を起動して接続を確認する

.env ファイルと同じフォルダで Claude Code を起動します。

cd ~/claude_skills
claude

起動したら、チャットに入力します。

.env ファイルを読み込んで、Elasticsearch に接続し、利用可能なインデックスの一覧を表示してください。

成功すると、Claude Code がインデックスの一覧を取得して表示します。

Step 7：使用例 1 — ES|QL でデータを分析する

Kibana のサンプルデータを使って、ES|QL クエリを試してみましょう。

Kibana（http://localhost:5601）の「Add data」メニューから eCommerce サンプルデータをまだ追加していない場合は、先に追加してください。

カテゴリ別の売上集計

チャットに入力します。

kibana_sample_data_ecommerce インデックスを使って、
カテゴリ（category）別の売上合計（taxful_total_price）を
高い順に並べた ES|QL クエリを実行してください。

elasticsearch-esql スキルが起動し、インデックスのフィールド構造を確認してから、正しい ES|QL 構文でクエリを生成・実行します。

実行された ES|QL クエリ：

FROM kibana_sample_data_ecommerce
| STATS total_sales = SUM(taxful_total_price) BY category
| SORT total_sales DESC

Step 8：使用例 2 — ログを調査する

次は kibana_sample_data_logs インデックスを使ったログ調査です。Kibana の「Add data」から Logs サンプルデータを追加してから試してください。

まず、observability-logs-search スキルを追加します。

npx skills add elastic/agent-skills -a claude-code \
  -s observability-logs-search --yes

スキル追加後、Claude Code のチャットに入力します。

kibana_sample_data_logs インデックスで、
直近のログから最もバイト転送量が多いリクエストを
上位 5 件表示してください。

Elastic Observability Labs のブログには、このスキルの設計について次のように書かれています。

原文（英語）: “The key shift is that the request is outcome-first. The skill captures implementation details such as API order, field expectations, and verification steps.”

日本語訳: 重要な変化は、リクエストが「結果から始まる」点です。スキルは、API の呼び出し順序、フィールドの期待値、検証ステップなどの実装の詳細をカバーします。

つまり、「どの API を呼ぶか」「どのフィールドを使うか」はスキルが判断します。ユーザーは「何を知りたいか」を自然言語で伝えるだけです。

出典： Elasticsearch Labs — Agent Skills for Elastic Observability

よくあるエラーと解決方法

エラー 1：.env が見つからない

(eval):source:1: no such file or directory: .env

原因： Claude Code が .env を相対パスで探したが、実行時のカレントディレクトリが異なる。

解決方法： .env の読み込みに絶対パスを使う。

source /Users/<username>/claude_skills/.env

または、.env があるフォルダで Claude Code を起動する。

エラー 2：Elasticsearch に接続できない

Set one of these environment variable combinations:
  1. ELASTICSEARCH_CLOUD_ID + ELASTICSEARCH_API_KEY
  2. ELASTICSEARCH_URL + ELASTICSEARCH_API_KEY
  3. ELASTICSEARCH_URL + ELASTICSEARCH_USERNAME + ELASTICSEARCH_PASSWORD

原因： .env ファイルの各行に export が付いていないため、環境変数がスキルのスクリプトに渡されていない。

解決方法： .env の各行の先頭に export を追加する。

# NG
ELASTICSEARCH_URL=https://localhost:9200

# OK
export ELASTICSEARCH_URL=https://localhost:9200

エラー 3：npm パッケージが見つからない

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@elastic/elasticsearch'

原因： スキルの Node.js スクリプトが必要とするパッケージがインストールされていない。

解決方法： スキルのフォルダで npm install を実行する。Claude Code は自動で対処することもあります。

cd .claude/skills/elasticsearch-esql && npm install

互換性についての注意：動かなかった例

現時点では、Agent Skills は Elastic Cloud Serverless との互換性を最大化して設計されています。

原文（英語）: “This initial technical preview release focuses on skills with maximum compatibility for Elastic Cloud Serverless”

日本語訳: この最初のテクニカルプレビューリリースは、Elastic Cloud Serverless との互換性を最大化することに重点を置いています。

出典： Elasticsearch Labs — Agent Skills for Elastic

ローカル Elasticsearch 9.x では、一部のスキルが動作しない場合があります。本記事の検証でも実際にエラーが発生したので、共有します。

実例：kibana-dashboards スキル

以下のコマンドで kibana-dashboards スキルをインストールし、Claude Code に Kibana ダッシュボードの作成を依頼しました。

npx skills add elastic/agent-skills -a claude-code \
  -s kibana-dashboards --yes

ダッシュボード作成を依頼すると、以下のエラーが発生しました：

Error: Invalid version number. Received "2023-10-31",
expected a string containing _only_ a finite, whole number greater than 0.

スキルのスクリプトが、バージョン番号として "2023-10-31"（日付形式）を送信していますが、Elasticsearch 9.x は整数のバージョン番号を期待しています。

この挙動はローカルの Elasticsearch 9.x 特有のもので、Elastic Cloud Serverless では動作する可能性があります。 Part 3 で Serverless での検証結果を紹介します。

スキルを追加する

ワークフローに合わせて、後からスキルを追加できます。

npx skills add elastic/agent-skills -a claude-code \
  -s <スキル名> --yes

インストール済みのスキルを確認するには：

npx skills list

スキルを追加した後、Claude Code の再起動は不要です。スキルはチャットから自然言語で依頼するだけで、自動的に読み込まれます。

出典： Elastic 公式ドキュメント — AI agent skills for Elastic

まとめ

本記事では、ローカル Elasticsearch と Claude Code をつなぐ手順を、実際に動作確認しながら紹介しました。

接続に必要なもの

項目内容
CA 証明書Elasticsearch の HTTPS 通信を信頼するために必要（Docker コンテナから docker cp で取得）
.env ファイル4 つの環境変数（export 付き、絶対パス）
起動場所.env と同じフォルダで Claude Code を起動

スキルの場所

起動したフォルダの .claude/skills/（プロジェクトローカル）

動作確認できたスキル

  • elasticsearch-authn：認証
  • elasticsearch-esql：ES|QL クエリ
  • observability-logs-search：ログ調査

動作しなかったスキル（ローカル Elasticsearch 9.x）

  • kibana-dashboards：バージョン番号の互換性エラー

Part 3 では：Elastic Cloud Serverless を使って、ローカルで動かなかったスキルを含む、より幅広い検証結果を紹介します。

MCP Apps を使った Elasticsearch との連携方法を紹介します。お楽しみに！

参考資料

Elastic 公式ドキュメント

Elasticsearch Labs ブログ

GitHub リポジトリ