Skills

A skill is a written procedure a workspace member saved — house conventions, a recurring report recipe, the way this team names things. Reading one before acting is usually cheaper than inferring it.

Read-only

List the workspace's SKILLS: markdown procedures its members wrote for agents (how they diagnose a metric, house chart conventions, trusted sources, a recurring report). Each row: id (the only handle; a name may repeat), a one-line description of WHEN to use it, ownerId/ownerName, updatedAt/updatedBy, archived. Call it EARLY — when a request sounds like a standing procedure ("the monthly board deck", "why did revenue drop"), names a skill, or starts multi-step work in an unfamiliar workspace: a skill holds what the workspace knows about its own data. Read a body with get_skill. ownerId filters to one person's; archived are hidden unless includeArchived:true. Lists only the skills YOU may open. To find one by name or keyword, pass query, whose description holds the search rules.

query

Find a skill by name or keyword instead of listing them all — use it when the user names or describes one ("the board-deck runbook") rather than listing every skill and matching names yourself. Matches names and one-line descriptions by keyword, ranked; one distinctive word works best. Rows are the listing's rows; pass the id to get_skill — names may repeat, so never resolve a skill by name. RANK ORDER IS NOT IDENTITY: when a hint says near-identical names tie, confirm which is meant (get_skill, or ask the user) before acting. Returns only skills YOU may open, never archived ones. Nothing matched: search each workspace from get_me, or list without query and match semantically.

Read-only

Return one skill in full, body included. Identify it by id (list_skills, or the bracketed id in the workspace-skills catalog); names may repeat, so never guess one from a name. Load the body BEFORE planning the work it covers and follow its procedure rather than improvising one — the caveats are usually the point. collab.editors lists who has it open in the web editor now: your write merges into their typing, except a paragraph they changed since your read, which you must re-read first. format:'markdown' returns a ready-to-write SKILL.md (frontmatter + body) for a local client: write it verbatim to .claude/skills/<name>/SKILL.md; keep json for reading or editing. The JSON carries url, publicLink, embed and the access (workspaceDefault, members, ownerId), so "who can edit this?" is a read. An empty versions means nothing has sealed yet (15–20 minutes after an edit). Requires view access.

Destructive write

Create or update a workspace skill — how you REMEMBER a procedure the user asks you to keep ("always chart revenue this way", "here's how we do the weekly review"): write it as a skill instead of answering that you'll remember it. Omit id to create (name, description and body all required); pass the id from list_skills to update in place, sending ONLY what changes — an omitted field keeps its stored value, so {id, archived: true} retires a skill and {id, name} renames one without resending the text. Write it as a runbook for a colleague who knows the tools but not this workspace: name short (a display label; duplicates are allowed, the id is the handle), description ONE line saying when to use it (the ONLY text a future agent sees before loading the skill, so make it a trigger, not a title), body markdown with the actual steps, max 20000 characters. Pass expectedUpdatedAt (the updatedAt you read from get_skill) to make the write conditional — it refuses if someone changed the skill since; without it, last writer wins. While people have the skill open in the web editor your write MERGES into their live document: paragraphs you change land, the rest stays theirs, and expectedUpdatedAt is the diff base. Changing a paragraph someone edited since your read is refused (conflict, nothing written) — re-read with get_skill and re-apply, or wait while they type. archived: true RETIRES a skill (out of list_skills, the agent catalog and the skill menu) without deleting it — prefer it to delete_skill for anything that might be wanted again; archived: false restores one, alone or beside new text (an archived skill refuses edits otherwise). Returns id, updatedAt. A new skill is born editable by every full member; access narrows that. Until a person saves it in the web editor, a tool-written skill reaches only its owner's and writer's agents. Creating needs full workspace membership; updating needs edit access on that skill (owner, editor grantee, or the editor default).

access

Grants, changes, or revokes access to the skill id names — the web's Skill → Sharing pane; alone, or beside an edit. Two independent knobs, at least one required: memberId + role sets a NAMED grant ('editor' | 'viewer', or 'none' to remove that person's grant), and workspaceDefault sets the baseline every full member gets without one — 'none' (named people only), 'viewer' (everyone in the workspace can read it), or 'editor' (everyone can edit it, which is what a skill is born with). "Read-only for everyone else" is workspaceDefault 'viewer' — one call that also covers members who join later; a named grant is for ONE person. get_skill reads the map back. This is how a request for access is ANSWERED: grant the requester editor, which also clears the pending request. Anyone with edit access on the skill may set it (its owner, an editor grantee, or a workspace admin); it refuses an archived skill (restore it first with archived:false). memberId must already be a member of this workspace (manage_member invite first) and may be neither the skill's OWNER — the owner already holds every right, and ownership moves only in the web app — nor YOURSELF: ask the owner or a workspace admin to change your own access rather than removing it by accident. A GUEST (share-by-email) can hold a grant and read the skill, but a guest's role is capped at viewer whatever is stored, so an editor grant on a guest is INERT until they are promoted to a full member. It writes the grants map and nothing else — it never touches the skill's text and never moves updatedAt, so it cannot collide with someone editing in the web app or invalidate an expectedUpdatedAt you are holding. The reply carries the skill's ownerId (never a grant — it lives outside the map) and the grants as they now stand.

Destructive write

Delete a workspace skill permanently. There is no undo and no restore, so prefer editing it with save_skill unless the user explicitly wants it gone. Confirm with the user only when their request does NOT identify the skill unambiguously; when the request names it, or you resolved the id from list_skills and it matches what was asked for, that request IS the confirmation. Names may repeat, so when one name resolves to more than one id, ask which before deleting. Only the skill's OWNER (ownerId, the author until ownership moves in the web app) or a workspace admin may delete one.