Skip to main content

​
What is a Skill?

A Skill packages your team’s method for a repeatable deliverable — call prep, discovery scripts, battlecards, one-pagers, QBR decks — as instructions an AI assistant can load and follow. Skills use the Anthropic Agent Skills format: a root SKILL.md with the instructions, plus optional bundled reference files the instructions point to. The difference from a prompt in a doc somewhere: Skills live in Octave, so every assistant connected to your workspace — Claude, Cursor, or anything else speaking MCP — discovers the same skills, follows the same current version, and your team’s method improves in one place.

​
Progressive disclosure

Skills load in three levels, so assistants read only what the task needs:
  1. Discovery — find_skill matches a task description against skill names and descriptions; list_skills browses the catalog. Neither loads any instructions.
  2. Instructions — get_skill loads the SKILL.md body plus a listing of bundled files.
  3. Reference files — get_skill_file reads one bundled file, only when the instructions call for it.
This keeps context lean: an assistant prepping a call loads the call-prep skill, not your entire methodology.

​
Skill lifecycle

Skills have a draft → published lifecycle and can be deactivated. Assistant discovery defaults to published, active skills. The REST list endpoint also defaults to that selection, but callers can explicitly filter status and active to audit drafts or inactive skills. Each skill’s folder is stored as a managed Asset (type skill). The Skill API keeps the searchable registry and the stored files in sync, which is why skill files are edited through the Skill API rather than the generic asset surface.

​
Managing Skills via API

  • GET /api/v2/skill/list — list skills, with status and text filters
  • GET /api/v2/skill/get — load a skill by oId or exact name, including its SKILL.md body and file listing
  • GET /api/v2/skill/file — read one bundled file
  • POST /api/v2/skill/find — find the best-matching skill for a task description
  • POST /api/v2/skill/create / POST /api/v2/skill/update / POST /api/v2/skill/delete — manage skills
The same operations are available to assistants through the MCP skill tools.

​
Running a skill

The Runs API executes a skill in the background and produces hosted Assets. Identify a workspace skill by its skl_ oId or a catalog skill by its name, such as deal-coach.
  • POST /api/v2/skills/{key}/runs — start with a natural-language request, optionally an items array of up to 200 lines. The request applies to each item. Optional callbackUrl, delivery, and idempotencyKey control delivery and retries of the submission.
  • GET /api/v2/runs/{oId} — read status, counts, credits, and paginated item outputs. Poll every 10–30 seconds; follow hasNext with itemsOffset and itemsLimit to read all items.
  • POST /api/v2/runs/{oId}/cancel — prevent unstarted items from running. Items already running finish and are charged; cancelling a finished run has no effect.
Start returns run and started. A repeated idempotencyKey returns the earlier run with started: false. Terminal statuses are succeeded, partial, failed, and cancelled. Each skill item is billed at the skill’s base price when its document is published, plus research tools as used, up to 1,000 credits per item. Inspect the run’s quoted, held, and charged credits. See Run a skill for the complete schema.