Box MCPとBox AIによる再利用可能なメタデータ抽出エージェントスキルの構築

 npx ai-agent-skills install ./box-metadata-extraction --agent cursor 

# Box Metadata Extraction - Template-Driven (Box MCP)## Purpose
Extract structured metadata from documents stored in a Box folder and write it back using a specified Box metadata template.This skill is designed to be reusable across document types by taking a `template_key` as input and using Box AI + Box metadata tools to populate metadata instances on each file.---## When to Use
Use this skill when you want to:
- Populate Box metadata for all files in a folder
- Reuse one workflow across many document types
- Drive extraction from an existing Box metadata template (by key or name)Example prompts:
- “Use the box-metadata-extraction skill on the Box folder with ID <FOLDER_ID> using metadata template key identifications.”
- “Use the box-metadata-extraction skill on this Box folder shared link <URL> using metadata template name identifications.”---## Inputs### Required
Provide ONE of:
- **folder_id** (string), OR
- **folder_shared_link_url** (string)And ONE of:
- **template_key** (string), OR
- **template_name** (string)### Optional
- **dry_run** (boolean, default: false)  
  If true, do not write metadata back to Box. Only report what would be written.- **limit** (number)  
  Maximum number of files to process (useful for demos).- **use_enhanced_extraction** (boolean, default: false)  
  If true, prefer enhanced Box AI extraction for harder scans.---## Guardrails (Hard Rules)
- Documents are stored only in Box. Do not rely on local document files.
- Do not recurse into subfolders (top-level files only).
- Do not overwrite existing metadata values: fill empty fields only.
- Avoid downloading and saving files locally (do not call file download with saving enabled).---## Tooling (What to Use)
Use these Box MCP tools as needed:### Resolve folder and list files
- `box_shared_link_folder_find_by_shared_link_url_tool` (if using a folder shared link)
- `box_folder_items_list_tool` (list top-level items; keep `is_recursive=false`)  ### Read file content (only if needed for fallback)
- Prefer `box_file_text_extract_tool` to extract readable text/markdown from a file### Load template schema (optional but recommended)
- `box_metadata_template_get_by_key_tool` (preferred)
- `box_metadata_template_get_by_name_tool` (fallback)### Extract structured data
- `box_ai_extract_structured_using_template_tool` (preferred)
- `box_ai_extract_structured_enhanced_using_template_tool` (if `use_enhanced_extraction=true`)### Read/write metadata instances
- `box_metadata_get_instance_on_file_tool`
- `box_metadata_set_instance_on_file_tool` (if no instance exists)
- `box_metadata_update_instance_on_file_tool` (update only empty fields)---## Workflow### Step 1 — Resolve the target folder
If `folder_id` is provided:
- Use it directly.If `folder_shared_link_url` is provided:
- Resolve the folder using `box_shared_link_folder_find_by_shared_link_url_tool`.
- Use the returned folder id.### Step 2 — List top-level files
- Call `box_folder_items_list_tool(folder_id, is_recursive=false)`.
- Filter results to files only.
- If `limit` is provided, process only the first N files.### Step 3 — Resolve template key (if only name provided)
- If `template_key` is provided, use it.
- Else look up the template using `box_metadata_template_get_by_name_tool(template_name)` and extract its key.(Optionally) fetch template definition using `box_metadata_template_get_by_key_tool` to learn field names/types for normalization.### Step 4 — For each file, check existing metadata
- Call `box_metadata_get_instance_on_file_tool(file_id, template_key)`.
- Determine which template fields are already populated.
- Only attempt to fill missing/empty fields.### Step 5 — Extract structured data for this file
Preferred path:
- Call Box AI template extraction for this file:
  - `box_ai_extract_structured_using_template_tool(file_ids=[file_id], template_key=template_key)`
  - If `use_enhanced_extraction=true`, use the enhanced variant.Fallback path (only if template extraction fails or returns empty):
