---
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
    - `allow_unsigned` boolean — AllowUnsigned permits installing a project-scoped skill without a verified signature; the exception is recorded in the project's lock file.
    - `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
  - `provenance` GithubComStacklokToolhivePkgSkillsProvenanceInfo — Provenance is the signer identity the project's lock file records for this skill, when project-scoped and lock-managed.
    - `cert_issuer` string — CertIssuer is the OIDC issuer that authenticated the signer.
    - `provisional` boolean — Provisional marks provenance with a documented verification gap (git signatures until transparency-log validation lands).
    - `repository_ref` string — RepositoryRef is the git ref the signing workflow ran on, from Fulcio certificate extension 1.3.6.1.4.1.57264.1.14. Empty means unconstrained, matching lock files written before the field existed.
    - `repository_uri` string — RepositoryURI is the source repository from the certificate extensions, when present.
    - `runner_environment` string — RunnerEnvironment is the runner class the signing workflow executed in (e.g. "github-hosted"), from Fulcio certificate extension 1.3.6.1.4.1.57264.1.11. Empty means unconstrained.
    - `signer_identity` string — SignerIdentity is the certificate subject identity (workflow path for GitHub Actions certificates, SAN verbatim otherwise).
    - `sigstore_url` string — SigstoreURL is the Sigstore instance the signature chains to.
  - `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).
  - `unsigned` boolean — Whether the install was recorded as an explicit unsigned exception.

## 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

> 49 revisions in range; 16 could not be searched.

- **2026-07-29** `3db2b10a01f6` — 1 info
  - added the optional property `skill/managed` to the response with the `201` status
- **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
- **2026-03-06** `b2b0a6a97af8` — 1 info
  - added the new optional request property `oneOf[#/components/schemas/v1.installSkillRequest]/group`
- **2026-03-05** `7ddc75dcd1f4` — 1 info
  - added the new optional request property `oneOf[#/components/schemas/v1.installSkillRequest]/project_root`
- **2026-02-20** `cb830b4f4217` — 2 info
  - added the new optional request property `oneOf[#/components/schemas/v1.installSkillRequest]/client`
  - added the new optional request property `oneOf[#/components/schemas/v1.installSkillRequest]/force`

[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/e9f942effcda/schema)