Skills API

Skills are reusable capability packs that the gateway can expose to agents. Pioneer skills are compatible with the Agent Skills specification, but installation and policy are managed by the gateway so every client connected to that gateway sees the same catalog. The skills protocol has three jobs: move a skill archive to the gateway, install/update/uninstall the skill, and control whether agents may use it implicitly. Explicit per-turn use is represented through turn/start.capabilities. Every installed skill has a stable skill_id that is separate from its slug, display name, source path, and current pack membership. Clients should use skill_id for updates, uninstall, policy changes, health operations, and capability references. A pack rename, source move, or pack update can change names and membership without changing the identity of a retained skill.

Methods

Method	Params	Result	Purpose
`skills/list`	`SkillListParams`	`SkillListResponse`	List installed skills and optional health/policy state.
`skills/upload/start`	`SkillsUploadStartParams`	`SkillsUploadStartResponse`	Start an archive upload session.
`skills/upload/finish`	`SkillsUploadFinishParams`	`SkillsUploadFinishResponse`	Finalize an upload session.
`skills/upload/abort`	`SkillsUploadAbortParams`	`SkillsUploadAbortResponse`	Abort an upload session.
`skills/install`	`SkillsInstallParams`	`SkillsInstallResponse`	Install a skill from a finished upload.
`skills/update`	`SkillsUpdateParams`	`SkillsUpdateResponse`	Replace an installed skill from a finished upload.
`skills/uninstall`	`SkillsUninstallParams`	`SkillsUninstallResponse`	Remove an installed skill.
`skills/pack/install`	`SkillsPackInstallParams`	`SkillsPackInstallResponse`	Install a pack and its member skills as one lifecycle operation.
`skills/pack/update`	`SkillsPackUpdateParams`	`SkillsPackUpdateResponse`	Update a pack while preserving retained member identities.
`skills/pack/uninstall`	`SkillsPackUninstallParams`	`SkillsPackUninstallResponse`	Remove a pack and its managed members as one operation.
`skills/health`	`SkillsHealthParams`	`SkillsHealthResponse`	Inspect validation, dependency, trust, and audit state.
`skills/policy/list`	`SkillsPolicyListParams`	`SkillsPolicyListResponse`	List workspace policy overrides.
`skills/policy/set`	`SkillsPolicySetParams`	`SkillsPolicySetResponse`	Enable/disable a skill or implicit invocation.

Listing skills

{
  "jsonrpc": "2.0",
  "id": "aaaaaaaaaaaaaaaaaaaaa",
  "method": "skills/list",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "include_health": true,
    "include_policy": true
  }
}

Response shape:

{
  "snapshot_version": 12,
  "generated_at": 1777900000,
  "skills": [
    {
      "slug": "documents",
      "source_kind": "workspace",
      "display_name": "Documents",
      "description": "Work with document files.",
      "version": "0.1.0",
      "fingerprint": "sha256:...",
      "trust_level": "trusted",
      "install": {
        "managed": true,
        "installed": true,
        "install_path": "/path/on/gateway",
        "updated_at": 1777900000
      },
      "policy": {
        "enabled": true,
        "allow_implicit_invocation": false
      },
      "health": {
        "status": "ok",
        "dependency_failures": [],
        "security_blocks": [],
        "validation_issues": []
      },
      "status": "ready"
    }
  ]
}

Use snapshot_version as an invalidation aid. When the gateway sends skills/changed, refresh the list and replace the local catalog.

Policy model

Skills have two separate policy switches:

Field	Meaning
`enabled`	Whether the skill can be used at all. Disabled skills stay installed but are not exposed to agents.
`allow_implicit_invocation`	Whether the gateway may include the skill as an automatically available capability. When false, the skill can still be selected explicitly by the user or client flow.

This split matters for client UX. “Installed” is not the same as “available to agents”, and “available explicitly” is not the same as “agent may decide to use it on its own”. Newly installed skills default to enabled but not implicit unless policy is changed after install. Clients should make explicit use available through the composer or another turn/start.capabilities flow instead of flipping implicit invocation automatically. Pack methods return the pack projection, deterministic member changes, and lifecycle audit information. Treat the operation as atomic from the UI perspective: refresh the catalog from the returned snapshot or the subsequent skills/changed notification rather than merging individual member updates optimistically.

Upload flow

Skill installation starts with a compressed archive upload. The supported archive format is currently tar_gz.

{
  "jsonrpc": "2.0",
  "id": "bbbbbbbbbbbbbbbbbbbbb",
  "method": "skills/upload/start",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "file_name": "documents.tar.gz",
    "archive_format": "tar_gz",
    "compressed_size_bytes": 73422,
    "uncompressed_size_hint_bytes": 240000,
    "sha256": "9f86d081884c7d659a2feaa0c55ad015..."
  }
}

