--- title: "box/box-for-ai" description: "A toolkit for developers to get the most out of the Box Platform using AI" source: https://github.com/box/box-for-ai ref: main license: MIT licenseName: "MIT License" canonical: https://skillsdocs.com/box/box-for-ai base: https://github.com/box/box-for-ai/blob/main/ chapters: 5 inlined: 5 withheld: 0 words: 3830 updated: 2026-08-07T20:40:08Z generator: "Skills Docs" --- > **box/box-for-ai** — every Agent Skill in this repository, inlined verbatim. > > Canonical HTML: https://skillsdocs.com/box/box-for-ai > Per-chapter Markdown: https://skillsdocs.com/box/box-for-ai/.md > Machine manifest: https://skillsdocs.com/box/box-for-ai/.well-known/agent-skills/index.json > JSON: https://skillsdocs.com/api/v1/books/box/box-for-ai > Install: `npx skills add box/box-for-ai` > Upstream: https://github.com/box/box-for-ai @ `main` > Licence: MIT > > Content is mirrored from GitHub and © its authors, served unmodified. Takedown: https://github.com/kyleledbetter/skillsdocs/issues/new?labels=takedown&title=Takedown+request # box/box-for-ai A toolkit for developers to get the most out of the Box Platform using AI - **Chapters:** 5 - **Inlined:** 5 (licence detected) - **Words:** 3,830 - **Reading time:** 17 min - **Stars:** 5 ## Table of contents 1. [box-legal-workflows-contract](https://skillsdocs.com/box/box-for-ai/box-legal-workflows-contract.md) — Automate contract review and monitoring with Box MCP — find new or expiring contracts, compare them against firm templates to flag material variances, write st… 2. [box-legal-workflows-intake](https://skillsdocs.com/box/box-for-ai/box-legal-workflows-intake.md) — Automate legal client intake and onboarding with Box MCP — review intake documents for completeness against firm requirements, summarize risk for attorney revi… 3. [box-legal-workflows-ma](https://skillsdocs.com/box/box-for-ai/box-legal-workflows-ma.md) — Build and manage M&A virtual data rooms with Box MCP — create secure due-diligence folder structures, scope role-based access for internal teams and external p… 4. [box-legal-workflows](https://skillsdocs.com/box/box-for-ai/box-legal-workflows.md) — Shared building blocks for Box-based legal workflows — Box collaboration role definitions, Box AI usage boundaries (what AI must not decide), and reusable huma… 5. [box](https://skillsdocs.com/box/box-for-ai/box.md) — Foundation skill for working with Box. Use this whenever the user mentions Box — authentication and MCP/CLI setup, choosing between MCP/CLI/REST, rate-limit an… ## Front matter _The repository README, verbatim except that relative links are resolved against https://github.com/box/box-for-ai/blob/main/._ # Box Agent Skills Agent Skills to help developers using AI agents work with Box. Whether you're building Box integrations in code, working with Box content via MCP tools, configuring webhooks, or using Box AI retrieval — this plugin gives your assistant the context it needs to do it right. The skills in this repo follow the [Agent Skills](https://agentskills.io/) format and can also be installed as a plugin for platforms like Codex, [Cursor](https://cursor.com), and [Claude Code](https://code.claude.com). ## Installation ### As an Agent Skill ```bash npx skills add box/box-for-ai ``` Check out the latest and full list of skills [here](https://skills.sh/box/box-for-ai). ### As a Platform Plugin This repo can also be installed as a plugin for supported platforms. You configure the Box MCP server connection through your platform's MCP settings — see the setup guide for your platform below. | Platform | Setup guide | |---|---| | Codex | [`.codex-plugin/README.md`](https://github.com/box/box-for-ai/blob/main/.codex-plugin/README.md) | | Cursor | [`.cursor-plugin/README.md`](https://github.com/box/box-for-ai/blob/main/.cursor-plugin/README.md) | | Claude Code | [`.claude-plugin/README.md`](https://github.com/box/box-for-ai/blob/main/.claude-plugin/README.md) | ## Usage Skills are automatically available once installed. The agent will use them when relevant tasks are detected. Here are some example prompts: ### Implement Box content workflows `Add Box file upload to my app` `Create a shared link for this folder` `Set up Box webhooks for new file events` ### Build document-driven flows `Search my Box account for invoices` `Use Box AI to classify documents` `Wire webhooks to process new uploads` ### Troubleshoot integrations `Debug 401 errors with my Box JWT auth` `Fix webhook signature verification` ## Skill Structure The Box skill follows the [Agent Skills Open Standard](https://agentskills.io/): - `SKILL.md` - Skill manifest with frontmatter, routing table, workflow steps, and guardrails - `references/` - Individual reference files (auth, content workflows, MCP tool patterns, AI/retrieval, etc.) - `examples/` - Example prompts ## Prerequisites - **Box CLI** (optional) — Install from [developer.box.com/guides/cli](https://developer.box.com/guides/cli) for CLI-first verification. - **BOX_ACCESS_TOKEN** (optional) — For direct REST verification when Box CLI is unavailable. ## Quick Verification Preferred order for agent tooling is MCP first, Box CLI second, and direct REST only as a last-resort fallback. ```bash # With Box CLI installed and authenticated: box users:get me --json box folders:items 0 --json --max-items 5 # Last-resort fallback (for sessions where MCP/CLI are unavailable): export BOX_ACCESS_TOKEN="your-token" curl -sS -H "Authorization: Bearer $BOX_ACCESS_TOKEN" -H "Accept: application/json" "https://api.box.com/2.0/folders/0" ``` ## Contributing Skills follow the [Agent Skills specification](https://agentskills.io). The Box skill is a directory with a `SKILL.md` file containing YAML frontmatter and markdown instructions, plus a `references/` directory for feature-specific deep dives. ## License MIT --- ## 1. box-legal-workflows-contract - **Source:** https://github.com/box/box-for-ai/blob/main/skills/box-legal-workflows-contract/SKILL.md - **Raw:** https://raw.githubusercontent.com/box/box-for-ai/main/skills/box-legal-workflows-contract/SKILL.md - **Markdown:** https://skillsdocs.com/box/box-for-ai/box-legal-workflows-contract.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html --- name: box-legal-workflows-contract description: Automate contract review and monitoring with Box MCP — find new or expiring contracts, compare them against firm templates to flag material variances, write structured contract metadata back to Box for searchability, and produce variance reports with citations. Use this skill when the user mentions contract review or monitoring, NDA or MSA review, contract expiration or renewals, contract metadata, or variance analysis, even if they don't name a specific Box tool. --- # Contract Review Agent > **PREREQUISITES:** > > - Read `box:box` for Box MCP auth, tool selection, base workflows. If missing, run: `npx skills add https://github.com/box/box-for-ai --skill box` > - Read `box-legal-workflows` for Box collaboration role definitions, Box AI usage boundaries, and reusable confirmation phrasings. If missing, run: `npx skills add box/box-for-ai --skill box-legal-workflows` Do contract review *in Box*: find contracts with Box search, compare against the firm's template with Box AI, persist results as Box metadata so they stay searchable, and monitor dates with metadata search. This skill is the contract-specific recipe; the underlying Box tool mechanics live in the capability references below. Materiality, risk, and favorability are firm-supplied criteria confirmed by an attorney — the agent extracts facts, stores them, and routes. It does not provide legal advice or decide risk. ## Box capability references Reach for these for tool mechanics rather than restating them here: - `box:references/mcp-search.md` — find contracts; metadata vs. keyword search, folder scoping, template schema lookup - `box:references/ai-and-retrieval.md` — compare to template and extract fields; pacing, text-rep/file limits, citations - `box:references/content-workflows.md` — metadata templates, `set_file_metadata`, report uploads, file comments - `box:references/collaboration.md` — grant the reviewing attorney access ## Box metadata model Persist review results as file metadata so contracts stay searchable. Find/inspect the firm's template via `box:references/mcp-search.md`; create one via `box:references/content-workflows.md` if none exists. - **Representative fields** (confirm the firm's actual set): `counterparty_name`, `contract_type`, `execution_date`, `effective_date`, `expiration_date`, `auto_renewal`, `notice_period_days`, `contract_value`, `governing_law`, `status` (active/expired/terminated/under_negotiation), `risk_rating`, `review_date`, `next_review_date`, `expiration_alert_date`. Link to matters with `matter_id`, `practice_area`, `matter_owner`. - The `risk_rating` value is the firm/attorney's determination — store it, don't decide it. ## Contract search recipes Once contracts carry metadata, use `search_files_metadata` (mechanics in `references/mcp-search.md`; otherwise `search_files_keyword` with date filters): - New since last review: `execution_date >= 'YYYY-MM-DD' AND execution_date <= 'YYYY-MM-DD'` - Expiring window: `expiration_date >= 'YYYY-MM-DD' AND expiration_date <= 'YYYY-MM-DD' AND status = 'active'` - By counterparty / rating: `counterparty_name = 'Acme Corp'` · `risk_rating = 'High'` ## Tool selection | Contract task | Tool | Notes | | --------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------- | | Find new contracts (date) | `search_files_metadata` | Query `execution_date`; fall back to `search_files_keyword` if no metadata | | Find expiring | `search_files_metadata` | Query `expiration_date` within 30/60/90 days | | Compare to template | `ai_qa_multi_file` | Contract + firm template in one call | | Extract metadata (template) | `ai_extract_structured_from_metadata_template` | If a template exists | | Extract metadata (custom) | `ai_extract_structured_from_fields_enhanced` | Define fields at runtime | | Write metadata | `set_file_metadata` | Persist extracted/confirmed fields | | Create variance report | `upload_file` | Write the summary doc | | Tag attorney | `create_file_comment` | Notify for review/expiration | | Grant attorney access | `create_collaboration` | If they lack access | ## Workflow 1. **Find**: `search_files_metadata` or `search_files_keyword`. **[CONFIRM: folder ID, date range/cadence]** 2. **Compare to template**: `ai_qa_multi_file` (contract + firm template) → extract clauses that differ, with citations. **[CONFIRM: template file ID]** 3. **Extract metadata**: `ai_extract_structured_from_metadata_template`, or `ai_extract_structured_from_fields_enhanced` if no template. 4. **Persist**: `set_file_metadata`, including the firm-confirmed `risk_rating`. **[CONFIRM: which fields]** 5. **Report**: `upload_file` — factual differences + citations + firm-confirmed rating (observations for attorney review, not recommendations). 6. **Route**: `create_file_comment` to tag the attorney; `create_collaboration` if they need access. **[CONFIRM: attorney, access]** 7. **Monitor expirations**: `search_files_metadata` on the expiration window → `create_file_comment` reminders → `set_file_metadata` (`expiration_alert_sent: yes`). ## Legal guardrails Box mechanics (external-sharing confirmation, AI pacing/limits/citations, metadata writes) are governed by the capability references above and `box-legal-workflows`. Specific to contracts: - Risk, materiality, and favorability are firm + attorney calls, never the agent's. If the firm has no documented criteria, route to an attorney rather than rating. - Prompt Box AI to extract differences and cite section/page — not to judge materiality or legal risk. - Record decisions in Box as the audit trail: the firm-confirmed rating in metadata plus the uploaded summary. --- ## 2. box-legal-workflows-intake - **Source:** https://github.com/box/box-for-ai/blob/main/skills/box-legal-workflows-intake/SKILL.md - **Raw:** https://raw.githubusercontent.com/box/box-for-ai/main/skills/box-legal-workflows-intake/SKILL.md - **Markdown:** https://skillsdocs.com/box/box-for-ai/box-legal-workflows-intake.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html --- name: box-legal-workflows-intake description: Automate legal client intake and onboarding with Box MCP — review intake documents for completeness against firm requirements, summarize risk for attorney review, route incomplete or high-risk submissions to the right attorney, extract client and matter metadata to Box, and generate engagement letters from Box DocGen templates. Use this skill when the user mentions client intake, client onboarding, new client review, intake documents, or engagement letters. --- # Client Intake & Onboarding > **PREREQUISITES:** > - Read `box:box` for Box MCP auth, tool selection, base workflows. If missing, run: `npx skills add https://github.com/box/box-for-ai --skill box` > - Read `box-legal-workflows` for Box collaboration role definitions, Box AI usage boundaries, and reusable confirmation phrasings. If missing, run: `npx skills add box/box-for-ai --skill box-legal-workflows` Do client intake *in Box*: inventory the intake folder, check completeness with Box AI against the firm's checklist, extract intake data into Box metadata, route via comments and collaborations, and generate the engagement letter with Box DocGen. This skill is the intake-specific recipe; the underlying Box tool mechanics live in the capability references below. The firm supplies the required-document checklist and risk criteria; conflict, PEP, and sanctions determinations run through the firm's screening system — not the agent or Box AI. Not legal advice. ## Box capability references Reach for these for tool mechanics rather than restating them here: - `box:references/content-workflows.md` — inventory the folder, metadata templates, `set_file_metadata`, file comments - `box:references/ai-and-retrieval.md` — completeness checks and data extraction; pacing, limits, citations - `box:references/mcp-doc-gen.md` — generate the engagement letter from a template - `box:references/collaboration.md` — tag/route the attorney and share with the client - `box:references/mcp-search.md` — find/inspect the firm's metadata template ## Box metadata model Record the intake outcome as file metadata so submissions stay searchable. Find/create the firm's template via `box:references/mcp-search.md` / `box:references/content-workflows.md`. - **Representative fields** (confirm the firm's actual set): `client_name`, `matter_name`, `practice_area`, `matter_owner`, `jurisdiction`, `matter_value`, `intake_status` (complete/incomplete), `risk_rating`, `assigned_attorney`, `decision`, `decision_date`. - Store the firm/attorney's rating and decision, not the agent's. ## Tool selection | Intake task | Tool | Notes | |------|------|-------| | Inventory submission | `list_folder_content_by_folder_id` | All files in the intake folder | | Check completeness | `ai_qa_multi_file` | Present/complete/valid vs. firm checklist, with citations | | Extract intake data | `ai_extract_structured_from_fields_enhanced` | Client, matter, jurisdiction, value | | Write metadata | `set_file_metadata` | Record status, rating, decision, attorney | | Tag attorney | `create_file_comment` | Route with the factual summary | | Grant access | `create_collaboration` | Give the attorney access | | Generate engagement letter | `create_docgen_batch` | Only if the firm approves | | Share with client | `add_folder_shared_link` or `create_collaboration` | Confirm audience/expiration | ## Workflow 1. **Inventory**: `list_folder_content_by_folder_id`. **[CONFIRM: intake folder ID]** 2. **Completeness**: `ai_qa_multi_file` — is each required doc (per the firm's checklist) present, complete, and valid, with citations? **[CONFIRM: firm's required-document list]** 3. **Extract intake data**: `ai_extract_structured_from_fields_enhanced` (client_name, matter_name, practice_area, jurisdiction, matter_value, …). 4. **Surface risk indicators (facts only)**: `ai_qa_multi_file` to surface the facts the firm's criteria reference (value, jurisdiction, named parties) with citations. Do **not** use AI to determine conflicts, PEP status, or sanctions — pass names/entities/locations to the firm's screening system. 5. **Persist**: `set_file_metadata` with the firm-confirmed `risk_rating`, `intake_status`, and `decision`. 6. **Route**: `create_file_comment` to tag the attorney with the factual summary; `create_collaboration` for access. **[CONFIRM: who, access level]** 7. **Engagement letter (only if the firm approves)**: `create_docgen_batch` against the firm's template → output to the confirmed folder → share via `create_collaboration` or `add_folder_shared_link`. **[CONFIRM: DocGen template, destination folder, share method/expiration]** ## Legal guardrails Box mechanics (DocGen template/tag requirements, external-sharing confirmation, AI pacing/limits/citations, metadata writes) are governed by the capability references above and `box-legal-workflows`. Specific to intake: - Conflict, PEP, and sanctions clearance are firm screening + attorney/compliance calls — the agent surfaces the underlying text only and never clears them. - Risk rating and routing/staffing are firm policy + attorney calls, never the agent's. - Prompt Box AI to surface facts and cite the source, not to determine risk. --- ## 3. box-legal-workflows-ma - **Source:** https://github.com/box/box-for-ai/blob/main/skills/box-legal-workflows-ma/SKILL.md - **Raw:** https://raw.githubusercontent.com/box/box-for-ai/main/skills/box-legal-workflows-ma/SKILL.md - **Markdown:** https://skillsdocs.com/box/box-for-ai/box-legal-workflows-ma.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html --- name: box-legal-workflows-ma description: Build and manage M&A virtual data rooms with Box MCP — create secure due-diligence folder structures, scope role-based access for internal teams and external parties, validate permissions before sharing, and answer cross-document due-diligence questions with Box AI. Use this skill when the user mentions M&A, deal rooms, data rooms, VDRs, due diligence, or mergers and acquisitions. --- # M&A Deal Room Management > **PREREQUISITES:** > - Read `box:box` for Box MCP auth, tool selection, base workflows. If missing, run: `npx skills add https://github.com/box/box-for-ai --skill box` > - Read `box-legal-workflows` for Box collaboration role definitions, Box AI usage boundaries, and reusable confirmation phrasings. If missing, run: `npx skills add box/box-for-ai --skill box-legal-workflows` Build and run an M&A data room *in Box*: create the folder hierarchy, scope role-based access with Box collaborations, validate permissions before sharing, and answer due-diligence questions with Box AI plus citations. This skill is the deal-room-specific recipe; the underlying Box tool mechanics live in the capability references below. Deal risk, materiality, and terms are attorney calls. Not legal advice. ## Box capability references Reach for these for tool mechanics rather than restating them here: - `box:references/content-workflows.md` — create the folder hierarchy, upload/copy, classify-and-file submissions - `box:references/collaboration.md` — role-based access, shared links, permission audits (`list_item_collaborations`) - `box:references/mcp-search.md` — locate documents, folder-scoped search - `box:references/ai-and-retrieval.md` — due-diligence Q&A and term extraction with citations ## Folder structure Create the tree using the MCP tools in `box:references/content-workflows.md` (top-down, parent before child; reuse the existing folder on a `409` name conflict). Confirm the firm's template first. Example numbered structure — numeric prefixes keep ordering consistent and segregate external submissions: ``` [Deal Name] M&A Deal Room/ ├── 01 - Financial Statements/ ├── 02 - Legal Documents/ ├── 03 - HR & Employment/ ├── 04 - Intellectual Property/ ├── 05 - Commercial Contracts/ ├── 06 - Real Estate & Assets/ ├── 07 - IT & Cybersecurity/ └── 08 - External Submissions/ ``` ## Access model Scope access least-privilege and folder-specific rather than root (role capabilities and external-sharing confirmation rules are in `box:references/collaboration.md` and `box-legal-workflows`). Example deal-room mapping (confirm with the user): - Internal: Deal Lead → Editor/Co-Owner on root; Finance → Viewer on Financial Statements; Legal → Editor on Legal Documents. - External: External Counsel → Uploader on their own folder; Auditors → Viewer on Financial Statements; Prospective Buyer → Viewer on a curated subset, not the full room. ## Tool selection | Deal-room task | Tool | Notes | |------|------|-------| | Create folders | `create_folder` | Batch the hierarchy, top-down | | Add files | `upload_file` / `copy_file` | New uploads or copy existing Box files | | Grant access | `create_collaboration` | Confirm first for any external party | | Shared link | `add_folder_shared_link` | Confirm audience/expiration | | Audit/verify access | `list_item_collaborations` | Before and after external changes | | Find docs | `search_files_keyword` | Scope with `ancestor_folder_id` | | Due-diligence Q&A | `ai_qa_multi_file` | Cross-document; surface citations | | Extract terms | `ai_extract_structured_from_fields_enhanced` | Persist with `set_file_metadata` | | Classify submissions | `ai_qa_single_file` | Then `copy_file` into the right folder | ## Workflow 1. **Setup**: create the folder tree → grant internal access with `create_collaboration`. **[CONFIRM: structure, emails/roles]** 2. **Populate**: `upload_file`/`copy_file`; classify submissions with `ai_qa_single_file`, then `copy_file` into the right category folder. 3. **External access**: `list_item_collaborations` (audit) → **[CONFIRM: who, folders, permission, expiration]** → `create_collaboration` or `add_folder_shared_link` → `list_item_collaborations` (verify). 4. **Due diligence**: `search_files_keyword` (folder-scoped) → `ai_qa_multi_file` → present the answer with citations; `ai_extract_structured_from_fields_enhanced` for terms → `set_file_metadata` to persist. ## Legal guardrails Box mechanics (external-sharing confirmation, shared-link settings, AI pacing/limits/citations) are governed by the capability references above and `box-legal-workflows`. Specific to deal rooms: - Deal risk, materiality, and term interpretation are attorney calls, never the agent's. - Validate permissions with `list_item_collaborations` before *and* after external changes — a folder grant exposes everything inside it, including files added later. - Audit trail: record returned folder/file/collaboration IDs and write DD summaries back to Box. --- ## 4. box-legal-workflows - **Source:** https://github.com/box/box-for-ai/blob/main/skills/box-legal-workflows/SKILL.md - **Raw:** https://raw.githubusercontent.com/box/box-for-ai/main/skills/box-legal-workflows/SKILL.md - **Markdown:** https://skillsdocs.com/box/box-for-ai/box-legal-workflows.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html --- name: box-legal-workflows description: Shared building blocks for Box-based legal workflows — Box collaboration role definitions, Box AI usage boundaries (what AI must not decide), and reusable human-in-the-loop confirmation phrasings. Referenced by box-legal-workflows-ma, box-legal-workflows-intake, and box-legal-workflows-contract skills. --- # Shared Legal Concepts > **PREREQUISITE:** Read `box:box` for Box MCP authentication, tool selection, and base workflows. If missing, run: `npx skills add https://github.com/box/box-for-ai --skill box` Shared building blocks used by the legal skills (M&A, Intake, Contract Review): Box collaboration role definitions, the boundaries of where Box AI must not be the decision-maker, and reusable confirmation phrasings. Risk frameworks, metadata fields, workflows, and decision-transparency requirements live in the individual legal skills. ## Box capability references Reach for these for the underlying Box tool mechanics rather than restating them here: - `box:references/collaboration.md` — collaborator role capabilities, shared links, and external-sharing rules - `box:references/ai-and-retrieval.md` — Box AI Q&A, extraction, and structured metadata tools, with pacing/limits/citations --- ## Box Collaboration Roles **[CONFIRM: What permission level is appropriate?]** For the full breakdown of each Box collaborator role (Co-owner, Editor, Viewer Uploader, Previewer Uploader, Viewer, Previewer, Uploader) and the exact capabilities each grants, see the role matrix in `box:references/collaboration.md`. Use that matrix to determine which role fits a given collaborator, then have the human confirm the choice before granting access. Apply least privilege: default to the most restrictive role that still lets the collaborator do their job, prefer specific folders over root access, and set expiration dates on external collaborations. --- ## Box AI Boundaries Box AI informs; a human attorney decides. Do **NOT** use Box AI for: - Final legal advice or decisions (human attorney only) - Access-control decisions (human approves permissions) - Client conflict checks (use the firm's conflict system) - Privilege determinations (attorney judgment) - Settlement negotiations or strategy Box AI is appropriate for *informing* humans — completeness checks, risk-factor flagging, metadata extraction, contract comparison, and due-diligence Q&A — always with citations surfaced and a human making the final call. For details on the Box AI tools available and how to use them, see `box:references/ai-and-retrieval.md`. --- ## Common Confirmation Patterns Reusable phrasings for the human-in-the-loop confirmations the legal skills require. ### Risk Rating "Here are the factors I found: [...], with citations from Box. Under your firm's criteria, which rating applies?" (The agent presents facts; the firm's criteria and attorney determine the rating.) ### Permissions "I'll grant [person] [role] access to [folder/file]. They can [permissions]. Proceed?" ### Routing "Based on [practice area/risk/type], I recommend routing to [attorney]. Correct, or assign to someone else?" ### Document Completeness "Firm requires: [list]. Found: [list]. Missing: [list]. Proceed with assessment?" ### Metadata Template "Do you have a Box metadata template for [type]? If yes, scope and template key?" ### Thresholds "What is your firm's threshold for [matter value/expiration alert/risk escalation]?" ### External Sharing "Before sharing with [external party], confirm: (1) Permission level? (2) Folders? (3) Expiration? (4) Link or collaboration?" --- ## 5. box - **Source:** https://github.com/box/box-for-ai/blob/main/skills/box/SKILL.md - **Raw:** https://raw.githubusercontent.com/box/box-for-ai/main/skills/box/SKILL.md - **Markdown:** https://skillsdocs.com/box/box-for-ai/box.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (13), referenced from this skill's directory: - `references/ai-and-retrieval.md` — https://raw.githubusercontent.com/box/box-for-ai/main/skills/box/references/ai-and-retrieval.md - `references/auth-and-setup.md` — https://raw.githubusercontent.com/box/box-for-ai/main/skills/box/references/auth-and-setup.md - `references/box-cli.md` — https://raw.githubusercontent.com/box/box-for-ai/main/skills/box/references/box-cli.md - `references/bulk-operations.md` — https://raw.githubusercontent.com/box/box-for-ai/main/skills/box/references/bulk-operations.md - `references/collaboration.md` — https://raw.githubusercontent.com/box/box-for-ai/main/skills/box/references/collaboration.md - `references/content-workflows.md` — https://raw.githubusercontent.com/box/box-for-ai/main/skills/box/references/content-workflows.md - `references/mcp-doc-gen.md` — https://raw.githubusercontent.com/box/box-for-ai/main/skills/box/references/mcp-doc-gen.md - `references/mcp-hubs.md` — https://raw.githubusercontent.com/box/box-for-ai/main/skills/box/references/mcp-hubs.md - `references/mcp-search.md` — https://raw.githubusercontent.com/box/box-for-ai/main/skills/box/references/mcp-search.md - `references/rest-calls.md` — https://raw.githubusercontent.com/box/box-for-ai/main/skills/box/references/rest-calls.md - `references/troubleshooting.md` — https://raw.githubusercontent.com/box/box-for-ai/main/skills/box/references/troubleshooting.md - `references/webhooks-and-events.md` — https://raw.githubusercontent.com/box/box-for-ai/main/skills/box/references/webhooks-and-events.md - `references/workflows.md` — https://raw.githubusercontent.com/box/box-for-ai/main/skills/box/references/workflows.md --- name: box description: > Foundation skill for working with Box. Use this whenever the user mentions Box — authentication and MCP/CLI setup, choosing between MCP/CLI/REST, rate-limit and pacing guidance, troubleshooting Box errors (401/403/404/409/429), or working with Box MCP tools (files, search, collaboration, AI, hubs, doc gen). Start here for any Box task even if the user doesn't name a specific tool, then route to the right reference. --- # Box ## Overview This is the foundation skill for any Box task. It routes a request to the right tool (MCP, CLI, or REST) and the right domain reference. Use it to: - Inventory which Box tooling is available (MCP → CLI → REST) and set up what is missing. - Choose the correct tool for an operation using the tool selection table below. - Identify which reference file covers the user's domain. - Diagnose common Box errors (401/403/404/409/429, missing content, wrong actor). Always start here—even when the user does not name a specific tool—then route to the deeper reference. ## Route The Request ### Tool selection First confirm which resources you actually have access to and are able to access. After, use this table to pick the right tool for the operation: | Operation type | Prefer | Rationale | | --- | --- | --- | | Most agent workflows (search, AI, content management, metadata, hubs) | MCP | Structured I/O, concurrent-safe, covers the common cases | | Bulk operations (batch moves, folder trees, batch metadata) | CLI | Compact output, `--fields` filtering, full API surface without requiring manual REST auth | | Verification and smoke tests | CLI | Reproducible, user can copy-paste commands | | Operations outside MCP scope | CLI | Full API coverage | | Last-resort fallback when MCP is unavailable and CLI is unavailable or not an option | Direct REST | Only after explicit user confirmation and REST auth setup guidance | | Building application code (SDK/REST endpoints, webhook handlers) | SDK or REST in code | Not agent tooling — write code the user ships | The table above is the single source of truth for tool selection — the sections below reference it rather than restate it. When tooling is unavailable, escalate in this order: guide the user through MCP setup first, then CLI setup, and only fall back to direct REST as a last resort after the user explicitly confirms REST fallback is acceptable. ### Domain routing Choose which reference files to read based on what the user needs: | If the user needs... | Read first | Pair with | Minimal verification | | --- | --- | --- | --- | | Uploads, folders, listings, downloads, previews, moves, or metadata | `references/content-workflows.md` | `references/auth-and-setup.md` | Read-after-write call using the same actor | | Sharing, collaborations (users/groups), or shared links | `references/collaboration.md` | `references/content-workflows.md`, `references/auth-and-setup.md` | List collaborations before and after changes | | Finding files or folders (keyword, folder name, metadata search) | `references/mcp-search.md` | `references/auth-and-setup.md` | Confirm item details before acting | | Box AI Q&A, summarization, extraction, or document retrieval | `references/ai-and-retrieval.md` | `references/auth-and-setup.md` | Retrieval-quality check before answer formatting | | Box Hubs — creating, curating, or querying a hub | `references/mcp-hubs.md` | `references/ai-and-retrieval.md`, `references/auth-and-setup.md` | Confirm hub items after changes | | Document generation from templates (Doc Gen) | `references/mcp-doc-gen.md` | `references/content-workflows.md`, `references/auth-and-setup.md` | Confirm template and destination before batch | | Organizing, reorganizing, or batch-moving files across folders; bulk metadata tagging; migrating folder structures | `references/bulk-operations.md` | `references/content-workflows.md`, `references/auth-and-setup.md`, `references/ai-and-retrieval.md` | Inventory source, verify move count matches plan | | Event-driven ingestion, new-file triggers, or webhook debugging | `references/webhooks-and-events.md` | `references/auth-and-setup.md`, `references/troubleshooting.md` | Signature check plus duplicate-delivery test | | 401, 403, 404, 409, 429, missing content, or wrong-actor bugs | `references/troubleshooting.md` | `references/auth-and-setup.md` | Reproduce with the exact actor, object ID, and endpoint | | Unsure which workflow applies | `references/workflows.md` | `references/auth-and-setup.md` | Choose the smallest Box object/action pair first | ## MCP The Box MCP server is the default tooling for agent workflows. It provides structured I/O, is concurrent-safe, and covers the common cases (search, Box AI, content management, metadata, hubs). See the tool selection table above for when to prefer it over CLI or REST. ### Availability check - Call `who_am_i`. If it fails, try `mcp_auth`. - If auth still fails, read `references/auth-and-setup.md` for MCP setup steps and walk the user through setup before considering other tooling. - Record whether MCP is available. ### Tool availability and documentation The updated/maintained list of Box MCP tools is documented at https://docs.box.com/en/box-mcp/tools. If an expected tool is missing or unavailable, see `references/troubleshooting.md` (MCP tool missing section) for diagnostic steps and admin-console enablement. ### General guidelines - When listing folder contents, paginate if needed and summarize large directories rather than printing every item. - Prefer reading file details with `get_file_details` before operating on a file — it confirms the file exists and shows current state. - For exploratory or demo usage, prefer working within a dedicated folder rather than operating across the user's entire Box account. - Avoid granting or assuming broad enterprise-wide access. Default to least-privilege — only access the folders and files the task requires. ### Usage The Box MCP capabilities are documented in focused reference files. Use the domain routing table above to pick the right one for the task: | MCP category | Reference | | --- | --- | | Files, folders, uploads, downloads, previews, metadata | `references/content-workflows.md` | | Search (keyword, folder, metadata) | `references/mcp-search.md` | | Collaborations (users/groups) and shared links | `references/collaboration.md` | | Box AI Q&A, extraction, structured metadata extraction, and agents | `references/ai-and-retrieval.md` | | Box Hubs creation, item management, and hub-level Q&A | `references/mcp-hubs.md` | | Box Doc Gen templates and document generation batches | `references/mcp-doc-gen.md` | ## CLI / REST API The tool selection table above governs when to reach for the CLI or direct REST. Both rank below MCP: CLI for operations outside MCP's scope or that need compact, field-filtered output, and direct REST only as a last-resort fallback after explicit user confirmation. ### CLI #### Availability check - Run `box users:get me --json`. Record whether CLI is available. - If CLI is unavailable, walk the user through CLI setup and retry `box users:get me --json`. #### Usage - Read `references/box-cli.md` for CLI-first auth, smoke-test commands, safe verification patterns, and serial-execution constraints. ### REST API Direct REST is the last-resort fallback per the tool selection table — only when MCP and CLI are both unavailable or declined. Building application code (SDK/REST endpoints, webhook handlers) the user ships is a separate case — that is code you write, not agent tooling. Prefer an official Box SDK when one already exists in the codebase or for the target language. #### Confirmation and setup - Never use direct REST fallback silently. Ask the user for explicit confirmation before proceeding. - Guide the user through token setup (`BOX_ACCESS_TOKEN`) and safe auth handling before issuing requests. - Keep access tokens, client secrets, private keys, and webhook secrets in env vars or the project's secret manager. #### Usage - Read `references/rest-calls.md` for direct REST fallback patterns, auth setup, and safe request templates. ## Workflow Follow these steps in order when coding against Box. 0. Inventory available Box tooling using the availability checks in the **MCP** and **CLI / REST API** sections above: check MCP first (`who_am_i` / `mcp_auth`), then CLI (`box users:get me --json`), and record which are available. When tooling is missing, follow the escalation order from **Route The Request** (MCP setup → CLI setup → REST after explicit confirmation). If the task is building application code (adding SDK endpoints, webhook handlers), tooling availability is secondary — proceed to step 1. 1. Inspect the repository for existing Box auth, SDK or HTTP client, env vars, webhook handlers, Box ID persistence, and tests. 2. Determine the acting identity before choosing endpoints: connected user, enterprise service account, app user, or platform-provided token. 3. Select the tool using the tool selection table and identify the domain reference using the domain routing table above. 4. Confirm whether the task changes access or data exposure. Shared links, collaborations, auth changes, large-scale downloads, and broad AI retrieval all need explicit user confirmation before widening access or scope. 5. Read the reference for the selected tool (MCP, CLI, or REST) and the domain reference identified by the tool selection and domain routing tables above. See the **References** section at the end of this file for the full annotated list of what each file covers. 6. Implement the smallest end-to-end flow that proves the integration works. 7. Add a runnable verification step. Prefer the repository's tests first; otherwise use native Box CLI commands when CLI is available and authenticated. Use direct Box REST verification only as a last resort after explicit user confirmation. 8. Summarize the deliverable with auth context, Box IDs, env vars or config, and the exact verification command or test. ## Guardrails > **Mandatory guardrails live in `rules/box.mdc` (at the repo root).** That file covers confirmation gates for destructive actions, hub modifications, file comments, Doc Gen output locations, externally shared folders, content display preferences, and Box AI governance. Read and follow them in every session. - Preserve the existing Box auth model unless the user explicitly asks to change it. - Check the current official Box docs before introducing a new auth path, changing auth scope, or changing Box AI behavior. - Prefer an official Box SDK when the codebase already uses one or the target language has a maintained SDK. Otherwise use direct REST calls with explicit request and response handling. - In agent workflows, do not jump straight to direct REST when MCP or CLI can be set up. Offer setup guidance for MCP first and CLI second before proposing REST fallback. - Never use direct REST fallback silently. Ask the user for explicit confirmation before proceeding with REST calls. - Keep access tokens, client secrets, private keys, and webhook secrets in env vars or the project's secret manager. - Distinguish file IDs, folder IDs, shared links, metadata template identifiers, and collaboration IDs. - Treat shared links, collaborations, and metadata writes as permission-sensitive changes. Confirm audience, scope, and least privilege before coding or applying them. - Require explicit confirmation before widening external access, switching the acting identity, or retrieving more document content than the task truly needs. - When a task requires understanding document content, use Box AI as the first method attempted — it operates server-side and requires no downloads. See `references/ai-and-retrieval.md` for the full preference order and fallback chain. - Pace Box AI calls at least 1–2 seconds apart. For bulk classification, use the sample-first strategy in `references/bulk-operations.md`. - Avoid downloading file bodies or routing content through external AI pipelines when Box-native methods (Box AI, search, metadata, previews) can answer the question server-side. - Request only the fields the application actually needs, and persist returned Box IDs instead of reconstructing paths later. - Run Box CLI commands strictly one at a time — see `references/box-cli.md` for details. For bulk work, default to CLI and use REST only after MCP/CLI setup attempts fail or the user explicitly confirms REST fallback. - Make webhook and event consumers idempotent. Box delivery and retry paths can produce duplicates. - Keep AI retrieval narrow for search and Q&A tasks. Search and filter first, then retrieve only the files needed for the answer. This does not apply to Box AI classification — when classifying documents, Box AI should be tried first per the content-understanding guardrail above. - Do not use `box configure:environments:get --current` as a routine auth check — it can print sensitive environment details. ## Verification - Prefer the repository's existing tests or app flows when they already cover the changed Box behavior. - If no better verification path exists, prefer native `box` CLI commands when `box` is installed and authenticated. - Use direct REST verification only after confirming MCP and CLI are unavailable or not an option and after the user explicitly approves REST fallback. - For REST fallback, guide the user through token setup (`BOX_ACCESS_TOKEN`) and safe auth handling before issuing requests. - Confirm CLI auth with `box users:get me --json`. - Verify mutations with a read-after-write call using the same actor, and record the object ID. - For webhooks, test the minimal happy path, duplicate delivery, and signature failure handling. - For AI flows, test retrieval quality separately from answer formatting. For example smoke-check commands, see `references/box-cli.md` (Common verification commands). ## Deliverable The final answer should include: - Acting auth context used for the change - Box object type and IDs touched - Env vars, secrets, or config expected by the integration - Files or endpoints added or changed - Exact verification command, script, or test path - Any permission-sensitive assumptions that still need confirmation ## References - `references/content-workflows.md`: files and folders — uploads, downloads, previews, folder trees, moves, metadata; MCP tools + CLI/REST patterns - `references/collaboration.md`: sharing and access — collaborator roles, shared links, external-sharing rules; MCP tools + CLI/REST patterns - `references/mcp-search.md`: finding content — keyword, folder-name, and metadata search via MCP - `references/ai-and-retrieval.md`: Box AI and retrieval — Q&A, extraction, agents, content understanding preference order; MCP tools + CLI commands - `references/mcp-hubs.md`: Box Hubs — creation, item management, hub-level Q&A via MCP - `references/mcp-doc-gen.md`: Box Doc Gen — template registration and document generation via MCP - `references/bulk-operations.md`: organizing files at scale — batch moves, folder hierarchy creation, serial execution, and rate-limit handling - `references/auth-and-setup.md`: auth path selection, MCP server setup, SDK vs REST choice, existing-codebase inspection, and current Box doc anchors - `references/box-cli.md`: CLI-first local auth, smoke-test commands, and safe verification patterns - `references/rest-calls.md`: direct REST fallback patterns, auth setup, and safe request templates - `references/webhooks-and-events.md`: webhook setup, event-feed usage, idempotency, and verification - `references/workflows.md`: quick workflow router when the task is ambiguous - `references/troubleshooting.md`: common failure modes and a debugging checklist