# Box Metadata Extraction

> Box Metadata Extraction — Template-Driven (Box MCP)

- Skill: `box-community/box-metadata-extraction` (Agent Skill)
- Install (CLI): `npx skillmds@latest add box-community/box-metadata-extraction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/box-community/box-metadata-extraction/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: box-community (https://skillmd.com/u/box-community)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/box-community/box-metadata-extraction

---

# 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