AGENT SKILL

dropbox

Browse, search, read, upload, and share the user's Dropbox — including team/shared folders — through their own Dropbox connection.

License 许可
MIT
所属仓库
yc-software/qm
最近更新
2026-11-15
Stars
★ 1.6w
Forks
2.0k

01 前言 Front Matter

name
dropbox
description
Browse, search, read, upload, and share the user's Dropbox — including team/shared folders — through their own Dropbox connection.
requiredCapabilities
[ "egress:api.dropboxapi.com", "egress:content.dropboxapi.com" ]

03 SKILL.md 正文

Dropbox

Use this skill when the user asks about their Dropbox files or folders — listing, searching, reading/downloading, uploading, or sharing.

Connection

Dropbox reaches you one of two ways; the requests are the same either way.

  • Direct token: $VAULT_TOKEN_API_DROPBOXAPI_COM (api.dropboxapi.com: list, search, share, move, delete) and $VAULT_TOKEN_CONTENT_DROPBOXAPI_COM (content.dropboxapi.com: download, upload) carry the same token, so if a host-specific one is empty, $VAULT_TOKEN_API_DROPBOXAPI_COM works for any Dropbox host. Pass it as -H "Authorization: Bearer $VAULT_TOKEN_..." on every call; nothing on the network path adds it for you. The curl examples below use it as written.

  • App connection: with no token, the user connects Dropbox as an app instead (composio skill). Send the same request through QM — same method, URL, query, headers and JSON body, but no Authorization header:

    curl -sS "$AGENT_API_URL/v1/composio/proxy" -H "X-Agent-Capability: $AGENT_API_TOKEN" \
      -H 'content-type: application/json' \
      --data '{"method":"POST","url":"https://api.dropboxapi.com/2/users/get_current_account"}'
    

    The reply is the provider's own status and body; the composio skill's "Raw requests" section covers 409 answers, choosing an account, and file bodies. Pass Dropbox-API-Arg in headers.

Never ask the user for a token, log it, or use another principal's credential or a service fallback.

If $VAULT_TOKEN_API_DROPBOXAPI_COM is empty and there is no app connection either: per-user connector tokens are injected only in a direct DM with the user (their personal scope) — in a channel or group they're absent by design, even for a fully-connected user. So don't tell a channel user to reconnect; ask them to DM you to run this. Only if it's empty inside a DM does it mean they haven't connected Dropbox — then point them to the Connectors page.

