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

Managed AgentsのカスタムSkillを使う3つの経路

Managed AgentsのカスタムSkillは、作業手順や前提知識をまとめたディレクトリ(SKILL.mdと付随ファイル)です。汎用エージェントに渡すと、そのタスクの専門家として振る舞います。エージェントが必要と判断したときに自動で呼び出されるので、プロンプトで毎回指示する必要はありません。

Skillをエージェントに届ける経路は、自分で作るかどうかを含めて3つあります。

後ろの2経路を実装レベルで扱います。SKILL.mdの書き方はAgent Skillsの解説記事、Managed Agents自体の設計はManaged Agentsの設計思想にあります。

Skillを増やすと、指示とメタデータの分だけセッションのコンテキストウィンドウを消費します。マウント数が増えるとサンドボックスの起動も遅くなるため、タスクに必要なものだけを絞って渡します。

Skillをワークスペースに登録する(curlとant apply)

登録の入口は2つあります。Skills APIへ直接アップロードする方法と、ant applyでファイルから宣言的に登録する方法です。どちらも成功すると、エージェントへの添付に使う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に直接アップロードします。

CLIのant applyを使うと、Skillをリポジトリ内のファイルとして管理できます。skills/pr-summary/SKILL.mdのようにルートへSKILL.mdを置いたディレクトリを指定して実行します。公式の例のSKILL.mdは、frontmatterにnameとdescriptionを書き、本文に3つの短い節で手順を書いただけの最小構成です。

ant apply skills/pr-summary

ant applyはディレクトリをアップロードして新しいSkillのIDを表示し、その対応をclaude-lock.jsonに書き込みます。このロックファイルをコミットしておくと、次の実行で編集内容が新しいバージョンとして上がり、同じSkillが二重に作られません。ant applyにはCLIバージョン1.30.0以降が必要です。対話端末では実行前に作成・更新の計画が表示され、承認してから反映されます。--dry-runを付けると、項目ごとの差分を見るだけで何も変更せずに終わります。ロックファイルには、最後に送った内容とAPIが返した内容のハッシュが残ります。これにより、ファイルの編集と、ファイル外で行われたリソースの変更を次の実行で検知できます。

端末のない環境では、ant applyは計画を表示して止まります。続けるには--yesで適用するか、--dry-runで計画だけを見ます。マージ後のデフォルトブランチではant apply --yes .を実行し、プルリクエストでは--dry-run .を使う流れです。--dry-runは、計画がブロックされても終了コード0で終わります。引数なしのant apply --yesは、ロックファイルが追跡済みのファイルだけを反映し、新しく足したファイルは飛ばします。