- Use `box_file_text_extract_tool(file_id)` to retrieve text.
- Then extract only template-defined fields.---### Step 6 — Normalize and filter extracted values
- Normalize dates to `YYYY-MM-DD` when possible.
- Trim whitespace.
- Preserve casing for names and proper nouns.**Important:**
- If a value does not exist in the document, **do not write anything** for that field.
- Do not invent, infer, or synthesize values.
- Only include fields with non-empty values that are clearly supported by the document content.---### Step 7 — Write metadata back (unless dry_run)
- Build `metadata_values` using only fields that:
  1) were extracted with a real, non-empty value, AND
  2) are currently empty on the file.If no metadata instance exists:
- Use `box_metadata_set_instance_on_file_tool(file_id, template_key, metadata_values)`If an instance exists:
- Use `box_metadata_update_instance_on_file_tool(file_id, template_key, metadata_values)`Never overwrite existing non-empty fields.---### Step 8 — Output summary
Return a summary table showing:
- file name
- file id
- template_key
- fields written (with full values)
- fields skipped (already present or not found)Do not redact values in the summary output.---## Failure Handling
- If one file fails, continue with the remaining files and report the error.
- If the template cannot be resolved, stop and explain what is required.
- If extraction yields no values for a file, report “no data extracted” and continue.---## Expected Output
- Full metadata values written to Box for extracted fields
- Clear visibility of extracted values in both chat output and Box UI
- No local document files required

(参考訳)
# Box メタデータ抽出 - テンプレート駆動型 (Box MCP)## 目的
Boxフォルダに保存されたドキュメントから構造化メタデータを抽出し、指定したBoxメタデータテンプレートを使って書き戻します。このスキルは、入力として`template_key`を受け取り、Box AIとBoxメタデータツールを使ってファイルごとにメタデータインスタンスを入力することで、ドキュメントタイプ間で再利用できるよう設計されています。---## 使用に適した状況
このスキルは、以下の用途で使用します。
- フォルダ内のすべてのファイルのBoxメタデータを入力する
- 多数のドキュメントタイプで1つのワークフローを再利用する
- 既存のBoxメタデータテンプレートからの抽出を起動する (キーまたは名前を指定) プロンプトの例:
- “メタデータテンプレートキーIDを使ってID <FOLDER_ID> のBoxフォルダに対して、box-metadata-extractionスキルを使用してください。”
- “メタデータテンプレート名IDを使ってこのBoxフォルダ共有リンク <URL> に対して、box-metadata-extractionスキルを使用してください。”---## 入力### 必須
 以下のどちらかを指定する:
- **folder_id** (文字列)、または
- **folder_shared_link_url** (文字列) かつ以下のどちらか:
- **template_key** (文字列)、または
- **template_name** (文字列)### 省略可
- **dry_run** (ブール値、デフォルト: false)  
  trueの場合はメタデータをBoxに書き戻さないでください。書き込まれると想定される内容だけを報告します。- **limit** (数値)  
  処理される最大ファイル数 (デモに有用)。- **use_enhanced_extraction** (ブール値、デフォルト: false)  
  trueの場合は、より詳細なスキャンのために強化されたBox AI抽出を推奨します。---## ガードレール (厳格なルール)
