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

# 通過 API 激活技能

> 如何查找技能 slug、在 API 調用中傳遞它們，以及在 SDK 中使用它們。

技能為 Theo 擴展了專業能力——領域知識、自定義工具、提示擴展和模型偏好。你可以通過傳遞技能的 **slug**，在任意補全請求中激活該技能。

## 查找技能 Slug

每個技能都有唯一的 slug（例如 `customer-support`、`code-review`、`deep-research`）。

**在 Dashboard 中：**

1. 進入 **Skills → Marketplace** 或 **My Skills**。
2. 每個技能卡片都會顯示其 slug——點擊複製圖標即可複製。

**通過 API：**

```bash theme={null}
# 列出所有市場技能
curl -H "Authorization: Bearer $THEO_API_KEY" \
  https://www.hitheo.ai/api/v1/skills

# 列出你已安裝的技能
curl -H "Authorization: Bearer $THEO_API_KEY" \
  "https://www.hitheo.ai/api/v1/skills?filter=installed"
```

兩者都會返回一個 `skills` 數組。每個對象都包含 `slug`、`name`、`description` 和 `category`。

**在技能構建器中：**
當你打開帶有 **API Call** 觸發器的 Input 節點時，畫布會顯示該技能的 slug，並帶有 **Copy** 按鈕。如果畫布尚未發佈，則會顯示草稿 slug 預覽。

## 在補全請求中使用技能

在 `skills` 數組中傳入一個或多個 slug：

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hitheo.ai/api/v1/completions \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Summarize recent support tickets for this customer",
      "skills": ["customer-support"]
    }'
  ```

  ```typescript SDK theme={null}
  import { Theo } from "@hitheo/sdk";

  const theo = new Theo({ apiKey: process.env.THEO_API_KEY! });

  const res = await theo.complete({
    prompt: "Summarize recent support tickets for this customer",
    skills: ["customer-support"],
  });
  ```

  ```python Python (requests) theme={null}
  import requests

  res = requests.post(
      "https://www.hitheo.ai/api/v1/completions",
      headers={"Authorization": f"Bearer {THEO_API_KEY}"},
      json={
          "prompt": "Summarize recent support tickets for this customer",
          "skills": ["customer-support"],
      },
  )
  ```
</CodeGroup>

## 工作原理

當你傳遞 `skills` 時：

1. **Slug 解析** —— Theo 查找每個 slug 並加載該技能的清單（提示擴展、工具、模型偏好）。
2. **與已安裝技能合併** —— 請求中的技能會與你已安裝並啓用的技能合併。
3. **提示注入** —— 每個激活技能的系統提示擴展都會被注入請求上下文，按優先級和強度排序。
4. **工具聚合** —— 激活技能所聲明的工具會對智能體循環可用。
5. **模型偏好** —— 如果某個技能指定了首選模型（例如用於深度分析的 `theo-1-reason`），Theo 可能會路由到該模型。

## 多個技能

你可以同時激活多個技能：

```json theme={null}
{
  "prompt": "Extract data from the attached ACORD 125 form and run a compliance check",
  "skills": ["data-extraction", "insurance-compliance"]
}
```

技能按列出的順序應用。如果多個技能的模型偏好存在衝突，以第一個技能的偏好為準。

## 你未安裝的技能

你可以在 `skills` 數組中傳入 **任意公開技能** 的 slug——無需先安裝它。安裝某個技能意味着它會自動包含在每個請求中；而在 `skills` 中傳遞它，只會為單次請求激活它。

## 構建你自己的技能

參見 [使用技能構建器進行構建](/guides/evi-canvas) 以可視化方式創建技能，或使用 SDK：

```typescript theme={null}
import { defineSkill } from "@hitheo/sdk";

export default defineSkill({
  name: "my-custom-skill",
  tools: [myTool],
  knowledge: ["./docs/*.md"],
});

// Publish: npx theo publish
```

發佈後，你的技能 slug 會立即可用於 `skills` 數組中。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.