はじめに
以前も書いてましたが、AgentCore ハーネスがGAになったので、改めて書いてみます。
今回はS3 FilesのSkillsを使ってみます。
skillsの使い方
ここがこの記事を書こうと思ったきっかけです。タイトルの「S3 Files に配置した Skills をマウント」をそのまま実現しようとすると、実は 2つの別機能が絡みます。
道①：S3 skill source（かんたん・VPC不要）
ふつうの S3 バケットにスキルを置いて、s3://... の URI を指定するだけ。
response = client.invoke_harness(
harnessArn=HARNESS_ARN,
runtimeSessionId=SESSION_ID,
skills=[
{"s3": {"uri": "s3://my-skills-bucket/skills/company-style/"}},
],
messages=[{"role": "user", "content": [{"text": "スタイルガイドに従って要約して"}]}],
)
- 実行ロールに
s3:GetObjectとs3:ListBucketがあればOK - VPC は不要（S3 VPC エンドポイント経由でも動く）
- スキル1個あたり 1GB 以下
👉 「とにかく S3 のスキルを使いたい」だけなら、こっちが正解。 圧倒的に簡単です。
道②：S3 Files をファイルシステムとして /mnt にマウント（本記事の主役）
一方、タイトルにある「S3 Files」は、Amazon のファイルシステムサービスです。これを使うと、
- S3 Files のアクセスポイントを
/mnt/...にマウントできる - マウントパスのファイルは、裏側の S3 バケットと 双方向に同期される
- ただし VPC が必須
つまり「マウント」という言葉が正しく当てはまるのはこちらです。
そして「マウントした S3 Files の中に置いた Skill を使う」には、上の表の ④ Path（ファイルシステム）ソース を組み合わせます。
S3 Files をマウント（/mnt/s3data）
↓
その中に Skill を配置（/mnt/s3data/skills/my-skill/SKILL.md）
↓
Path ソースで参照（{"path": "/mnt/s3data/skills/my-skill"}）
これがタイトルどおりの構成です。**①より手間はかかりますが、「S3 のデータを丸ごとファイルシステムとして扱い、その一部をスキルとしても使う」**という、より柔軟なことができます。
⚠️ どちらを選ぶ？
- スキルを配るだけ → 道①（S3 skill source）
- S3 のデータをエージェントの作業ディレクトリとして使いつつ、その中のスキルも使いたい → 道②（S3 Files マウント + path skill）
この記事では学習目的で 道② をメインに解説します。
ハンズオン：S3 Files をマウントして、その中の Skill を使う
全体像
┌─────────────────────────────────────────────┐
│ AgentCore Managed Harness（microVM） │
│ │
│ /mnt/s3data/ ←── マウント ──┐ │
│ └ skills/my-skill/ │ │
│ └ SKILL.md │ 双方向同期 │
│ │ │
│ path skill として参照 ───────┘ │
└────────────────────────────────┼──────────────┘
│
┌────────▼────────┐
│ Amazon S3 Files │
│ (access point) │
│ ＋ 裏側のS3バケット│
└──────────────────┘
前提・準備するもの
道②は VPC が必須なので、準備物がやや多めです。
- AgentCore が GA 提供されているリージョン（対応リージョン一覧）
- VPC（サブネット2つ + セキュリティグループ1つ程度）
- S3 Files のファイルシステム + アクセスポイント
- ハーネス用の 実行ロール（execution role）
- AgentCore CLI（
agentcoreコマンド）
🛠️ VPC・S3 Files・IAM の前提条件（ネットワーク・権限・セキュリティグループ）は、ハーネスと Runtime で共通です。詳細は公式の File system configurations for AgentCore Runtime を参照してください。
ステップ1：Skill を作る
まずは簡単な SKILL.md を1枚作ります。例として「社内のリリースノートを書くスキル」を作ってみます。
---
name: release-note-writer
description: 社内ルールに沿ったリリースノートを日本語で作成する。バージョン番号、変更点、影響範囲を必ず含める。
---
# リリースノート作成スキル
以下のフォーマットでリリースノートを書いてください。
## 出力フォーマット
- **バージョン**: vX.Y.Z
- **リリース日**: YYYY-MM-DD
- **変更点**: 箇条書き（ユーザー視点で）
- **影響範囲**: 影響を受ける機能・利用者
- **移行手順**: 必要な場合のみ
## ルール
- 専門用語には必ず1行の補足をつける
- 破壊的変更には ⚠️ を付ける
ステップ2：S3 Files のバックエンドバケットに Skill を置く
S3 Files のアクセスポイントは、裏側の S3 バケットと同期します。なので、裏側のバケットにスキルを置けば、マウント先にも現れます。
# 裏側のS3バケットにスキルをアップロード
aws s3 cp ./release-note-writer/SKILL.md \
s3://my-s3files-backing-bucket/skills/release-note-writer/SKILL.md
マウント経由で書き込んでも、S3 と双方向同期されるので結果は同じです。今回は分かりやすさ優先で、先に S3 へ置いておきます。
ステップ3：ハーネスに S3 Files をマウントする
agentcore CLI でハーネスを作り、S3 Files アクセスポイントをマウントします。S3 Files のマウントには VPC モードが必須なので、サブネットとセキュリティグループも一緒に渡します。
agentcore add harness --name data-agent \
--network-mode VPC \
--subnets subnet-abc123,subnet-def456 \
--security-groups sg-abc123 \
--s3-access-point arn:aws:s3files:us-west-2:123456789012:file-system/fs-0123456789abcdef0/access-point/fsap-0123456789abcdef0:/mnt/s3data
agentcore deploy
CLI ではなく API（CloudFormation や SDK）で作る場合は、次のような JSON になります。
aws bedrock-agentcore-control create-harness \
--harness-name "DataAgent" \
--execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
--environment '{
"agentCoreRuntimeEnvironment": {
"networkConfiguration": {
"networkMode": "VPC",
"networkModeConfig": {
"subnets": ["subnet-abc123", "subnet-def456"],
"securityGroups": ["sg-abc123"]
}
},
"filesystemConfigurations": [
{
"s3FilesAccessPoint": {
"accessPointArn": "arn:aws:s3files:us-west-2:123456789012:file-system/fs-0123456789abcdef0/access-point/fsap-0123456789abcdef0",
"mountPath": "/mnt/s3data"
}
}
]
}
}'
📌 ハマりポイント：ARN にコロンが含まれる
S3 Files のアクセスポイント ARN 自体に:が含まれます。CLI の--s3-access-pointでは、最後のコロンより後ろがマウントパスとして解釈されます。📌 マウントパスは
/mnt配下のみ。S3 Files マウントは最大2個まで指定できます。
ステップ4：マウントできているか確認する
エージェントのループを通さずに、直接シェルコマンドを実行して中身を確認できます。これが InvokeAgentRuntimeCommand（CLI なら --exec）です。モデルを介さないので、トークン課金もありません。
agentcore invoke --exec --harness data-agent --session-id "$(uuidgen)" \
"ls -la /mnt/s3data/skills/release-note-writer"
SKILL.md が見えていればマウント成功です 🎉
ステップ5：Path ソースで Skill を参照して呼び出す
マウントしたパスを path スキルソースとして渡します。
response = client.invoke_harness(
harnessArn=HARNESS_ARN,
runtimeSessionId=SESSION_ID,
skills=[
{"path": "/mnt/s3data/skills/release-note-writer"},
],
messages=[{"role": "user", "content": [{"text": "v2.0.0 のリリースノートを書いて。認証方式をCognitoに変更した。"}]}],
)
ℹ️ 公式ドキュメントの
pathスキルの例は.agents/skills/xlsxのような相対パスで書かれています（コンテナにバイクインしたケース）。今回のように/mnt配下にマウントしたスキルも同じファイルシステム上に存在するため path ソースで参照できる、というのが本構成の考え方です。実際に運用する際は、ステップ4の--execでパスが見えていることを必ず確認してから本番に進めてください。
これで、S3 Files にあるスキルを、AgentCore Managed Harness のエージェントがマウント経由で使う構成の完成です。
補足：いろんなソースを混ぜられる
スキルソースは4種類すべてを1回の呼び出しで混ぜられます。
response = client.invoke_harness(
harnessArn=HARNESS_ARN,
runtimeSessionId=SESSION_ID,
skills=[
{"awsSkills": {"paths": ["core-skills/aws-cdk"]}}, # AWS公式
{"git": {"url": "https://github.com/anthropics/skills", "path": "skills/docx"}}, # Git
{"s3": {"uri": "s3://my-bucket/skills/company-style/"}}, # S3 skill source（道①）
{"path": "/mnt/s3data/skills/release-note-writer"}, # S3 Filesマウント（道②）
],
messages=[{"role": "user", "content": [{"text": "このプロジェクトを手伝って"}]}],
)
また、スキルはハーネス作成時（CreateHarness / UpdateHarness）のデフォルトとしても、呼び出しごとにも指定できます。両方で同名スキルを定義した場合は invoke 時のものが勝ちます。
ハマりやすいポイントまとめ
| 症状 | エラー / 原因 | 対処 |
|---|---|---|
| S3 スキルが取れない | AccessDeniedException |
実行ロールに s3:GetObject / s3:ListBucket を付与 |
| S3 オブジェクトが無い | Skill source not found: s3://… |
URI のパスを確認 |
| Git clone が失敗 | could not resolve host |
VPC に NAT ゲートウェイがあるか確認 |
| Git がタイムアウト | operation timed out after 60s |
Git fetch は 60秒以内に完了必須 |
| スキルが大きすぎる | Skill exceeds 1GB size limit |
スキルは 1GB 以下に |
| AWS スキルが一致しない | AWS skill path 'x' matched no skills |
glob パターンを見直す |
| パストラバーサル | Invalid AWS skill path |
相対パスのみ。/ 始まりや .. は禁止 |
スキル取得の失敗は握りつぶされず、必ず呼び出し自体が失敗します（descriptive error 付き）。「動いてるのにスキルが効いてない…」という事故が起きにくい、良い設計です。
そして一番大事なのは、冒頭で書いた 「S3 skill source（道①）」と「S3 Files マウント（道②）」を混同しないこと。
- VPC を立てたくない / スキルを配るだけ → 道①
- S3 をファイルシステムとして使いたい → 道②（VPC必須）
まとめ
- AgentCore Managed Harness は、エージェントを本番運用するための「土台一式」を設定で済ませられるマネージドサービス。2026年6月 GA。
- Skills は Markdown + スクリプトで専門知識をオンデマンドに渡す仕組み。4種類のソース（AWS / Git / S3 / Path）がある。
- 「S3 から Skill を使う」には 2つの道がある:
-
道①：S3 skill source …
{"s3": {"uri": ...}}、VPC不要、かんたん -
道②：S3 Files マウント + path skill …
/mntにマウントして参照、VPC必須、柔軟
-
道①：S3 skill source …
- タイトルの「S3 Files をマウント」をやるなら道②。ARN のコロン、マウントパスは
/mnt配下、VPC 必須あたりがハマりポイント。
「マウント」という言葉に引っ張られて道②を選びがちですが、多くのケースでは道①で十分です。要件に合わせて選びましょう。