Help us improve
Share bugs, ideas, or general feedback.
From box
Builds Box integrations for uploads, folders, listings, downloads, sharing, collaborations, search, metadata, automations, and AI retrievals via MCP server, CLI, SDKs, or REST APIs.
npx claudepluginhub box/box-for-ai --plugin boxHow this skill is triggered — by the user, by Claude, or both
Slash command
/box:boxThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Implement Box content workflows in application code. Reuse the repository's existing auth and HTTP or SDK stack whenever possible, identify the acting Box identity before coding, and make the smallest end-to-end path work before layering on sharing, metadata, webhooks, or AI.
examples/box-prompts.mdreferences/ai-and-retrieval.mdreferences/auth-and-setup.mdreferences/box-cli.mdreferences/bulk-operations.mdreferences/content-workflows.mdreferences/mcp-tool-patterns.mdreferences/rest-calls.mdreferences/troubleshooting.mdreferences/webhooks-and-events.mdreferences/workflows.mdMandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
Implement Box content workflows in application code. Reuse the repository's existing auth and HTTP or SDK stack whenever possible, identify the acting Box identity before coding, and make the smallest end-to-end path work before layering on sharing, metadata, webhooks, or AI.
After completing step 0 (tool inventory), 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 |
MCP covers the majority of common agent workflows and is the default when it has a matching tool. Use CLI when the operation falls outside MCP's scope, when compact and field-filtered output matters, or for reproducible verification commands. If MCP is unavailable, guide the user through MCP setup first; if CLI is unavailable, guide the user through CLI setup next. Use direct REST only as a last resort after explicitly asking the user to confirm that REST fallback is acceptable.
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, shared links, collaborations, or metadata | references/content-workflows.md | references/auth-and-setup.md | Read-after-write call using the same actor |
| 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 |
| Search, document retrieval, summarization, extraction, or Box AI | references/ai-and-retrieval.md | references/auth-and-setup.md | Retrieval-quality check before answer formatting |
| 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 |
Follow these steps in order when coding against Box.
who_am_i. If it fails, try mcp_auth. If auth still fails, read references/auth-and-setup.md for MCP setup steps. Record whether MCP is available.box users:get me --json. Record whether CLI is available.box users:get me --json.references/rest-calls.md for auth and request patterns.references/mcp-tool-patterns.md for MCP, references/box-cli.md for CLI, references/rest-calls.md for direct REST fallback) and the domain reference from the routing table:
references/mcp-tool-patterns.mdreferences/box-cli.mdreferences/rest-calls.mdreferences/auth-and-setup.mdreferences/workflows.mdreferences/content-workflows.mdreferences/bulk-operations.mdreferences/webhooks-and-events.mdreferences/ai-and-retrieval.mdreferences/troubleshooting.mdbox configure:environments:get --current as a routine auth check because it can print sensitive environment details.box CLI commands when box is installed and authenticated.BOX_ACCESS_TOKEN) and safe auth handling before issuing requests.box users:get me --json.Example smoke checks:
box users:get me --json
box folders:get 0 --json --fields id,name,item_collection
box folders:items 0 --json --max-items 20
box search "invoice" --json --limit 10
curl -sS -H "Authorization: Bearer $BOX_ACCESS_TOKEN" -H "Accept: application/json" "https://api.box.com/2.0/folders/0?fields=id,name,item_collection"
The final answer should include:
references/mcp-tool-patterns.md: best-practice patterns for working with Box content via the Box MCP server — search, file writes, metadata extraction, Box AI tool selection, and general guidelinesreferences/auth-and-setup.md: auth path selection, SDK vs REST choice, existing-codebase inspection, and current Box doc anchorsreferences/box-cli.md: CLI-first local auth, smoke-test commands, and safe verification patternsreferences/rest-calls.md: direct REST fallback patterns, auth setup, and safe request templatesreferences/workflows.md: quick workflow router when the task is ambiguousreferences/content-workflows.md: uploads, folders, listings, downloads, shared links, collaborations, metadata, and file movesreferences/bulk-operations.md: organizing files at scale, batch moves, folder hierarchy creation, serial execution, and rate-limit handlingreferences/webhooks-and-events.md: webhook setup, event-feed usage, idempotency, and verificationreferences/ai-and-retrieval.md: search-first retrieval, Box AI usage, and external AI guardrailsreferences/troubleshooting.md: common failure modes and a debugging checklistexamples/box-prompts.md: example prompts for realistic use cases