clickmax-drive
Use when the user wants to find, organize, share, comment on, restore or clean up files and folders in the Clickmax workspace Drive (spaces, trash, quota, Google Drive).
How do I install this agent skill?
npx skills add https://docs.clickmax.io --skill clickmax-driveIs this agent skill safe to install?
No partner audit is available yet. Read the source before installing.
What does this agent skill do?
As tools abaixo aparecem com os nomes que o MCP da Clickmax registra. Se o seu cliente de IA prefixar nomes de tool (
mcp__<servidor>__,mcp_<servidor>_, ou outro), use o nome já prefixado que aparecer na sua lista de tools.
When this applies
Use this skill for the workspace file library: locating a file or folder, building a folder tree, sharing with a teammate, commenting, reading who has access, trashing/restoring, and answering "why is my storage full".
Not this skill:
- files attached to a CRM opportunity/task, meeting recordings, page images, message media -> they appear in the Drive read-only (see assumptions) but are managed in their own area
- publishing a file on the internet (image on a page, product deliverable) ->
clickmax-pages,clickmax-products - uploading a file or reading its bytes -> not possible through tools; upload happens in the Clickmax web app
Key assumptions
- SPACE = unit of access.
personal("Meu drive", one per person, private) |team(own members + roles) |system("Plataforma": platform-filed files from other areas; everyone reads, nobody writes) - role per space: reader < commenter < editor < owner. reader = view; commenter = +comment; editor = +create/rename/move/share/trash/restore; owner = +edit/delete space, manage members
- workspace seat only CAPS: viewer/guest/finance_only/attendant = reader max. Workspace owner = owner everywhere. Workspace admin does NOT see spaces they were not invited to
- direct item share = 2nd access source; most permissive wins, then seat cap. Sharing a folder covers everything inside, including future files
- NO public link. Sharing is always to a named, active workspace member.
sharerole isreader | commenter | editor(neverowner) drive_files_browseis not paginated (whole folder);drive_search/drive_favorites_list/drive_shares_with_meare paginated (page,perPagedefault 10)- search = NAME substring only (never file content); needs
qor a filter - names: max 200 chars, no
/\.., no leading.; folder/space names are NOT unique -> create is not idempotent - move = same space only, never into itself/descendant. No copy. No cross-space move
- trash: soft delete, 30 days, then purged by a daily job. Trashed items STILL count in quota. Only
drive_trash_purge/drive_trash_emptyfree space. Folder = one trash item with its subtree; list shows roots only - deleted spaces are not restorable; purge/empty are irreversible and, for Google-backed spaces, delete the file in the customer's own Google Drive
- files with
origin != uploadand folders withsystemOrigin= platform-filed: cannot be renamed/moved/trashed from the Drive - quota is per workspace (
quotaBytesfromdrive_storage_usage, never assume a number). Bytes are decimal strings.level: ok | warning >=80% | critical >=95% | exceeded. Google-backed files areexternalBytes, outside quota - Drive menu may be hidden in the web app for accounts where it is not released yet; the tools work regardless -> tell the user to contact support, do not try to "enable" it
userIdfor members/shares/person card:idfromworkspace_members_list(every person of the workspace; find bysearch= name or e-mail),user.idfromdrive_spaces_members_list, orpersonId(NOT the attendantid) fromattendants_list. Shares and space membership need anactiveperson; apendinginvitation cannot receive access yet- Google-backed space health =
connectionHealthon space rows:connected|read_only(opens/downloads, but folder creation and uploads fail) |disconnected(connection gone or authorization revoked). Fixing either = the person who connected Google reconnects in the web app. A folder created in a Google-backed space is created in Google first; a Google refusal saves nothing in Clickmax - person card numbers (
drive_people_get) are what the CALLER can see, never a workspace total of that person
Thought process
- Locate before acting: known name ->
drive_search; known space -> browse; nothing known ->drive_overview. - Check role before proposing writes (
myRolein space rows). reader/commenter -> explain instead of failing with 403. - Reuse before create: browse/list first, create only when nothing matches.
- Reversible (trash, rename, move, comment) > irreversible (purge, empty, delete space, connect Google). Ask before the irreversible ones and before any grant of access.
Execute guide
- Overview / discovery:
drive_overviewreturns spaces (withmyRole), counters, storage and the 6 latest recents in one call. Usedrive_spaces_listwhen only spaces are needed. - Find:
drive_search(q, optionaltype,ownerId,spaceId,from/to). Each row haslocation(space + folder path) to tell the user where it lives.drive_searchanddrive_favorites_listare paginated (page/perPage, seemeta): before concluding an item does not exist, picking "the" match or validating a result, read every pagemetareports (finding one candidate is not a reason to stop); page 1 alone is enough only for a preview the user asked for, and then say more pages exist. For "what did I use lately" ->drive_recents_list(not paginated,limitup to 100); starred ->drive_favorites_list. - Navigate:
drive_files_browsewithspaceId(+folderId; omit for the root). For an item that came through a share, takelocation.spaceIdfrom the share/search row.drive_folders_path= breadcrumb. - Before building a tree in a Google-backed space, read
connectionHealth(drive_spaces_get): anything other thanconnected-> tell the user to reconnect Google first instead of attempting creates. - Build a tree top-down:
drive_folders_createwithspaceIdand noparentIdfor level 1, then pass each returnedidasparentId. Never fire sibling creates before checking existing folders. - Organize:
drive_files_update/drive_folders_updatewithnameand/orfolderId/parentId(null= root, omitted = unchanged). - Share one item: resolve
userId->drive_shares_createwith exactly one offolderId/fileIdand the role. Check the result withdrive_items_access. Revoke withdrive_shares_revoke(shareId; only entries withinherited = false). Inherited access is changed in the space (drive_spaces_members_update/drive_spaces_members_remove) or in the parent share. - Give a person a whole space:
drive_spaces_members_add(space owner only). Re-adding updates the role. - Restore:
drive_trash_list->drive_trash_restorewithkind+idof the ROOT row. IfrestoredToRootis true, tell the user the original folder was gone. Something deleted inside a folder is restored by restoring the folder. - Free space:
drive_storage_usage->drive_trash_list-> show what goes (name, size, deleted by/when) -> confirmation ->drive_trash_purgeper item, ordrive_trash_emptyonly when the user wants everything they can delete gone. Trashing alone frees nothing. - Link for the user to open a file:
drive_files_download_url(300 s, credential-like: hand it only to the requester, never store it). It is not a way to share with others. - Google Drive:
drive_spaces_google_capabilities(own connection) ordrive_spaces_google_connections(all) -> only acanWriteconnection and only an EMPTY team space (even trashed items count) ->drive_spaces_connect_google. One-way; connecting/reconnecting the Google account itself happens in the web app. - "What does Ana have in the Drive?": resolve her
userId->drive_people_get(role, totals, team spaces in common, 4 newest files); for the full list,drive_searchwithownerId. - Comments:
drive_comments_list/drive_comments_add(commenter+). Activity of an item:drive_items_activity(not per-person views/downloads).
Report
- Lead with what was found/changed and WHERE:
Space / Folder / Subfolder. - Lists: newest-modified first for search; folders before files when browsing. Show up to 10 rows unless the user asked for everything (then fetch every page and list all); when rows are left out, say how many (
+N more) and offer to continue. - Sizes in human units (GB/MB) converted from the byte strings; quota as
used of quota (ratio %)+ level. - Shares: name the person, the item, the role and what the role allows; mention that access applies to everything inside a shared folder.
- Trash: show
expiresAt(days left) and say restore is possible until then. - Follow-up mutations, purges and access grants are opt-in only.
Warnings
- Sharing exposes data to another person: confirm item + person + role first.
- Purge / empty trash / delete space / connect Google are irreversible; never chain them onto a search result without an explicit user confirmation naming the items.
- Seat cap: a role granted to a viewer/guest/finance_only/attendant seat still behaves as reader; do not promise write access.
- 404 on an item can mean "no access", not only "does not exist".
- A
pendingfile is an unfinished upload; anorphanedfile has a broken Google link (still listed, not downloadable, nothing deleted).
Anti-patterns
- Promising public links, uploads, downloads of content, cross-space moves, copies or content search.
- Creating a folder or space without listing existing ones.
- Passing an attendant
idasuserId. - Treating trash as freed storage.
- Removing a member or share to "fix" inherited access (it is changed at its origin).
- Deleting a space to clean up a few files (trash the files instead).
Clickmax skill revision: 23f2b5440092
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/docs.clickmax.io/clickmax-drive">View clickmax-drive on skillZs</a>