Skip to main content
Skills are instruction packages composed into agent prompts at dispatch time. A skill bundles guidance, optional files and allowed tools, and an activation mode (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): a Skill plus every version-defining field — content, files, allowedTools, toolSets, defaultActivationMode, implicitActivation, maxInstructionTokens, priority, tierFloor, rubric — and fileRoles, inputModes, outputModes, requiresCapabilities, slashCommand and the derived determinism profile.
  • SkillVersion (listVersions): versionId, version, status, synthesisTier, createdAt.
An absent optional value is 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 moves activeVersionId 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 first
  • GET /api/v3/skills/{skillId} — getSkill — fetch one skill by skillId
  • GET /api/v3/skills/{skillId}/versions — listSkillVersions — a skill’s versions, newest first
Writes:
  • POST /api/v3/skills — createSkill — author a workspace skill (409 if the skillId exists)
  • PATCH /api/v3/skills/{skillId} — updateSkill — patch a workspace skill named by id (its skillId)
Skill sets:
  • 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 set
  • DELETE /api/v3/skill-sets/{setId} — deleteSkillSet — deprecate a workspace skill set
  • POST /api/v3/skill-sets/{setId}/members — addSkillSetMember — add a skill to a set
  • DELETE /api/v3/skill-sets/{setId}/members/{skillId} — removeSkillSetMember — remove a skill from a set
A skill set groups skills for assignment: an agent holding a set composes every active member. The set writes need 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 an Idempotency-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

The Forge MCP server lists forge_list_skills; it reaches the other operations in its skills tool group through forge_call_operation with operationId getSkill, listSkillVersions, createSkill and updateSkill.