Response:

{
  "upload_id": "upl_000000000000000001",
  "recommended_chunk_size_bytes": 1048576,
  "max_chunk_size_bytes": 4194304,
  "max_compressed_size_bytes": 104857600,
  "max_uncompressed_size_bytes": 524288000,
  "expires_at_unix": 1777900300
}

After this response, chunks are not sent as JSON-RPC requests. They are sent as binary WebSocket frames on the same authenticated connection.

Binary chunk frame

A skill upload chunk frame has this layout:

Bytes	Content
`0..4`	Magic bytes: `PSU1`
`4..8`	Big-endian `u32` header length.
next `header_len`	UTF-8 JSON `SkillsUploadChunkHeader`.
remaining bytes	Raw archive chunk bytes.

Chunk header:

{
  "workspace_id": "ws_000000000000000001",
  "upload_id": "upl_000000000000000001",
  "offset": 0,
  "len": 1048576,
  "chunk_sha256": "optional-chunk-hash"
}

The gateway acknowledges chunks with a notification:

{
  "jsonrpc": "2.0",
  "method": "skills/upload/chunk_ack",
  "params": {
    "upload_id": "upl_000000000000000001",
    "offset": 0,
    "len": 1048576,
    "received_bytes": 1048576,
    "next_offset": 1048576
  }
}

Clients should use next_offset for resumable upload UI and retry from the acknowledged offset after reconnect.

Finishing or aborting upload

{
  "jsonrpc": "2.0",
  "id": "ccccccccccccccccccccc",
  "method": "skills/upload/finish",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "upload_id": "upl_000000000000000001"
  }
}

Response:

{
  "upload_id": "upl_000000000000000001",
  "status": "ready",
  "sha256": "9f86d081884c7d659a2feaa0c55ad015...",
  "compressed_size_bytes": 73422
}

If the user cancels before install, call skills/upload/abort with workspace_id and upload_id.

Installing a skill

Installation consumes a finished upload. The only lifecycle source currently accepted by the public protocol is uploaded_archive.

{
  "jsonrpc": "2.0",
  "id": "ddddddddddddddddddddd",
  "method": "skills/install",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "source": {
      "type": "uploaded_archive",
      "upload_id": "upl_000000000000000001"
    },
    "target_source_kind": "workspace"
  }
}

Response:

{
  "status": "installed",
  "skill": {
    "slug": "documents",
    "source_kind": "workspace",
    "version": "0.1.0",
    "fingerprint": "sha256:...",
    "trust_level": "trusted",
    "install_path": "/path/on/gateway"
  },
  "audit": {
    "events_written": 3
  }
}

Use skills/update for replacing an existing skill. It accepts slug, source_kind, source, and optional expected_previous_fingerprint for optimistic concurrency. After install, use skills/policy/set only when changing policy. The default explicit-only state is enough for composer selection.

Setting policy

{
  "jsonrpc": "2.0",
  "id": "eeeeeeeeeeeeeeeeeeeee",
  "method": "skills/policy/set",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "skill_slug": "documents",
    "source_kind": "workspace",
    "enabled": true,
    "allow_implicit_invocation": false
  }
}

Omit a field when you want to keep its current value. For example, toggling only implicit invocation should send allow_implicit_invocation without enabled.

Health

skills/health is for detailed diagnostics. Pass an empty skills array to inspect all skills, or pass exact { slug, source_kind } targets.

{
  "jsonrpc": "2.0",
  "id": "fffffffffffffffffffff",
  "method": "skills/health",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "skills": [
      { "slug": "documents", "source_kind": "workspace" }
    ],
    "audit_limit": 16
  }
}

Health responses include dependency diagnostics, security findings, validation issues, trust-gate decisions, and recent audit events. Clients should surface blocking diagnostics before letting a user assume a skill is ready.

Notifications

Event	Meaning
`skills/changed`	Installed skills or policy changed; refresh `skills/list`.
`skills/upload/chunk_ack`	Upload chunk was accepted; continue from `next_offset`.

Skills are scoped by gateway and workspace. A skill installed on one remote gateway is not available on another gateway until it is installed there too.

Introduction

Workspace & Threads

Features

Methods

Listing skills

Policy model

Upload flow

Binary chunk frame

Finishing or aborting upload

Installing a skill

Setting policy

Health

Notifications

​Methods

​Listing skills

​Policy model

​Upload flow

​Binary chunk frame

​Finishing or aborting upload

​Installing a skill

​Setting policy

​Health

​Notifications

Methods

Listing skills

Policy model

Upload flow

Binary chunk frame

Finishing or aborting upload

Installing a skill

Setting policy

Health

Notifications