---
title: "Install a skill"
method: POST
path: "/api/v1beta/skills"
tags: ["skills"]
---

# Install a skill

`POST /api/v1beta/skills`

Install a skill from a remote source

## Request body

- union
  - object
  - PkgApiV1InstallSkillRequest — Request to install a skill
    - `clients` string[] — Clients lists target client identifiers (e.g., "claude-code"), or ["all"] to target every skill-supporting client. Omitting this field installs to all available clients.
    - `force` boolean — Force allows overwriting unmanaged skill directories
    - `group` string — Group is the group name to add the skill to after installation
    - `name` string — Name or OCI reference of the skill to install
    - `project_root` string — ProjectRoot is the project root path for project-scoped installs
    - `scope` 'user' | 'project' — Scope for the installation
    - `version` string — Version to install (empty means latest)

## Response `201`

Created

- PkgApiV1InstallSkillResponse — Response after successfully installing a skill
  - `skill` GithubComStacklokToolhivePkgSkillsInstalledSkill — InstalledSkill contains the full installation record.
    - `clients` string[] — Clients is the list of client identifiers the skill is installed for. TODO: Refactor client.ClientApp to a shared package so it can be used here instead of []string.
    - `dependencies` GithubComStacklokToolhivePkgSkillsDependency[] — Dependencies is the list of external skill dependencies.
      - `digest` string — Digest is the OCI digest for upgrade detection.
      - `name` string — Name is the dependency name.
      - `reference` string — Reference is the OCI reference for the dependency.
    - `digest` string — Digest is the OCI digest (sha256:...) for upgrade detection.
    - `installed_at` string — InstalledAt is the timestamp when the skill was installed.
    - `managed` boolean — Managed indicates this install is tracked in the project's toolhive.lock.yaml. Only ever true for project-scoped installs. No omitempty: false is an observable state (unmanaged), not an absence.
    - `metadata` GithubComStacklokToolhivePkgSkillsSkillMetadata — Metadata contains the skill's metadata.
      - `author` string — Author is the skill author or maintainer.
      - `description` string — Description is a human-readable description of the skill.
      - `name` string — Name is the unique name of the skill.
      - `tags` string[] — Tags is a list of tags for categorization.
      - `version` string — Version is the semantic version of the skill.
    - `project_root` string — ProjectRoot is the project root path for project-scoped skills. Empty for user-scoped.
    - `reference` string — Reference is the full OCI reference (e.g. ghcr.io/org/skill:v1).
    - `scope` 'user' | 'project' — Scope for the installation
    - `status` 'installed' | 'pending' | 'failed' — Status is the current installation status.
    - `tag` string — Tag is the OCI tag (e.g. v1.0.0).

## Other responses

- `400` — Bad Request
- `401` — Unauthorized (registry refused credentials)
- `404` — Not Found (artifact not present in registry)
- `409` — Conflict
- `429` — Too Many Requests (registry rate limit)
- `500` — Internal Server Error
- `502` — Bad Gateway (upstream registry failure)
- `504` — Gateway Timeout (upstream pull timed out)

## Changes

- **2026-07-29** `3db2b10a01f6` — 1 info
  - added the optional property `skill/managed` to the response with the `201` status
- **2026-04-23** `d5a1987b7457` — 4 info
  - added the non-success response with the status `401`
  - added the non-success response with the status `404`
  - added the non-success response with the status `429`
  - added the non-success response with the status `504`
- **2026-04-21** `ead8d06eaeaa` — 1 info
  - added the non-success response with the status `502`
- **2026-04-13** `3b31034fd29e` — 1 warning, 1 info
  - removed the request property `oneOf[#/components/schemas/pkg_api_v1.installSkillRequest]/client`
  - added the new optional request property `oneOf[#/components/schemas/pkg_api_v1.installSkillRequest]/clients`
- **2026-03-17** `8ab2f5690c97` — 1 breaking, 1 info
  - removed `#/components/schemas/v1.installSkillRequest` from the request body `oneOf` list
  - added `#/components/schemas/pkg_api_v1.installSkillRequest` to the request body `oneOf` list

[Full history](https://skmtc.dev/stacklok/apis/toolhive-api/changes/api/v1beta/skills/post.md)

---

[API](https://skmtc.dev/stacklok/apis/toolhive-api.md) · [All operations](https://skmtc.dev/stacklok/apis/toolhive-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stacklok/toolhive-api/revisions/3db2b10a01f6/schema)