- ドキュメントはBoxにのみ保存されます。ローカルのドキュメントファイルに依存しないでください。
- サブフォルダ内を再帰的に処理しないでください (最上位のファイルのみ)。
- 既存のメタデータ値を上書きしないでください: 空のフィールドのみに入力します。
- ローカルでのファイルのダウンロードと保存を避けます (保存を有効にしたままファイルダウンロードを呼び出さないこと)。---## ツール (使用するもの)
必要に応じて以下のBox MCPツールを使用します。### フォルダを解決し、ファイルリストを取得する
- `box_shared_link_folder_find_by_shared_link_url_tool` (フォルダの共有リンクを使用している場合)
- `box_folder_items_list_tool` (最上位項目のリストを取得し、'is_recursive=false'を保持) ### ファイルの内容を読み取る (フォールバックに必要な場合のみ)
- ファイルから読み取り可能なテキスト/マークダウンを抽出するには`box_file_text_extract_tool`を推奨します### テンプレートスキーマを読み込む (省略可だが推奨)
- `box_metadata_template_get_by_key_tool` (推奨)
- 'box_metadata_template_get_by_name_tool' (フォールバック)### 構造化データを抽出する
- `box_ai_extract_structured_using_template_tool` (推奨)
- `box_ai_extract_structured_enhanced_using_template_tool` (`use_enhanced_extraction=true`の場合)### メタデータインスタンスを読み取る/書き込む
- `box_metadata_get_instance_on_file_tool`
- `box_metadata_set_instance_on_file_tool` (インスタンスが存在しない場合)
- `box_metadata_update_instance_on_file_tool` (空のフィールドのみ更新)---## ワークフロー### ステップ1 — ターゲットフォルダを解決する
`folder_id` が指定されている場合:
- 直接それを使用します。`folder_shared_link_url` が指定されている場合:
-  `box_shared_link_folder_find_by_shared_link_url_tool`を使用してフォルダを解決します
- 返されたフォルダIDを使用します。### ステップ2 — 最上位ファイルの一覧を取得する
- `box_folder_items_list_tool(folder_id, is_recursive=false)`を呼び出します。
- 結果にフィルタをかけてファイルのみに絞り込みます。
- `limit`が指定されている場合、最初のN個のファイルのみを処理します。### ステップ3 — テンプレートキーを解決する (名前のみが指定されている場合)
- `template_key`が指定されている場合は、それを使用します
- それ以外の場合は `box_metadata_template_get_by_name_tool(template_name)` を使ってテンプレートを検索し、そのキーを抽出します。(省略可) `box_metadata_template_get_by_key_tool`を使ってテンプレート定義を取得し、正規化のためにフィールド名/フィールドタイプを学習します。### ステップ4 — ファイルごとに既存のメタデータを確認する
- `box_metadata_get_instance_on_file_tool(file_id, template_key)`を呼び出します。
- 入力済みのテンプレートフィールドを特定します。
- 不足しているフィールド/空のフィールドのみに入力を試行します。### ステップ5 — このファイルの構造化データを抽出する
推奨されるパス:
- このファイルのBox AIテンプレート抽出を呼び出します:
  - `box_ai_extract_structured_using_template_tool(file_ids=[file_id], template_key=template_key)`
  - `use_enhanced_extraction=true`の場合は強化されたバリエーションを使用します。フォールバックパス (テンプレート抽出が失敗または空が返された場合のみ):
- テキストを取得するには`box_file_text_extract_tool(file_id)`を使用します。
- 次にテンプレートで定義されたフィールドのみを抽出します。---### ステップ6 — 抽出した値を正規化し、それにフィルタをかける
- 可能であれば日付を`YYYY-MM-DD`に正規化します。
- 空白を削除します。
- 名前と固有名詞の大文字小文字の表記を保持します。**重要:**
- ドキュメントに値が存在しない場合は、そのフィールドについて**何も記述しないでください**。
- 値を捏造、推測、合成しないでください。
- ドキュメントの内容によって明確にサポートされている、空以外の値のフィールドのみを含めます。---### ステップ7 — メタデータを書き戻す (dry_run以外の場合)
- 以下に当てはまるフィールドのみを使用して`metadata_values`を構築します。
  1) 以前に空以外の実際の値があり、抽出済みであり、かつ
  2) 現在、ファイルでは空になっている。メタデータインスタンスが存在しない場合:
- `box_metadata_set_instance_on_file_tool(file_id, template_key, metadata_values)`を使用します インスタンスが存在する場合:
- `box_metadata_update_instance_on_file_tool(file_id, template_key, metadata_values)`を使用します 既存の空以外のフィールドを上書きしないでください。---### ステップ8 — 要約を出力する
以下を示す概要表を返します:
- ファイル名
- ファイルID
- template_key
- (完全な値がある) 書き込まれたフィールド
- スキップされたフィールド (既に存在しているか見つからない) 要約の出力値を修正しないでください。---## エラー処理
- 1つのファイルでエラーが発生した場合は、残りのファイルを処理しエラーを報告します。
- テンプレートが解決できない場合は、停止して何が必要であるかを説明してください。
- 抽出でファイルの値が出力されない場合は“データ抽出なし”と報告し、続行します。---## 期待される出力
- Boxに書き込まれた、抽出されたフィールドの完全なメタデータ値
- チャット出力とBox UIの両方で抽出済み値を明確に表示
- ローカルドキュメントファイルは不要