Skills (Public Beta)

Skills are the authorable execution units used by agents.

Public beta scope: full CRUD, versioning, publish, run, and draft-composition endpoints are available, but behavior may evolve with explicit versioning.

SDK methods

• list({ organizationId }) -> GET /api/skills
• get(skillId, { organizationId }) -> GET /api/skills/:id
• create -> POST /api/skills
• update -> PATCH /api/skills/:id
• createVersion -> POST /api/skills/:id/versions
• publish -> POST /api/skills/:id/publish
• preview -> POST /api/skills/:id/preview
• diff -> GET /api/skills/:id/versions/:versionId/diff
• run -> POST /api/skills/:id/run
• replacePrompts -> POST /api/skill-versions/:id/prompts
• replaceTools -> POST /api/skill-versions/:id/tools

Builder composition helpers

Use createVersion(...) first, then compose the draft skill version with:

• replacePrompts(skillVersionId, { organizationId, prompts })
• replaceTools(skillVersionId, { organizationId, tools })

Prompt composition is the canonical authored shape for skills. Both draft composition helpers are draft-only replace-all mutations, and array order is canonical.

Prompt workflow

Use client.prompts.create(...) with organizationId, promptKey, name, and optional defaultSection.

Create content with client.prompts.createVersion(prompt.id, { organizationId, content }).

Publish reviewed content with client.prompts.publish(prompt.id, { organizationId, versionId }).

Attach the prompt to a draft skill version with client.skills.replacePrompts(skillVersion.id, { organizationId, prompts: [{ promptId, attachmentMode: "floating_latest_published", positionIndex: 0 }] }).

For CLI-managed authoring, declare the prompt in top-level prompts[] and reference it from skills[].promptComposition; prompt-mv apply performs the create/version/publish/attach sequence.

Beta notes

• Skill authoring surfaces are public beta.
• Changes will be versioned and communicated ahead of breaking updates.

See also

• Runs
• Agents