Claude Media
Managed AgentsにカスタムSkillを追加する方法 — GitHubリポジトリからの自動読み込みも
AnthropicAgent SDKチュートリアル

Managed AgentsにカスタムSkillを追加する方法 — GitHubリポジトリからの自動読み込みも

Managed AgentsのカスタムSkill作成からエージェントへの添付、GitHubリポジトリの.claude/skillsを自動検出させる設定までを一次ソースの仕様で解説します。

読了目安 約15分

Managed AgentsのカスタムSkillとは何か

Managed AgentsのカスタムSkillは、エージェントにドメイン固有の専門知識を持たせるファイルシステムベースのリソースです。作業手順・前提知識・ベストプラクティスをまとめたディレクトリを用意すると、汎用エージェントがそのタスクの専門家として振る舞うようになります。

Skillには2種類あります。プリビルドSkillはPowerPoint・Excel・Word・PDFなどの文書操作(pptx / xlsx / docx / pdf)を担い、どのワークスペースでもそのまま使えます(標準Skillの一覧を参照)。カスタムSkillは自分で作成してワークスペースにアップロードするものです。どちらもエージェントが必要と判断したタイミングで自動的に呼び出します。

Skillをエージェントに届ける方法も2通りあります。ひとつはエージェントのskills配列に明示的にアタッチする方法、もうひとつはGitHubリポジトリをセッションにマウントし、リポジトリ側の.claude/skillsディレクトリから自動検出させる方法です。本記事はこの2経路を実装レベルで扱います。SKILL.mdの書式そのものの作り方はAgent Skillsの解説記事に譲ります。

Managed Agents自体のセッション・ハーネス・サンドボックス分離の設計はManaged Agentsの設計思想にまとめてあります。

Skillを1つ追加するたびにセッションのコンテキストウィンドウにわずかなコストがかかります。指示とメタデータがモデルに読み込まれるためで、エージェントが本当に必要とするSkillだけを絞ってアタッチするのが基本方針です。

カスタムSkillを作成してワークスペースにアップロードする

カスタムSkillはSKILL.mdファイルと付随ファイルを含むディレクトリで、zipアーカイブまたは個別ファイル群としてワークスペースにアップロードします。作成に成功すると、エージェントへのアタッチ時に参照するskill_*形式のIDが返ります。

curl -X POST "https://api.anthropic.com/v1/skills" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F "files[]=@example_skill.zip"

display_nameを省略すると、SKILL.md内のnameフィールドから表示名が自動的に決まります。明示的に指定する場合は255字まで許容され、ワークスペース内でユニークである必要はありません。Skillのバンドルは通常のFiles APIではなく、Skills APIに直接アップロードします。作成後のSkillは一覧・取得・削除・バージョン管理が可能で、ant skills createのようなCLIコマンドからも同じ操作ができます。

Skillの作成・アタッチを含むManaged Agents API全般はmanaged-agents-2026-04-01ベータヘッダーを必要とします(メモリストア関連のエンドポイントだけは別のヘッダーを使う例外です)。公式SDKを使う場合はこのヘッダーを自動で付与するため、curlで直接叩く場合にだけ意識すれば足ります。組織でカスタムSkillを配布する際のバージョン管理・リスク階層評価はAgent Skillsのエンタープライズ配布で扱っています。

作成のレスポンスにはlatest_version_idが含まれます。カスタムSkillを更新しても既存のエージェントが即座に新しい挙動へ切り替わるわけではありません。エージェントのskills配列で特定のversionを指定していれば、新しいバージョンをアップロードしたあともそのエージェントは指定した版のまま動き続け、latestを指定している場合だけ次回セッションから新しい版が使われます。動作確認前のSkillを本番エージェントに影響させたくない場合は、検証用エージェントでversionを明示的に固定してから切り替えるのが安全です。

プリビルドSkillはワークスペース作成時点ですでに使える状態になっており、この作成手順自体が不要です。プリビルドSkillだけを使うなら、次の「Agentのskills配列にアタッチする」までスキップできます。

Agentのskills配列にアタッチする

作成したカスタムSkillをエージェントに使わせるには、エージェント作成時のskills配列にエントリを追加します。各エントリは次の3フィールドで構成されます。

フィールド説明
type説明プリビルドSkillはanthropic、ワークスペース作成のカスタムSkillはcustom
skill_id説明プリビルドは短い名前(例xlsx)、カスタムは作成時に返ったskill_*ID
version説明特定バージョンに固定するかlatestを指定。省略時はlatest
curl -X POST https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  --json '{
    "name": "Financial Analyst",
    "model": "claude-opus-5",
    "system": "You are a financial analysis agent.",
    "skills": [
      {"type": "anthropic", "skill_id": "xlsx"},
      {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
    ]
  }'

