Skills
Save, share, approve and load reusable instructions (Agent Skills) through the Skill Library operations, and learn what a turn is offered
The Skill Library keeps the reusable instructions people write for Cortex: a
skill is a folder in the Agent Skills format, which in this release is a single
SKILL.md. A person saves a skill, improves it in new
versions, shares a version with a team or the whole organization, and loads it
into a conversation turn when it is offered there.
Every operation acts for one person. The platform takes that person, their
organization, their teams, their clearance and the classification a turn runs
at from the verified call, never from your input. A call made for no person is
refused with FORBIDDEN.
import { createHttpPlatformTransport, createScrydonSDK } from '@scrydon/sdk/platform'
const platform = createScrydonSDK(
createHttpPlatformTransport({
baseUrl: 'https://scrydon.com',
headers: () => ({ authorization: `Bearer ${accessToken}` }),
})
)
const saved = await platform.skills.create({
skillMd: '---\nname: board-memo\ndescription: House style for board memos\n---\n# Board memo\n…',
changeNote: 'First version',
idempotencyKey: 'board-memo-v1',
})
const shared = await platform.skills.share({
versionId: saved.versionId,
target: { kind: 'team', teamId: '6f1c…' },
idempotencyKey: 'board-memo-v1-finance',
})
// shared.outcome is 'live' or 'pending'Operations
Every operation is a POST. Reads need the skills:read scope, and writes need
skills:write. The table is generated from the SDK's operation registry.
| Operation | HTTP | Scope | What it does |
|---|---|---|---|
skills.offered.list | POST /api/platform/v1/skills/offered/list | skills:read | Lists the skills this call may load: at the classification of the room named by roomId, else at the classification the call runs at. Never returns a body. Records nothing. |
skills.load | POST /api/platform/v1/skills/load | skills:read | Loads one offered skill: its SKILL.md, fingerprint, requested tools and file list, and for a skill that runs code its folder. Checks the skill against the offer first, and records the load in the Audit Log. |
skills.library.list | POST /api/platform/v1/skills/library/list | skills:read | One tab of your library (mine, groups or organization), one page at a time. |
skills.get | POST /api/platform/v1/skills/get | skills:read | One skill: its summary, the versions you may read, and the grants that follow a version you may read. |
skills.versions.get | POST /api/platform/v1/skills/versions/get | skills:read | One version in full: SKILL.md, fingerprint, files, checks, classification and the approvals it received. |
skills.create | POST /api/platform/v1/skills/create | skills:write | Saves a new skill as version 1. You are its author. |
skills.versions.create | POST /api/platform/v1/skills/versions/create | skills:write | Saves a new version of your own skill. baseVersionId must be its latest version. |
skills.imports.preview | POST /api/platform/v1/skills/imports/preview | skills:write | Reads an upload (a zip, a tar.gz, or a folder's files) and lists each skill it holds as ready, refused or blocked. Saves nothing. |
skills.imports.commit | POST /api/platform/v1/skills/imports/commit | skills:write | Saves the ready skills you name from an upload into your own skills, each as version 1. All of them are saved, or none. |
skills.drafts.generate | POST /api/platform/v1/skills/drafts/generate | skills:write | Drafts a new skill, or a change to one of yours, from a short conversation excerpt, through your organization's language model. Send the room's roomId and the model call runs at least at that room's classification. Saves nothing. |
skills.drafts.save | POST /api/platform/v1/skills/drafts/save | skills:write | Saves your unsaved draft: one per skill, and one for a new skill. Send the room's roomId when the draft is kept in a room. |
skills.drafts.get | POST /api/platform/v1/skills/drafts/get | skills:read | Reads that draft back, with the roomId it was kept in. |
skills.drafts.delete | POST /api/platform/v1/skills/drafts/delete | skills:write | Discards that draft. deleted is false when there was none. |
skills.fork | POST /api/platform/v1/skills/fork | skills:write | Copies a version of someone else's skill into your own skills as version 1, linked to where it came from. |
skills.share | POST /api/platform/v1/skills/share | skills:write | Shares a version with a team or the organization. The share goes live at once or opens a request; dryRun tells you which and writes nothing. |
skills.requests.list | POST /api/platform/v1/skills/requests/list | skills:read | The share requests you may decide, and the recent live shares into teams you administer. |
skills.requests.decide | POST /api/platform/v1/skills/requests/decide | skills:write | Approves or declines a share request. |
skills.grants.pullBack | POST /api/platform/v1/skills/grants/pull-back | skills:write | Pulls back a share: the team or organization goes back to the version it followed before, or loses the skill when there was none. |
skills.bundles.get | POST /api/platform/v1/skills/bundles/get | skills:read | An agent's pinned skills: each pin's version, whether it is still offered, and a newer version you could move it to. bundle is null before the first pin. |
skills.bundles.pin | POST /api/platform/v1/skills/bundles/pin | skills:write | Pins a version of a skill you are offered on an agent. Pinning the same version again changes nothing. |
skills.bundles.update | POST /api/platform/v1/skills/bundles/update | skills:write | Moves a pinned skill to another version you are offered, such as its newer one. A pin never moves by itself. |
skills.bundles.unpin | POST /api/platform/v1/skills/bundles/unpin | skills:write | Takes a skill off the agent. Unpinning a skill that is not pinned changes nothing. |
skills.bundles.detach | POST /api/platform/v1/skills/bundles/detach | skills:write | Gives the agent its own copy of a list it shares with other agents, so changes to it stop reaching them. |
skills.bundles.rename | POST /api/platform/v1/skills/bundles/rename | skills:write | Names the agent's list, or clears its name. A list several agents share needs a person who may change every one of them. |
skills.bundles.attach | POST /api/platform/v1/skills/bundles/attach | skills:write | Gives an agent a list another agent already holds, so both use it. Every pin on it must be one you are offered. A list without a name needs a name. Attaching the list the agent already holds changes nothing. |
skills.admin.library.list | POST /api/platform/v1/skills/admin/library/list | skills:read | Organization admins only. Every skill of the organization that was ever shared, at the newest shared version your clearance covers, with its shares, any waiting request and its uses this month. |
skills.admin.requests.list | POST /api/platform/v1/skills/admin/requests/list | skills:read | Organization admins only. Every share request of the organization, newest first, each saying in canDecide whether you may decide it. |
skills.admin.loads.list | POST /api/platform/v1/skills/admin/loads/list | skills:read | Organization admins only. One skill's loads, newest first: when, who for, which version, why, and the room's classification, for each version you may read. |
skills.admin.bundles.list | POST /api/platform/v1/skills/admin/bundles/list | skills:read | Organization admins only. Every agent's skill list that an agent holds, newest first, with the agents holding it and its pins. Read-only. |
skills.create, skills.versions.create and skills.fork need an
idempotencyKey, and so does skills.share unless it is a dryRun. The same
key with the same body, from the same person, returns the first result and
writes nothing more. The same key with a different body, or from another
person, is refused with idempotency_key_reused. Deciding a request twice the
same way returns its current state.
The skills.bundles.* writes take no key: sending one again leaves the agent's
list as the first one did.
Availability
The Skill Library needs its store in your deployment. When it is not there,
every skills.* operation answers CAPABILITY_NOT_CONFIGURED (HTTP 409) and
does nothing.
Who may do what
| Action | Who |
|---|---|
| Read a skill and its versions | Its author; the members of a team the skill is shared with; every member when it is shared with the organization; the admins of a team it waits for approval in; and organization admins, for any skill that was ever shared or put up for sharing. A skill that was never shared is visible to its author only. In every case your clearance must cover the version's classification. |
| Save a skill, or a new version | The author only. To improve someone else's skill, fork it into your own skills. |
| Share with a team | The author, with any team in the organization. |
| Share with the organization | The author, by request. An organization admin who is not the requester approves it. |
| Approve or decline a team request | That team's admins. When the team has no admin, an organization admin who did not make the request. |
| Give a second approval | An organization admin other than the first approver and the requester. |
| Pull back a share | The team's admins, organization admins, or the author. |
When a share goes live
skills.share answers outcome: 'live' when the team follows the version at
once, and 'pending' when it waits for approval. The first rule that matches
decides, and reasons lists what applied:
- The target is the organization: one organization admin approves (
organization). - The version runs code: one team admin approves, and a second approver too when your organization requires one (
runs_code). - A check flagged something, such as hidden characters or text your data-loss prevention matched: one team admin approves (
checks_flagged). - Your organization requires approval to share with a team (
approval_required), or your deployment does (nato_floor): one team admin approves. - Otherwise the share is live at once. The team's admins see it in their requests and can pull it back.
A team admin who shares into their own team approves the share by making it. A second approver, when rule 2 needs one, is still required.
A new version does not move a team by itself. Saving touches no grant: the team keeps the version it follows until the new one is shared with it, and approved when an approval is needed.
Classification
Each version carries a classification from your organization's scheme.
- Saved from a conversation. Send the room's
roomId. The platform reads the room's classification itself and checks that you are a member, and the version takes that classification. Do not send aclassificationas well: the pair is refused withroom_save_classified. - Written anywhere else. Send a
classification, or leave it out to use your organization's unlabelled-data classification.
skills.drafts.generate takes a roomId too, for the room the excerpt came
from. The platform reads that room's classification the same way, and the
language model call runs at the higher of it and the classification the call
runs at. A room classified under another scheme than the call is refused with
scheme_mismatch.
skills.versions.get also returns the version's dependencies: one entry per
package a requirements.txt or package.json in the skill declares, with its
ecosystem (pypi or npm), name, spec, whether it is pinned, and the
path of the file that declares it. An unpinned dependency also appears in the
version's checks. dependencies is left out by a platform that predates it,
which means the list was not reported, not that there is none. Upgrade the
SDK with or before the platform: results are checked strictly, so an SDK
older than the platform refuses a version that carries dependencies.
You cannot save a version above your own clearance (above_clearance). Every
read, decision and load checks that your clearance covers the version.
The SKILL.md is checked by your organization's data-loss prevention when it is
saved. A match your policy blocks refuses the save with POLICY_BLOCKED and
details.policyCode LLM_BLOCKED_BY_DLP. A match your policy only reports is
saved, flagged in the version's checks, and recorded in the Audit Log; sharing
it then needs a team admin. Sharing does not scan again, and a fork keeps the
checks of the version it copies.
A version saved with skills.versions.create below an earlier version of the
same skill is saved and flagged classification_below_version
(SKILL_CHECK.CLASSIFICATION_BELOW_VERSION). The flag carries the new rank,
and the versionNumber and versionRank of the earlier version with the
highest rank in the same classification scheme. Sharing it then needs a team
admin, like any flagged version. Versions an extension writes are not
compared. A client that parses checks with an SDK that predates this
flag rejects a version that carries it, so update the SDK before the platform.
What a turn is offered
skills.offered.list and skills.load work at the classification the call
runs at: the one it asserts, or your organization's unlabelled-data
classification when it asserts none. You never send it in the body.
A screen that lists skills for a room, such as Cortex's / palette, sends that
room's roomId to skills.offered.list instead. The platform reads the room's
classification itself, as you, and computes the offer at it; the result's
classification says which. A room you are not a member of is refused with
not_room_member, and a room whose label cannot be read with
room_band_unreadable: neither falls back to a default. skills.load takes no
roomId. A turn in that room loads at the room's classification, so a skill the
room was offered is loadable by the turn, unless the room's classification
changed in between.
A person is offered:
- their own skills, at the latest version;
- each version their teams follow;
- the version the organization follows.
Then, in this order:
- Anything the turn may not load is dropped: an archived skill, a version under another classification scheme, a version above the turn's classification, and a version your clearance does not cover. When your organization turns personal skills off, your own skills reach you only through a share. Then a skill you forked is dropped, but only while your fork is offered to the turn, because your fork stands in for it. That includes a fork that reaches you only through a team or the organization you shared it with. A fork the turn may not load hides nothing, so you are offered the original.
- One version per skill is kept: your own, else the higher version number, else a team's before the organization's. A version dropped in step 1 never hides one that is allowed, so you still get your team's version 7 when your own version 9 is above the turn.
- Each skill gets a handle, its
name. Two offered skills with the same name each get their origin as a suffix, such assar-narrativeandsar-narrative-fincrime. querynarrows the list by name, title and description. It is sorted by title, andlimitcaps it (25 by default, 50 at most).
skills.load re-runs the same offer for the call and refuses a skill that is
not in it with not_offered. It checks the whole offer, not one page of it, so
any skill a search could find can be loaded. Pass versionId to require the
exact version you were offered.
Skills that run code
A version runs code when it has a file under scripts/ or a script file such as
.py or .sh. It is offered only to an agent turn that can run it, and only
when all of these hold:
- your organization's skills policy allows scripts (
scriptsAllowed), and the version's classification is at or underscriptsMaxRank; - the call comes from an agent turn that runs in the microVM sandbox with its sandbox tools. The platform's agent runtime signs this on the call; no application can assert it, and a call from anywhere else, Cortex included, is never offered a skill that runs code;
- the version can run: its folder is stored, and its checks carry no
not_runnableflag.
Anywhere else skills.load refuses it with not_runnable, and the message
says which condition failed, for example This skill runs code that may not run here: this step does not run on the microVM tier with the sandbox tools. A
version you could not have been offered anyway is still refused with
not_offered. A / palette still lists it, last, so it can be shown as
unavailable.
A version saved before skills could run code is judged when it is loaded: a
folder over 2 MiB, or a dependency not locked by hash, is refused with
not_runnable and the file at fault, and nothing is loaded.
A version that runs code is checked when it is saved. Its checks carry
not_runnable (SKILL_CHECK.NOT_RUNNABLE), with a code from
SKILL_RUN_REFUSALS and the path of the file at fault, when it cannot run:
code | Why |
|---|---|
too_large_to_run | The folder is over 2 MiB. |
dependencies_not_locked | A dependency is not locked by hash: a requirements.txt line without == and a --hash=sha256:, or an option line such as -r; a package.json that declares dependencies or optionalDependencies without a package-lock.json (version 2 or later) beside it naming each one with an integrity hash. |
Such a version cannot be shared or approved (not_runnable).
A file that runs and fetches a package itself is flagged too, as
runtime_install (SKILL_CHECK.RUNTIME_INSTALL), with the path, the 1-based
line and the command of the first such command in each file, such as
pip install or npx. It is a flag for the person who approves the skill, not
a refusal, and it is a text match: a command a script builds while it runs is
not found, and the sandbox reaches whatever package registries your
organisation's egress policy allows.
A load of a version that runs code answers folder: every file of the folder,
{ path, data } with the bytes base64, in path order. The files hash to
digest, and the agent's sandbox checks that before it writes them, read-only,
then installs the locked dependencies itself (pip install --require-hashes,
bun install --frozen-lockfile --ignore-scripts). folder is absent for a
version that only instructs.
When your organization sets a dependency mirror (Cortex skills settings, under
Advanced), folder also carries dependencyMirror: pythonIndexUrl,
npmRegistryUrl, or both, each an https URL without credentials, a query or a
fragment. The sandbox
installs from those instead of the public indexes and still checks every hash in
the lock. They reach the installer's command line, never the environment of a
script the skill runs.
An agent's pinned skills
An agent in Cortex can be given skills of its own: a list of pinned versions it
is offered in every room, whoever talks to it. A workflow's Agent block can be
given the same. The skills.bundles.* operations name the agent as agent:
{ kind: "persona", matrixUserId } for a Cortex agent, by its Matrix user id,
or { kind: "workflow", workflowId } for the workflow whose Agent blocks hold
the list.
- Anyone who may open the agent reads its list. For a workflow, that is
anyone who may read the workflow; anyone else is answered
not_found, as if there were no such agent. Each pin says who pinned it and when, itsstate,runsCode, andnewer: the highest version you are offered above the pinned one, ornull. - Changing the list needs a person who may change the agent's workflow.
The platform asks the workflow's owner on each write. A workflow in a
read-only environment is refused with
environment_read_only. - You pin only what you are offered. For a Cortex agent, send the
roomIdyou pin from: the version must be the one you are offered there, at that room's classification. A workflow has no room, so a workflow pin takes noroomIdand is judged at your own clearance. Anything else is refused withnot_offered. A list holds at most 25 skills. - A skill that runs code can be pinned. Its folder must be able to run, or
the pin is refused with
not_runnable. Where it runs is checked at every load, not when you pin: the agent's step must run on the microVM tier with its sandbox tools, and your organization's skills policy must allow scripts at the version's classification. On any other step the load is refused withnot_runnable, and the run shows why. The pin stays. - A pin stays at its version. When the skill moves on,
newersays so, andskills.bundles.updatemoves the pin. Nothing moves it for you. - A share that is pulled back stops reaching the agent. Its pin reads
no_longer_sharedand is not offered until the skill is shared again. A pin of the pinner's own skill stays offered while your organization allows personal skills. - Several agents can share one list.
skills.bundles.attachgives an agent a list by itsbundleId: you must be able to change that agent, and every pin on the list must be one you are offered at your clearance, or the attach is refused withnot_offered. A list is named when a second agent uses it: an unnamed list needs aname, and a named one is renamed withskills.bundles.rename, not by attaching it. The list the agent held before is kept, held by no agent.sharedWithcounts the others.skills.bundles.detachgives one agent its own copy, and renaming a shared list needs a person who may change every agent holding it.
A workflow's Agent block asks for its offer with an agent_block subject that
names its workflow, its block and the person's picks. It is offered the agent's
pinned skills plus each pick, but a pick only at the exact version that person
is offered: any other pick is dropped. When a skill is both pinned and picked,
the pinned version wins, and the item's origin is bundle with the list's
name as originName. The subject must name the workflow the run was started
for, or it is refused with subject_mismatch.
Your library
skills.library.list reads one tab at a time:
tab | What it lists |
|---|---|
mine | The skills you wrote or forked, at their latest version. |
groups | The skills shared with your teams, one item per share. Each item names its team in teamName, so a skill shared with two of your teams appears twice, and the two can be at different versions. |
organization | The skills shared with the whole organization. |
A fork's forkedFrom says where it came from. Its origin is team when the
source reaches you through a team, named in originName; organization when it
reaches you through the organization; mine when the source is your own; and
null when it no longer reaches you. Read origin, not originName, to tell
them apart: a team may be called anything, "organization" included.
An item's movedAt is set when its share was made, or moved to another
version, in the last seven days. These are the items Cortex lists under "From
your groups this week", also one per share. Keep requesting pages until
nextCursor is null.
Every item has an approval: approved when at least one share of the skill,
with a team or with the organization, is live and not revoked; not_approved
when the skill is private or every share of it is still waiting for a decision.
A share is live once it was approved, or at once when the organization's policy
lets it through without approval. A newer version that waits for approval does
not take approved away from a skill a live share already follows. Items in
groups and organization are shares that are live, so they are always
approved.
Pass approval (approved or not_approved) to list only those skills; leave
it out to list them all. The filter is applied before the page is cut, so a
page is never short because of it. A cursor names a position in the list, not
the filter: send the same approval with it as with the page it came from.
Importing skills
skills.imports.preview and skills.imports.commit bring skills you already
have into your own skills. The upload is one zip or tar.gz, or the files of a
folder, and its decoded bytes are capped at
11 MiB. One import takes at
most 64 skills.
An upload can hold:
- Agent Skills folders: each folder with a
SKILL.mdis one skill, with its other files. - Rule files: a Cursor rule (
.mdc) or a GitHub Copilot instructions or prompt file becomes a skill. Its text goes intoreferences/, and the candidate'sconversionnames the file it came from.
The preview lists every skill the upload holds. A ready one can be imported.
A refused one is not a valid skill, and its refusal says why, in the same
codes a save uses. A blocked one holds text your organization's DLP policy
blocks. Symbolic links and devices are refused.
The commit reads the upload again rather than trusting the preview. Send the
same upload and the folder of each ready skill you want. Each one is saved
as version 1 of a new skill you author, at the classification you send (up
to your own clearance), or at your organization's lowest classification when
you send none. If any one of them cannot be saved, for example because you
already have a skill of that name, nothing is saved. Sharing the imported
skills is a separate step, under the usual rules.
For organization admins
Four reads back the Library, Review, Usage and Bundles pages under Settings → Cortex in
Platform. Each refuses anyone who is not an organization admin with FORBIDDEN,
which carries no details.reason, before anything is read. They show nothing an organization
admin could not already read: a skill that was never shared stays visible to
its author only, and a version above your clearance is left out.
| Operation | Lists | Filters |
|---|---|---|
skills.admin.library.list | One item per skill that was ever shared, at the newest shared version your clearance covers. grants lists the teams and the organization that follow it, pending the request that waits, if any, and usesThisMonth how many turns loaded it this calendar month (UTC), counting only loads of a version that was shared and that your clearance covers. skills.admin.requests.list counts its usesThisMonth the same way. | query matches the name or a shared version's title. status is shared, pending or archived; left out, it lists every skill that is not archived. sort is recent (the default) or uses_this_month, most used first. |
skills.admin.requests.list | Every share request of the organization whose version your clearance covers, newest first, not only the ones you may decide. canDecide is true when skills.requests.decide would accept your decision now. baseVersionId is the version the target follows, to compare against, or null. | status is pending, live (shared without approval) or decided (approved, declined, withdrawn or pulled back); left out, every status. requestId returns that one request, and takes no cursor. |
skills.admin.loads.list | One skill's loads, newest first, all time, one row per load of a version that was shared and your clearance covers. Each row has at, the version (number and digest), the person the turn ran for, the loadTrigger, and the roomRank (null outside a room). agentSubject gives only the kind of agent, and is absent when a person's turn loaded it. | skillId is required. A skill that skills.admin.library.list would not list is refused with details.reason not_found. |
skills.admin.bundles.list | One item per agent's skill list that at least one agent holds, newest first by when it was made. holders names each workflow holding it, its environmentId (or null) and the persona that runs it (its slug and matrixUserId), or null for a workflow no persona runs. pins gives each pinned skill's title, version, state (offered or no_longer_shared, as the agent's turns see it) and runsCode. A pin of a version above your clearance is left out. It never says who pinned what, and changes nothing: pinning needs write access to the agent's workflow, which being an organization admin does not give. | query matches the list's name, ignoring case; a list without a name never matches. |
All four page with cursor and limit. The library is newest first by when the version it shows was saved, so saving a version that was not shared moves nothing, or with sort: uses_this_month most used first, ties by id. Its later pages count the same uses as its first page: the month that page fell in, up to the moment it was read, so a month that turns or a skill used while you page moves nothing, and usesThisMonth on those pages is as of that moment. A cursor works only with the list, and the sort, it was issued for (invalid_cursor). The review is newest first by when the request was made, the loads by when they happened, and the lists by when they were made. None counts the total.
usesThisMonth counts the same versions skills.admin.loads.list lists, those you may read, but one per turn and only this month, while the history lists every load over all time. Older servers refuse sort: send it only to a server that serves skills.admin.loads.list.
Do not build an admin view from skills.library.list. It lists what you
are offered as a member, not what the organization has shared; filtering it on
the client shows an admin the wrong set.
Audit
Saving, importing, forking, sharing, approving, declining, pulling back and loading each
write an Audit Log event that names the skill, the version number and its
fingerprint. See the Audit Log catalogue.
Each change to an agent's pinned skills writes a skill_bundle.* event naming
the list and every workflow holding it; a pin, an update and an unpin also name
the version. A write that changes nothing writes no event. A load by an agent's
turn writes skill.loaded, naming the agent's workflow and block.
Errors
Every failure is a PlatformApiError with a stable code. A refusal by the
Skill Library also carries details.reason, which is stable and safe to branch
on. This table is generated from SKILL_ERROR_REASONS in @scrydon/sdk/platform.
details.reason | Code | HTTP | When |
|---|---|---|---|
stale_base | INVALID_REQUEST | 400 | Another version of the skill was saved first, so baseVersionId is no longer the latest. Start again from the latest version. |
idempotency_key_reused | INVALID_REQUEST | 400 | The idempotencyKey already answered a different request: another body, another operation, or another person. |
invalid_skill | INVALID_REQUEST | 400 | The SKILL.md is not a valid skill. details.refusal says why, for example invalid_frontmatter or skill_md_too_large. |
slug_taken | INVALID_REQUEST | 400 | You already have a skill with this name. A fork keeps the name of what it copies, so this also refuses a fork of a skill whose name you already use. |
slug_changed | INVALID_REQUEST | 400 | A new version keeps its skill's name. Save a renamed skill as a new skill. |
unchanged | INVALID_REQUEST | 400 | The new version is identical to the latest one. |
own_skill | INVALID_REQUEST | 400 | You cannot fork your own skill. Save a new version of it instead. |
above_clearance | FORBIDDEN | 403 | The classification is above your own clearance, so you could not read the version back. |
scheme_mismatch | INVALID_REQUEST | 400 | The classification is not a level of your organization's active classification scheme, or the room a draft names is classified under another scheme than the call. |
not_room_member | FORBIDDEN | 403 | The roomId names a room you are not a member of. |
room_save_classified | INVALID_REQUEST | 400 | A save sent both a roomId and a classification. A save from a room takes the room's classification, so send one or the other. |
room_band_unreadable | FORBIDDEN | 403 | You are in the room, but its classification label cannot be read. The call is refused rather than given a default classification. |
not_found | FORBIDDEN | 403 | The skill, version or share request does not exist, or you may not read it or act on it. The two are not told apart. A share to a team that is not in your organization answers INVALID_REQUEST with the same reason. |
not_offered | FORBIDDEN | 403 | skills.load named a skill, or a version, that this call is not offered. |
already_shared | INVALID_REQUEST | 400 | The team or the organization already follows this version. |
already_decided | INVALID_REQUEST | 400 | The request was already decided: it is closed, or you decided it the other way before. Only someone who could decide the request is told this. |
not_current | INVALID_REQUEST | 400 | A pull back named a share that is not the one its team or organization follows now. |
invalid_cursor | INVALID_REQUEST | 400 | The cursor is not one this list issued. |
classification_required | INVALID_REQUEST | 400 | skills.offered.list or skills.load was called with no classification to offer skills at. |
excerpt_too_large | INVALID_REQUEST | 400 | The conversation excerpt is over the limit skills.drafts.generate accepts. details.maxCharacters gives it. |
mode_mismatch | INVALID_REQUEST | 400 | A draft of a new skill named a skill or a base version. Those belong to a draft that revises a skill. |
skills_policy_invalid | CAPABILITY_NOT_CONFIGURED | 409 | Your organization's skills policy cannot be read as a valid policy. Shares and offers are refused until an administrator corrects it. |
import_unreadable | INVALID_REQUEST | 400 | The upload is not a readable zip, tar.gz or set of files, or it is past the limits one import reads. |
import_empty | INVALID_REQUEST | 400 | The upload holds no skill folder and no rule file. |
import_too_many_skills | INVALID_REQUEST | 400 | The upload holds more skills than one import takes. Import it in parts. |
import_folder_not_ready | INVALID_REQUEST | 400 | A commit named a folder the upload does not hold, or one that is not ready. Preview the upload again. |
environment_read_only | FORBIDDEN | 403 | The agent's workflow lives in a read-only environment. Its pinned skills change only with a deploy. |
runs_code | FORBIDDEN | 403 | No longer returned: an agent can now be given a skill that runs code (see below). Kept so code that matches it still compiles. |
not_runnable | INVALID_REQUEST | 400 | The version runs code that cannot run: its folder is over 2 MiB, or a dependency is not locked by hash. It cannot be shared, approved or pinned; a decline still works. Its checks carry the not_runnable flag that says which. skills.load also answers it for a version that runs code where it may not run this turn; the message names why. |
bundle_full | INVALID_REQUEST | 400 | The agent already has 25 pinned skills. Unpin one first. Moving a pinned skill to another version still works. |
subject_mismatch | FORBIDDEN | 403 | An agent_block subject names another workflow than the one the run was started for, or the call is not a workflow run. |
extension_read_only | INVALID_REQUEST | 400 | The skill comes from an installed extension, which is the only place its versions change. Fork it to change a copy of your own. |
Other failures carry no Skill Library reason:
| Code | HTTP | When |
|---|---|---|
FORBIDDEN | 403 | The call does not carry the operation's scope, or it is made for no person. |
INVALID_REQUEST | 400 | The body fails the contract, for example a SKILL.md over 65,536 characters or a share with no idempotencyKey, or free text (a SKILL.md, a change note, a search query, a share reason, a decision note) holding U+0000 or an unpaired UTF-16 surrogate, which Postgres cannot store. A SKILL.md within that count but over 64 KiB in UTF-8 is refused with invalid_skill instead. |
POLICY_BLOCKED | 422 | Data-loss prevention blocked the SKILL.md on save (details.policyCode LLM_BLOCKED_BY_DLP), or a policy blocked the text skills.drafts.generate sent to the language model. |
PROVIDER_UNAVAILABLE | 503 | A store, the room, the policy or the Audit Log could not be read or written right now. Nothing was recorded as done; retry with the same idempotencyKey. |
import { PlatformApiError, SKILL_ERROR_REASONS } from '@scrydon/sdk/platform'
try {
await platform.skills.versions.create({ skillId, baseVersionId, skillMd, changeNote, idempotencyKey })
} catch (err) {
if (err instanceof PlatformApiError && err.details?.reason === SKILL_ERROR_REASONS.STALE_BASE) {
// Someone saved a newer version first: reload it and apply your change again.
}
}