エージェントのファイルからskills: - ../skills/pr-summaryのように相対パスで参照すると、ant applyが依存順に作成して本物のIDを埋めます。GitHub上のディレクトリ(https://github.com/<owner>/<repo>/tree/<branch>/<dir>)もSkillの参照先に書けます。この場合はコミットに固定され、--upgradeを付けたときだけ取り直されます。プライベートリポジトリを参照するなら、GITHUB_TOKENを設定します。

ファイルを消してもSkill自体は残り、警告が出るだけです。--pruneを付けて初めて削除されます。ファイル名を変えると別のSkillを宣言したことになる点にも注意が要ります。

ファイル外でリソースが編集・アーカイブ・削除されていると、計画はThis plan cannot be applied:で終わります。--forceを付けると、その編集を上書きするか、代わりのリソースを作ります。Consoleで作ったリソースは、ant applyが引き取れません。

Managed Agents APIはmanaged-agents-2026-04-01ベータヘッダーを必要とし、公式SDKは自動で付けます。curlで直接叩くときだけ手で付けます。Skillを添えたセッションでメモリストアも使うときは、メモリストアのエンドポイントだけagent-memory-2026-07-22を使い、併記すると400になります。配布時のバージョン管理はAgent Skillsのエンタープライズ配布で扱っています。

エージェントのskills配列に添付してバージョンを決める

作成したSkillは、エージェント作成時のskills配列に加えて使います。1エントリはtype・skill_id・versionの3フィールドで、typeはプリビルドならanthropic、自作ならcustomです。skill_idはプリビルドがxlsxのような短い名前、自作が作成時に返ったskill_*のIDになります。

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-5",
    "system": "You are a financial analysis agent.",
    "skills": [
      {"type": "anthropic", "skill_id": "xlsx"},
      {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
    ]
  }'

versionは省略でき、省略時はlatestです。固定するときのバージョン表記は、Skillの出どころで形が違います。

本番のエージェントでは、検証前のSkillを巻き込まないようskills配列でバージョンを明示する選択肢があります。ant apply経由で作るエージェントは、適用した時点のバージョンに参照が固定されます。Skillを編集して再度ant applyを実行すると、それを参照するエージェントも同じ実行の中で更新されます。

1つのセッションに添付できるSkillは最大500個です。この数え方は、セッション内の全エージェントを横断して重複を除いた集合に対するものです。単一エージェントの配列だけが対象ではありません。

セッションを作るとき、agentには{"type": "agent_with_overrides", "id": ...}の形でエージェントを渡します。そこへmodel・system・tools・mcp_servers・skillsのいずれかを加えると、そのセッションだけ設定を上書きできます。toolsを空にすると、実効的なskillsが残っている場合は400になります。Skillの読み込みにreadツールが要るためです。

GitHubリポジトリの.claude/skillsを自動検出させる

コードベースの中にSkillを置く経路では、github_repositoryリソースをセッションにマウントします。セッション開始時にリポジトリルートの.claude/skillsがスキャンされ、見つかったSkillの名前・説明・パスがエージェントに見えます。タスクに合うと、エージェントがSKILL.mdと同梱のスクリプトを読みに行きます。

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
)

リソースのフィールドはtype・url・authorization_tokenが必須で、mount_pathとcheckoutは任意です。mount_pathの既定は/workspace/<repo-name>です。checkoutにはブランチかコミットを渡せます。ブランチなら{"type": "branch", "name": "main"}、コミットなら{"type": "commit", "sha": "..."}の形です。省略するとデフォルトブランチになります。

urlはhttps://github.com/<owner>/<repo>の形で、.gitを付けません。SSH形式のURLはinvalid_request_errorで拒否されます。トークンはAPIレスポンスには出てきません。トークンは、必要最小限の権限を持つ細粒度のパーソナルアクセストークンにし、アカウント全体に広い権限を持つものは避けます。プライベートリポジトリのクローンに必要なスコープはrepoです。

検出されるのは、リポジトリルートから見てちょうど.claude/skills/<skill名>/SKILL.mdの位置にあるものだけです。次の配置は検出されません。

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

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

この自動検出はエージェントのreadツールで動きます。readは既定で有効ですが、無効にしたエージェントはリポジトリのSkillを読み込みません。クラウドサンドボックス専用の機能でもあり、セルフホストサンドボックスはGitHubリポジトリリソース自体をサポートしません。

反映のタイミングと同名Skillの扱い

マウントするリポジトリは、resources配列にエントリを足して複数にできます。一度作ったセッションのリポジトリは付け替えられず、変えたいときは新しいセッションを作ります。稼働中のセッションでは、リソースの一覧取得(GET /v1/sessions/{session_id}/resources)と、認可トークンのローテーションができます。

検出されるSkillは、checkoutで指定した状態、指定がなければデフォルトブランチの状態に従います。スキャンはセッション開始時に1回だけです。

同じ名前のSkillが、skills配列の添付とリポジトリ、あるいは別のマウント済みリポジトリの両方にあっても、衝突はしません。どちらも使え、それぞれ自分のパスつきで案内されます。

まとめ

頻繁にコードと一緒に直す手順はリポジトリ読み込みに、複数のエージェントで共有する専門知識はアップロード式に向いています。リポジトリ式を選ぶなら、マウントするリポジトリのコミット権限が、そのままエージェントへの指示権限になる点を先に決めておきます。