1つのセッションでアタッチできるSkillは最大500個です。これはセッション内の全エージェントを横断して重複排除した集合に対する上限で、単一エージェントのskills配列だけの話ではありません。マウントするSkillが増えるほどセッションのサンドボックス起動が遅くなるため、そのエージェントのタスクに実際に必要なSkillだけを絞るのが公式の推奨です。

GitHubリポジトリから直接読み込ませる

Skillはコードベースの中に置くこともできます。github_repositoryリソースをセッションにマウントすると、リポジトリのルートにあるディレクトリがセッション開始時にスキャンされ、見つかったSkillがそのままエージェントから使えるようになります。事前のアップロードも、エージェントの配列への登録も不要です。

session_id=$(curl -fsS https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<JSON | jq -r '.id'
{
  "agent": "$agent_id",
  "environment_id": "$environment_id",
  "resources": [
    {
      "type": "github_repository",
      "url": "https://github.com/org/repo",
      "mount_path": "/workspace/repo",
      "authorization_token": "ghp_your_github_token"
    }
  ]
}
JSON
)

mount_pathは省略可能で、デフォルトは/workspace/<repo-name>です。プライベートリポジトリではauthorization_tokenにそのリポジトリへのアクセス権が必要です。

検出されるのは、リポジトリルートから見てちょうど.claude/skills/<skill名>/SKILL.mdという1階層下の配置だけです。次のような配置は検出されません。

  • .claude/skills/SKILL.md(Skill専用ディレクトリで囲まれていない)
  • .claude/skills/tools/code-review/SKILL.md(1階層より深い)
  • skills/code-review/SKILL.md(.claudeの外にあるskillsディレクトリ)

パッケージのサブディレクトリなど、リポジトリの別の場所にある.claude/skillsはセッション開始時のアナウンスには含まれませんが、エージェントがそのサブツリー配下のファイルを読んだ際に見つかることはあります。

この自動検出はエージェントのreadツールを使って行われます。readツールはデフォルトで有効ですが、無効化しているエージェントはリポジトリのSkillを読み込みません。またこの検出はクラウドサンドボックスでのみ動作し、セルフホストサンドボックスはGitHubリポジトリリソース自体をサポートしません。

発見されるSkillは、リソース設定でcheckoutブランチやコミットを指定していればその状態、指定がなければリポジトリのデフォルトブランチの状態に従います。スキャンはセッション開始時に1回だけ実行され、セッション中に追加されたコミットは反映されません。更新後のSkillを読み込ませたい場合は新しいセッションを開始します。

使い分けとよくあるつまずき

プリビルド・アップロード式カスタム・リポジトリ読み込みの3経路は、更新の頻度と管理主体で選び分けます。

経路向いている場面更新の反映
プリビルドSkill向いている場面文書操作など汎用タスク更新の反映Anthropicが管理、設定不要
アップロード式カスタムSkill向いている場面ワークスペース横断で共有する専門知識更新の反映Skills API経由で明示的に再アップロード・バージョン更新
GitHubリポジトリ読み込み向いている場面コードベースと一緒にバージョン管理したい手順更新の反映リポジトリへのコミット。ただし新しいセッションを開始するまで反映されない

つまずきやすい点は次の4つです。

  • ディレクトリ階層を1つでも間違えると(ネストしすぎ、.claudeの外に置く)そのSkillはセッション開始時のアナウンスに乗らず、エージェントが自発的にファイルを読まない限り気づかれません
  • セルフホストサンドボックスではGitHubリポジトリ経由のSkill読み込みがそもそも成立しません。この構成を検討している場合は先にサンドボックスの種類を確認します
  • 外部コントリビューションを受け付けるリポジトリをそのままマウントすると、レビューなしでエージェントの実行力を持つ指示が追加される経路になります
  • リポジトリ側でSkillを更新しても、稼働中のセッションには反映されません。動作確認は必ず新しいセッションで行います

リポジトリ読み込みで見つかったSkillと、skills配列でアタッチしたSkillは共存できます。名前が同じSkillが両方の経路にあっても、それぞれ別のパスとして案内されるため両方使えます。

まとめ

Managed AgentsのカスタムSkillは、Skills APIへのアップロードとskills配列への登録という明示的な経路に加えて、GitHubリポジトリの.claude/skillsをセッション開始時に自動検出させる経路を持ちます。頻繁にコードと一緒に更新したい手順はリポジトリ読み込みに、ワークスペース横断で共有したい専門知識はアップロード式カスタムSkillに向いています。いずれの経路でも、セッションあたり最大500Skillという上限と、リポジトリマウントが信頼境界を広げるという2点は設計前に確認しておく価値があります。

この記事を共有:XはてブLinkedIn

関連する記事

Anthropic をもっと見る →