always or on_demand). Integrations browse the skill catalog and author workspace skills programmatically.
Access
The skill catalog is platform-global: it has no org-unit home.skills:read lets a caller read every skill, and skills:write lets it create and update workspace skills that every caller holding skills:read can then read and assign. Only workspace skills are editable; a write to a builtin, marketplace, clawhub or anthropic skill is 422. A created skill is always a workspace skill: a source in the request body is ignored.
Resource shape
Skill(list items, and the create and update responses):id,skillId,name,description,version,status,owner,tags,emoji,skillType,source,quality,agentCount,assignedAgents({ agentId, name }),createdAt,updatedAt,kind,enabled,activeVersionId,canaryVersionId.SkillDetail(get): aSkillplus every version-defining field —content,files,allowedTools,toolSets,defaultActivationMode,implicitActivation,maxInstructionTokens,priority,tierFloor,rubric— andfileRoles,inputModes,outputModes,requiresCapabilities,slashCommandand the deriveddeterminismprofile.SkillVersion(listVersions):versionId,version,status,synthesisTier,createdAt.
null ([] for tags, {} for files and fileRoles). The creator, principal, synthesis, embedding and usage fields are never returned, nor quality.contentHash; a rubric calibration example carries its subjectHash, never the subject.
Versions and published workflows
Every change to a version-defining field mints an immutable version and movesactiveVersionId to it (for an active skill). A change that touches only operational fields (tags, emoji, owner, status) mints nothing. A published workflow node pins the skill version that was active when it was published and keeps composing that version’s content after the skill changes; an unpinned node composes the current head.
status (and enabled) are live controls outside version identity: setting a skill’s status to anything but active removes it from every workflow at once, pinned or not. A status publishes or archives the skill, so an update that carries status also needs skills:manage at the platform scope, as the Console’s publish and remove do. Without it the answer is 403 permission_denied naming skills:manage, and nothing is written. Other fields still need only skills:write.
Operations
Reads:GET /api/v3/skills— listSkills — page the catalog, oldest firstGET /api/v3/skills/{skillId}— getSkill — fetch one skill byskillIdGET /api/v3/skills/{skillId}/versions— listSkillVersions — a skill’s versions, newest first
POST /api/v3/skills— createSkill — author a workspace skill (409if theskillIdexists)PATCH /api/v3/skills/{skillId}— updateSkill — patch a workspace skill named byid(itsskillId)
GET /api/v3/skill-sets— listSkillSets — active skill sets and their member skills (skills:read)POST /api/v3/skill-sets— createSkillSet — create a workspace skill set (skills:manage)PATCH /api/v3/skill-sets/{setId}— updateSkillSet — rename or redescribe a workspace skill setDELETE /api/v3/skill-sets/{setId}— deleteSkillSet — deprecate a workspace skill setPOST /api/v3/skill-sets/{setId}/members— addSkillSetMember — add a skill to a setDELETE /api/v3/skill-sets/{setId}/members/{skillId}— removeSkillSetMember — remove a skill from a set
skills:manage at the platform scope, and a membership change reaches every holding agent at its next dispatch. They are reached from MCP through forge_call_operation.
Paging
limit (1–100, default 50; a larger value is 400 too_big) and cursor page the catalog behind a unique keyset cursor, so a skill is never skipped or repeated across pages. Follow meta.nextCursor until meta.hasMore is false. listVersions pages a skill’s versions newest first (limit 1–100, default 50): continue while meta.hasMore is true, passing meta.nextCursor as cursor with the same other parameters; a page may be short while more remain, and the list never answers meta.partial. A malformed limit is 400 Invalid: limit on the catalog and 400 limit must be a positive integer on listVersions; a malformed cursor is 400 Invalid cursor on both.
Retrying a write
Send anIdempotency-Key header with create or update. A same-key repeat of a completed write returns the recorded response with Idempotency-Replayed: true while the caller still holds skills:write (and skills:manage, when the repeated update carries a status), and never writes twice (see Idempotency).
Common workflow
forge_list_skills; it reaches the other operations in its skills tool group through forge_call_operation with operationId getSkill, listSkillVersions, createSkill and updateSkill.
Related
- Skills overview — conceptual background on the skills system
- Native HTTP quickstart — call these endpoints with
fetchand a bearer token

