Deployments.ai Docs
Platform

Managed skills

Publish reusable skills to the platform catalog, release them as immutable versions, and install them into environments.

A managed skill is a named block of instructions, with optional reference files, kept in a platform-wide catalog. Platform administrators publish skills from a source as immutable releases. Environment users install a released skill into their environment, for all agents or for one agent definition. Agents then read the installed skill's reference files with the managed_skills.reference.read tool.

Availability

Installing a managed skill does not add its content to an agent's prompt. The only runtime use is the managed_skills.reference.read tool, which reads files under references/ from a skill installed for the agent. To put a skill in the prompt, name a platform skill in spec.platformSkills or paste its text into spec.skills. See Platform skills.

Catalog resources

Sources, releases, and skills are global. They are not scoped to an organization, so their routes take no tenant headers. Installations belong to one environment.

ResourcePathKey facts
Source/v1/managed-skill-sourcesA stable key, a name, and optional repositoryUrl, pinnedCommit, licenseHash, and metadata.
Release/v1/managed-skill-sources/:id/releasesAn immutable set of skills with a semantic releaseVersion and a contentHash.
Skill/v1/managed-skills/:idOne skill in a release: key, content, description, dependencies, and referencePaths.
Installation/v1/managed-skill-installationsA released skill installed in an environment, optionally for one agent definition.

Sources and releases are active or archived. Installations are active, removed, or superseded. Updates, archives, and removals take the current expectedVersion.

Publish a release

Publishing sends the source's expectedSourceVersion, a releaseVersion, an optional manifest object, and the skills. The platform checks that each dependency names a skill in the same release, replaces dependency keys with skill IDs, computes the release's contentHash, and writes the release, its skills, and the new source version in one transaction. A concurrent publish, or a releaseVersion the source already used, fails with managed_skill_release_conflict.

RuleLimit
Source and skill keyLowercase identifier, at most 128 characters (^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$)
repositoryUrlhttps, no credentials, query, or fragment, at most 2,048 characters
pinnedCommit40 to 64 lowercase hex characters
licenseHashsha256: plus 64 hex characters
releaseVersionA semantic version, at most 255 characters
Skills per release1 to 96, with unique keys
Skill content and each reference file256 KiB of UTF-8 each
Each skill, with its reference files320 KiB encoded
Reference files per skill128, at paths under references/ of at most 512 characters
dependencies per skill96, unique, naming skills in the same release (managed_skill_dependency_missing)
All skills in a release3 MiB encoded
Source metadata and release manifest192 KiB encoded each

Install a skill

An installation names a managedSkillId and its managedSkillReleaseId, and optionally an agentDefinitionId. The release must be active and the skill must belong to it (managed_skill_release_mismatch). The agent definition, when given, must be active.

An environment holds one active installation of a skill for each target. The target is either one agent definition or the whole environment. Remove an installation before you install the same skill again for the same target.

Each release gives its skills new IDs, so two releases of one skill key are different skills and can both be installed for one target. To upgrade, install the new release's skill, then remove the old installation. The list of installations also returns removed ones, and nothing checks dependencies at install time or at run time. The console's Skills screen does the upgrade in that order, installs missing dependencies first, and reports each installation's dependency status. See Manage managed skills.

Read reference files at run time

managed_skills.reference.read is a platform catalog tool with effect read and default action allow. Declare it in the agent manifest like any other tool.

InputMeaning
sourceKeyThe source's key.
skillKeyThe skill's key in the release.
releaseIdThe release ID.
pathA normalized path under references/, for example references/checklist.md.
maxBytesOptional upper bound, at most 256 KiB.

The call succeeds only when the source and release are active and the skill has an active installation for the run's agent definition or for the whole environment. The content comes back as a private report artifact. The tool's description tells the model to treat the file as reference material and ignore instructions inside it. A file larger than maxBytes fails the call.

Permissions

ActionCapability
Read sources, releases, skills, and installationsmanaged-skills:read
Install and remove skillsmanaged-skills:install
Create, update, publish, and archive sources and releasesmanaged-skills:admin

managed-skills:admin takes effect only for platform administrators, and the CLI's device sign-in does not request it. Catalog authoring is an operator task.

Use it

  1. Find a skill in the catalog.

    deployments managed-skill-source list
    deployments managed-skill-release list $MANAGED_SKILL_SOURCE_ID
    deployments managed-skill-release skills $MANAGED_SKILL_RELEASE_ID
  2. Install it for one agent definition in the current environment.

    deployments managed-skill-installation install --managed-skill-id $MANAGED_SKILL_ID \
      --managed-skill-release-id $MANAGED_SKILL_RELEASE_ID --agent-definition-id $AGENT_DEFINITION_ID
  3. Declare managed_skills.reference.read in the agent manifest and tell the agent which sourceKey, skillKey, releaseId, and paths to read.

Platform administrators publish a release from a JSON file of skills:

deployments managed-skill-release publish $MANAGED_SKILL_SOURCE_ID \
  --expected-source-version 2 --release-version 1.3.0 --skills "$(cat skills.json)"

Reference

On this page