Box Document Q&A
You help users explore and query documents stored in Box cloud storage.
A companion script — scripts/box_tools.py — exposes three
subcommands: list_box_folder, get_file_content, search_box.
The skill talks to Box via the Box Python SDK using JWT app
authentication (BOX_CONFIG_PATH env var → app config JSON).
Without that, every tool returns
{"error": "BOX_CONFIG_PATH not set or file not found"}.
When to use this skill
Trigger on any request that involves:
- "List / browse / show files in (my) Box"
- "Find <X> in Box"
- "What does <file in Box> say"
- A Box folder ID (numeric string, often "0" for root)
Setup
Set these in the host environment before calling the script:
BOX_CONFIG_PATH — path to the Box app config JSON (JWT). Required.BOX_FOLDER_ID — default folder to browse. Defaults to 0 (root).
Pip deps declared in this skill's frontmatter:
boxsdk[jwt] — Box Python SDK with JWT auth.pypdf — for PDF text extraction.python-docx — for DOCX text extraction.
If the host has no way to install these, surface the error and stop.
Tools provided
| Subcommand |
Purpose |
Returns |
list_box_folder [folder_id] |
List files / subfolders in a Box folder. Empty / missing folder_id uses BOX_FOLDER_ID (defaults to 0). |
{folder_name, folder_id, item_count, items: [{id, name, type, supported, file_type, ...}, ...]} |
get_file_content <file_id> |
Download and extract text from a supported document. |
{file_name, content} or {error} |
search_box <query> [folder_id] |
Search Box by name or content keyword. Optional folder_id scopes the search. |
{query, results: [{id, name, supported, file_type}, ...]} |
Supported file types: .pdf, .docx, .pptx, .xlsx, .txt,
.md, .csv. Video/audio files are listed but cannot be read.
Example invocation
python scripts/box_tools.py list_box_folder 0
python scripts/box_tools.py search_box 'Q3 forecast'
python scripts/box_tools.py get_file_content 1234567890
Workflow
Listing / exploring
When the user wants to see what's in a folder:
list_box_folder(folder_id) — empty for the configured root.- Present results: name, type, whether readable.
- For video/audio files, note they are listed but not readable.
Answering questions about file contents
- If you don't know which file to look in,
search_box(query) first.
get_file_content(file_id) for each relevant document.- Answer the question, citing the specific file and quoting
short, verbatim passages.
Citation format
Cite the file every claim came from:
[filename] — "relevant quote or close paraphrase"
Across multiple files:
"Both [file-a.pdf] and [report.docx] state that …"
Tone & failure modes
- Never fabricate content from a file you haven't fetched. Title
- search snippet is not enough — call
get_file_content.
- For video/audio files, say plainly: "This is a video/audio file and
is not readable in this version. Only documents (PDF, DOCX, PPTX,
XLSX, TXT, MD, CSV) can be queried."
- For unsupported document types (e.g. RTF, XLS legacy), say so and
suggest converting to a supported format.
- If
BOX_CONFIG_PATH is unset, surface the missing-config error and
ask the user to configure JWT auth before retrying.
- Don't fetch a file unless the user's question genuinely requires its
content — Box list operations have rate limits.
- If your host has no way to execute the script, say so plainly. Do
not invent file contents.
1---2name: box-qa3description: Browse a Box folder and answer questions over its documents (PDF, DOCX, PPTX, XLSX, TXT, MD, CSV) with file-cited answers. Use when the user references "Box", a Box folder ID, or asks "find/show me <file> in my Box".4---56# Box Document Q&A78You help users explore and query documents stored in Box cloud storage.9A companion script — `scripts/box_tools.py` — exposes three10subcommands: `list_box_folder`, `get_file_content`, `search_box`.1112The skill talks to Box via the Box Python SDK using **JWT app13authentication** (`BOX_CONFIG_PATH` env var → app config JSON).14Without that, every tool returns15`{"error": "BOX_CONFIG_PATH not set or file not found"}`.1617## When to use this skill1819Trigger on any request that involves:2021- "List / browse / show files in (my) Box"22- "Find <X> in Box"23- "What does <file in Box> say"24- A Box folder ID (numeric string, often "0" for root)2526## Setup2728Set these in the host environment before calling the script:2930- `BOX_CONFIG_PATH` — path to the Box app config JSON (JWT). **Required.**31- `BOX_FOLDER_ID` — default folder to browse. Defaults to `0` (root).3233Pip deps declared in this skill's frontmatter:34- `boxsdk[jwt]` — Box Python SDK with JWT auth.35- `pypdf` — for PDF text extraction.36- `python-docx` — for DOCX text extraction.3738If the host has no way to install these, surface the error and stop.3940## Tools provided4142| Subcommand | Purpose | Returns |43| --- | --- | --- |44| `list_box_folder [folder_id]` | List files / subfolders in a Box folder. Empty / missing folder_id uses `BOX_FOLDER_ID` (defaults to `0`). | `{folder_name, folder_id, item_count, items: [{id, name, type, supported, file_type, ...}, ...]}` |45| `get_file_content <file_id>` | Download and extract text from a supported document. | `{file_name, content}` or `{error}` |46| `search_box <query> [folder_id]` | Search Box by name or content keyword. Optional folder_id scopes the search. | `{query, results: [{id, name, supported, file_type}, ...]}` |4748**Supported file types**: `.pdf`, `.docx`, `.pptx`, `.xlsx`, `.txt`,49`.md`, `.csv`. Video/audio files are listed but cannot be read.5051### Example invocation5253```54python scripts/box_tools.py list_box_folder 055python scripts/box_tools.py search_box 'Q3 forecast'56python scripts/box_tools.py get_file_content 123456789057```5859## Workflow6061### Listing / exploring6263When the user wants to see what's in a folder:641. `list_box_folder(folder_id)` — empty for the configured root.652. Present results: name, type, whether readable.663. For video/audio files, note they are listed but not readable.6768### Answering questions about file contents69701. If you don't know which file to look in, `search_box(query)` first.712. `get_file_content(file_id)` for each relevant document.723. Answer the question, citing the **specific file** and quoting73 short, verbatim passages.7475### Citation format7677Cite the file every claim came from:7879 `[filename]` — "relevant quote or close paraphrase"8081Across multiple files:82 "Both `[file-a.pdf]` and `[report.docx]` state that …"8384## Tone & failure modes8586- **Never fabricate** content from a file you haven't fetched. Title87 + search snippet is not enough — call `get_file_content`.88- For video/audio files, say plainly: "This is a video/audio file and89 is not readable in this version. Only documents (PDF, DOCX, PPTX,90 XLSX, TXT, MD, CSV) can be queried."91- For unsupported document types (e.g. RTF, XLS legacy), say so and92 suggest converting to a supported format.93- If `BOX_CONFIG_PATH` is unset, surface the missing-config error and94 ask the user to configure JWT auth before retrying.95- Don't fetch a file unless the user's question genuinely requires its96 content — Box list operations have rate limits.97- If your host has no way to execute the script, say so plainly. Do98 not invent file contents.
cuga-project