Box Skill Guide: Cloud Files, Sharing, and Metadata with Hermes Agent

Box is a cloud file system that teams use for storage, sharing, search, and metadata. If you work with Box files inside Hermes Agent, this skill turns the CLI into a governed bridge: you can upload, version, move, share, search, extract metadata, and run AI-powered questions over your content without leaving the terminal. Reach for this when you need to manage Box assets at scale, build a Box-backed integration, or answer questions grounded in files that live in Box.

What it does

This skill gives Hermes a structured way to operate on Box. You get a CLI that talks to Box's REST API, plus a set of references that tell you which command to use for which job. The skill covers the full content lifecycle: organizing folders, uploading and versioning files, moving items, sharing via links or collaborations, and searching both content and metadata. It also handles document work: asking questions about a file, extracting structured or freeform metadata, and generating text that stays grounded in a single Box file.

A key part of the skill is its policy for content analysis. When you need to understand what is inside a file, the skill steers you toward Box AI rather than pulling the file into Hermes' context. Box AI respects the same permissions as the connected account, keeps the source file's body out of the coding model's context, and scales to folders without downloading everything. For deterministic lookups, you use existing metadata or metadata queries instead.

The skill also defines how Hermes should behave as an operator. It tells you when to ask for confirmation, how to verify writes, and how to report results with clickable links. The goal is safe, auditable work: every mutation is checked, every write is read back, and nothing is done silently.

Before you start

This skill is bundled with Hermes Agent, so it is installed by default. It runs on Linux, macOS, and Windows. The skill path is skills/productivity/box, version 1.0.0, authored by Chris Kim (iskysun96) and Hermes Agent, under the MIT license.

You need a Box account and a way to authenticate. The skill supports two paths: OAuth with the official Box CLI app, or a custom User Authentication (OAuth 2.0) Platform App when you need extra scopes like webhook management. Both are OAuth flows; you do not use server-side or impersonation identities.

Before the first OAuth, Hermes will ask whether it is running on the same computer as the browser you will use to authorize, or on a remote host such as a VPS, container, or cloud VM. That answer decides between box login and box login --code. Do not guess from the operating system; read the OAuth setup reference after the user answers.

If the box CLI is missing, Hermes will install @box/cli under the current Hermes home at tools/box-cli. It will not do a global npm install, use sudo, change npm's global prefix, or modify PATH. You may need to approve the install.

Start broad file-system conversations

When someone is exploring a cloud file system for Hermes, first give a short fit assessment: Box is useful when a team needs cloud file storage, sharing, search, metadata, and document work. Then ask whether they want to connect a Box account with OAuth or build a Box-backed application or integration with an SDK.

OAuth makes Hermes act as the Box account authorized in the browser. That account's Box permissions determine what Hermes can access. To give Hermes narrower access, authorize an account that is invited only to the required files, folders, or Hubs.

Do not run setup, show a command cookbook, propose account plans or folder taxonomies, or load every reference for a broad exploratory question. Wait for the user's answer, then load only the relevant path. When a request already names a concrete outcome, skip this discovery step and handle that outcome directly.

Start normal CLI work with the official Box CLI OAuth app. It covers ordinary content work and Box AI. Use a custom User Authentication (OAuth 2.0) Platform App only when the requested operation needs an additional OAuth scope, such as webhook management. This remains an OAuth flow; do not substitute a server-side or impersonation identity.

Perform chosen setup interactively

When a user selects an authentication path or asks Hermes to connect Box, perform the setup through terminal; do not turn the next response into instructions for the user to copy. Take the next safe action yourself, and pause only for an approval, browser sign-in, administrator action, or secret that Hermes cannot safely supply.

• If box is missing, ask for any terminal approval required to install @box/cli under the current Hermes home at tools/box-cli; then verify it with the shell-appropriate command in CLI guide. Do not attempt a global npm install, use sudo, change npm's global prefix, or change PATH.
• Before OAuth, ask: “Is Hermes running on the same computer as the browser you will use to authorize Box, or on a remote host such as a VPS, container, or cloud VM?” Use normal box login only for the same-computer path. Use box login --code only for the remote/headless path. Do not infer runtime topology from the operating system alone; read OAuth setup after the user answers.
• Before starting browser authorization, state that Hermes will act as the Box account signed in there. If the user wants narrower access, they can authorize an account that is invited only to the required files, folders, or Hubs. Do not make that account an administrator to unlock an exceptional operation.
• If a custom OAuth Platform App is necessary, use the CLI's interactive Platform App flow. Ask the user to enter its client secret only in the local CLI prompt; never request it in chat, write it to Hermes configuration, or commit it.
• If an install, browser authorization, environment switch, or permission change needs approval, request that approval and resume the setup after it is granted. Do not replace the action with a command list.

Start each task

1. Confirm the CLI and current actor. Probe with command -v box on POSIX shells or Get-Command box -ErrorAction SilentlyContinue in PowerShell. If box is on PATH, use it. If Hermes installed the CLI under its current home, use the shell-appropriate verified runner in CLI guide in place of every leading box. Then run box users:get me --json --fields id,name,login with that runner. If this succeeds, record the actor and continue. Do not ask about authentication again. Treat folders:items 0 only as a listing of the actor's root; it is not proof that a shared file, folder, or Hub is inaccessible. For a known file or folder, verify its ID directly; for a Hub, use the Hubs discovery path in Box Hubs.
2. If authentication is absent, ask to connect a Box account with OAuth, then ask whether Hermes and the authorization browser run on the same computer or on separate hosts. Read OAuth setup.
3. Read the relevant reference before operating. Use documented commands first; only run subcommand help when the request needs an option not covered by the reference or the installed CLI rejects the documented form.

