> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chowder.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Skill

> Install a skill from ClawHub onto an instance.

Installs a skill from ClawHub onto the instance. Under the hood, this runs `npx clawhub install` with the given slug. If the skill requires environment variables, you can provide them upfront in the `env` field — or skip them and configure later via the [update config endpoint](/api-reference/skills/update-config).

## Authentication

Requires an **org-level API key** or a **scoped token** with the `configure` permission.

## Path Parameters

<ParamField path="instance_id" type="string" required>
  The ID of the instance.
</ParamField>

## Body Parameters

<ParamField body="slug" type="string" required>
  The ClawHub slug identifying the skill to install (e.g. `web-search`).
</ParamField>

<ParamField body="env" type="object">
  Optional environment variables required by the skill. Keys are variable names, values are strings.
</ParamField>

## Response

<ResponseField name="skill" type="string">
  The name of the installed skill.
</ResponseField>

<ResponseField name="status" type="string">
  Either `"installed"` (fully ready) or `"installed_missing_env"` (installed but needs env vars to function).
</ResponseField>

<ResponseField name="output" type="string">
  Raw output from the installation process.
</ResponseField>

<ResponseField name="env_applied" type="object">
  The environment variables that were successfully applied, if any.
</ResponseField>

<ResponseField name="required_env" type="array">
  A list of environment variable names that the skill still needs, if any.
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable status message.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  curl -X POST https://api.chowder.dev/v1/instances/ins_abc123/skills/install \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "slug": "web-search",
      "env": {
        "SEARCH_API_KEY": "sk-..."
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 (fully installed) theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  {
    "skill": "web-search",
    "status": "installed",
    "output": "Successfully installed web-search@1.2.0",
    "env_applied": {
      "SEARCH_API_KEY": "sk-..."
    },
    "message": "Skill installed and ready to use."
  }
  ```

  ```json 200 (missing env) theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  {
    "skill": "image-gen",
    "status": "installed_missing_env",
    "output": "Successfully installed image-gen@0.9.1",
    "required_env": ["OPENAI_API_KEY"],
    "message": "Skill installed but requires environment variables to function."
  }
  ```
</ResponseExample>