On 400 Invalid authorization value: the header was missing or empty, so Dropbox never checked the token. Fix your command (echo ${#VAULT_TOKEN_API_DROPBOXAPI_COM} shows the variable is set) and retry; this says nothing about the user's connection. Before telling a user Dropbox is broken, confirm with users/get_current_account below.

On 401 (invalid_access_token, expired_access_token): the token was sent and rejected → have them reconnect — unless the error body's .tag is missing_scope, in which case the app lacks a permission; name the required_scope it returns (the connected app grants account_info.read, files.metadata.read, files.content.read/write, sharing.read/write).

First: pick the right namespace (team vs personal)

This is the step that makes team and shared folders visible. By default the Dropbox API only lists the user's personal (home) namespace — for a Business member that root is often nearly empty. The team folders they see in the Dropbox web UI live in the team namespace, and the API only shows them when you set the Dropbox-API-Path-Root header.

Resolve the account's namespaces once, then reuse the root_namespace_id for the rest of the session — it doesn't change. This endpoint takes no arguments: send no request body and no Content-Type (adding Content-Type: application/json with an empty body returns a 400):

curl -sS -X POST 'https://api.dropboxapi.com/2/users/get_current_account' \
  -H "Authorization: Bearer $VAULT_TOKEN_API_DROPBOXAPI_COM"

Read root_info from the response. If root_info[".tag"] is team, use its root_namespace_id to see everything (team folders + the member's own files); if it is user (individual account), the default root is fine and no header is needed.

When you have a root_namespace_id, add this header to every files/sharing call so your view matches the web UI (substitute the id):

-H 'Dropbox-API-Path-Root: {".tag":"root","root":"ROOT_NAMESPACE_ID"}'

Prefer referencing items by id ("id:...", returned by list/search) over path strings — ids are stable across namespaces and avoid path-escaping issues.

List a folder

path is "" for the root of the active namespace, or a folder path/id:

curl -sS -X POST 'https://api.dropboxapi.com/2/files/list_folder' \
  -H "Authorization: Bearer $VAULT_TOKEN_API_DROPBOXAPI_COM" \
  -H 'Dropbox-API-Path-Root: {".tag":"root","root":"ROOT_NAMESPACE_ID"}' \
  -H 'Content-Type: application/json' \
  --data '{"path":"","recursive":false}'

For an ls -R-style or find-across-a-tree request, set "recursive":true to stream the whole subtree in one paginated pass instead of walking folder by folder.

If the response has "has_more":true, page with the returned cursor:

curl -sS -X POST 'https://api.dropboxapi.com/2/files/list_folder/continue' \
  -H "Authorization: Bearer $VAULT_TOKEN_API_DROPBOXAPI_COM" \
  -H 'Content-Type: application/json' \
  --data '{"cursor":"CURSOR"}'

Search

curl -sS -X POST 'https://api.dropboxapi.com/2/files/search_v2' \
  -H "Authorization: Bearer $VAULT_TOKEN_API_DROPBOXAPI_COM" \
  -H 'Dropbox-API-Path-Root: {".tag":"root","root":"ROOT_NAMESPACE_ID"}' \
  -H 'Content-Type: application/json' \
  --data '{"query":"budget","options":{"max_results":100}}'

If the response has "has_more": true, keep fetching with its cursor via files/search/continue_v2 (same shape as list_folder/continue above) before concluding a file doesn't exist.

Read / download a file

Downloads use the content host and carry their argument in the Dropbox-API-Arg header (no JSON body). Reference the file by id or path:

curl -sS -X POST 'https://content.dropboxapi.com/2/files/download' \
  -H "Authorization: Bearer $VAULT_TOKEN_CONTENT_DROPBOXAPI_COM" \
  -H 'Dropbox-API-Path-Root: {".tag":"root","root":"ROOT_NAMESPACE_ID"}' \
  -H 'Dropbox-API-Arg: {"path":"id:FILE_ID"}' \
  -o inbox/dropbox-file.bin

Keep source paths/ids in your answer so claims can be traced.

Writes require approval

Uploading, sharing, moving, and deleting are writes. Prepare the exact change, name the target file/folder (id + path), and get approval before running it.

Upload bytes you produced (content host; the arg is a header, the file is the body):

curl -sS -X POST 'https://content.dropboxapi.com/2/files/upload' \
  -H "Authorization: Bearer $VAULT_TOKEN_CONTENT_DROPBOXAPI_COM" \
  -H 'Dropbox-API-Path-Root: {".tag":"root","root":"ROOT_NAMESPACE_ID"}' \
  -H 'Dropbox-API-Arg: {"path":"/Reports/q3.pdf","mode":"add","autorename":true}' \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @q3.pdf

Create a shared link (returns a url; a 409 shared_link_already_exists carries the existing link in its metadata — reuse it):

curl -sS -X POST 'https://api.dropboxapi.com/2/sharing/create_shared_link_with_settings' \
  -H "Authorization: Bearer $VAULT_TOKEN_API_DROPBOXAPI_COM" \
  -H 'Dropbox-API-Path-Root: {".tag":"root","root":"ROOT_NAMESPACE_ID"}' \
  -H 'Content-Type: application/json' \
  --data '{"path":"id:FILE_ID"}'

Move/rename or delete (delete_v2 is recoverable — the file goes to the user's deleted files, not a permanent purge):

curl -sS -X POST 'https://api.dropboxapi.com/2/files/move_v2' \
  -H "Authorization: Bearer $VAULT_TOKEN_API_DROPBOXAPI_COM" \
  -H 'Dropbox-API-Path-Root: {".tag":"root","root":"ROOT_NAMESPACE_ID"}' \
  -H 'Content-Type: application/json' \
  --data '{"from_path":"id:FILE_ID","to_path":"/Archive/q3.pdf"}'

curl -sS -X POST 'https://api.dropboxapi.com/2/files/delete_v2' \
  -H "Authorization: Bearer $VAULT_TOKEN_API_DROPBOXAPI_COM" \
  -H 'Dropbox-API-Path-Root: {".tag":"root","root":"ROOT_NAMESPACE_ID"}' \
  -H 'Content-Type: application/json' \
  --data '{"path":"id:FILE_ID"}'

Always report the file path/id and what changed, plus any shared link you created.

04 同仓库更多 Skills

yc-software
yc-software/qm

zoom

Find, create, reschedule, and cancel the user's Zoom meetings through their own Zoom connection.

★ 1.6w
yc-software
yc-software/qm

use-shared-credential

When you need to call a service the org has a SHARED credential for (a SERP/search key, a paid-API key, a data-vendor feed, a Git remote) — and the platform has told you that credential is available to this conversation — make the call BY PROXY through the credential broker. You never see the secret; the core stamps it onto the outbound request for you.

★ 1.6w
yc-software
yc-software/qm

ui-state

See what the person is looking at in the QM web UI right now — the whole page (sidebar, every multiview pane, open dialogs) as raw HTML, the app's state as JSON, optionally the CSS and a screenshot. Use when they ask about something on their screen, want help with the UI, or you need to check what a canvas you wrote actually rendered.

★ 1.6w
yc-software
yc-software/qm

ui-canvas

Draw your own HTML/CSS/JS as a full-window overlay on top of the QM web UI — a dashboard, a form, a visualization, controls that message you back. Write, update, replace, pin or dismiss it. Use when an interactive or visual result beats a chat reply.

★ 1.6w
yc-software
yc-software/qm

taste-skill

Design taste and process for anything a person will look at in a browser — landing page, dashboard, prototype, deck. The default design driver for a browsable artifact, with an anti-slop playbook for the visual language.

★ 1.6w
yc-software
yc-software/qm

slack-drafts

Create Slack message drafts in the user's own composer, as the user, through their per-user Slack OAuth. Drafting only — the user reviews and sends from Slack.

★ 1.6w