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