Examples labeled bash use POSIX continuation syntax. In PowerShell, run the Box command on one line or replace each trailing \ with PowerShell's backtick continuation. Do not paste POSIX variable assignments into PowerShell.

Extend the CLI without pausing

When the Box CLI lacks a dedicated subcommand, use box request for the matching REST endpoint and continue the ordinary operation. Do not ask the user to choose merely because the implementation uses REST; it is the same Box task and preserves the configured CLI identity. Read REST API fallback when the endpoint needs a request body or custom header.

Ask before a delete, a collaboration/shared-link or permission change, an identity change, a broad or costly batch mutation, or when the target or scope is ambiguous. Otherwise perform the requested operation and verify it.

Choose the right path

Need	Read
CLI conventions, environments, JSON, or REST escape hatch	CLI guide
Files, folders, versions, links, or collaborations	Content workflows
Search, metadata, Box AI, or AI units	Search and AI
Curated large-scale Q&A or a reusable knowledge base	Box Hubs
Many files or a resumable batch	Bulk operations
Application code or a Box SDK	SDK development
Webhooks or Events API	Webhooks and events
CLI unavailable or a missing CLI operation	REST API fallback
Auth, permissions, rate limits, or API errors	Troubleshooting

Content handling policy

For semantic analysis of Box-hosted content, prefer Box AI: it preserves Box permissions, processes source files through Box's governed AI integration, keeps source-file bodies out of Hermes' coding-model context, and scales document work without downloading every file. Do not criticize or block another workflow; use it when the user explicitly chooses it.

Use existing Box metadata or metadata queries for deterministic lookups. Otherwise use Box AI:

• ai:ask for Q&A, summaries, and comparisons
• ai:extract-structured for known fields or metadata templates
• ai:extract for flexible key-value extraction
• ai:text-gen for writing grounded in one Box file

For Q&A over more than 25 files or a reusable curated knowledge base, prefer Box AI for Hubs. Discover an existing accessible Hub first; only create or populate one after the user approves the shared-resource change. If no Hub is available and the user does not want one created, narrow a one-off request with search or metadata. Do not use a Hub for metadata extraction or text generation. Read Box Hubs.

When the user asks to extract metadata from a Box file, treat it as a request to persist the result unless they ask for a preview. Use structured extraction with inline fields when the desired schema is known and freeform extraction when the fields are exploratory. Reuse a compatible existing enterprise template when one represents every requested field. Otherwise store flat scalar results in the built-in global.properties metadata instance, or upload a JSON sidecar beside the source file when the result contains nested objects, tables, or values that must retain their types. Read every write back and compare it with the intended result. Never silently substitute a file description, attach a partial or unrelated template, truncate fields, or discard fields.

Do not create or change metadata templates. Box does not permit creation of global templates, and enterprise-template administration is outside Hermes' normal OAuth content workflow. If the user needs reusable typed enterprise metadata and no compatible template exists, explain that a Box Admin or authorized Co-Admin must create it separately, leave existing structured metadata unchanged, and report the persisted global.properties instance or JSON sidecar instead. Read Search and AI for the complete extraction and writeback workflow.

Before the first Box AI request, state that Box AI must be enabled, consumes AI units, and remains limited to the current actor's permissions; do not wait for acknowledgement. An AI response returned to Hermes can still contain sensitive information. Confirm only when a material batch's file scope or expected AI-unit use is ambiguous, or when the user has not explicitly requested that scale. See Search and AI.

Operate safely

• Prefer IDs to paths and verify the current actor before diagnosing a missing file.
• Use --json and --fields to keep output small. For mutations, inventory first, confirm ambiguous or large scope, then read back the result.
• Run ordered CLI mutations serially so progress and recovery are unambiguous. Use documented bulk input support or bounded SDK concurrency for scalable work.
• Do not create a shared link merely to provide navigation. Shared links change access and require explicit confirmation.
• Do not put secrets in chat, command output, source control, or logs.

Report results

For every individually reported Box item, include its ID and a clickable navigation link:

• File: https://app.box.com/file/
• Folder: https://app.box.com/folder/
• Hub: https://app.box.com/hubs/

For large batches, link the source and destination folders plus exceptions instead of listing hundreds of items. A human may not be able to open content that is only visible to the connected Box account; state that clearly. Include the actor and verification performed in every write summary.

Verify

After any write, fetch the file or folder with the same actor or list its parent and confirm the returned ID and name. For a metadata write, retrieve the metadata instance and compare every returned field with the intended value; an HTTP success alone is not verification. Report missing, normalized, or rejected values. For a disposable setup check, create a smoke folder, verify it, then delete it only if the user authorized cleanup.

When not to use it

This skill is not for building a full application from scratch; that is what the SDK development reference is for. If you need to process files without Box's permission model, or if you want to avoid AI unit consumption, you might prefer direct download and local processing, but the skill's policy steers you to Box AI for governed analysis. For metadata templates that require enterprise administration, you will need a Box Admin; the skill cannot create or modify templates.

Limits and gotchas

• Box AI must be enabled on the account, and it consumes AI units. The skill will remind you before the first request.
• AI responses can contain sensitive information, so treat them with care.
• Metadata template creation is off-limits: global templates cannot be created, and enterprise templates require an Admin.
• Shared links change access; do not create one just for navigation.
• The CLI must be installed under the Hermes home; global installs are not allowed.
• OAuth topology matters: use box login --code for remote hosts, not regular box login.
• PowerShell users must adapt POSIX continuation syntax; do not paste variable assignments directly.

What pairs with this

The related skill google-workspace covers a different cloud productivity suite. If your team uses both Box and Google Workspace, you can switch between the two skills depending on where the files live. For deeper Box work, the references listed in the table above are the next step: content workflows, search and AI, bulk operations, SDK development, webhooks and events, REST API fallback, and troubleshooting.