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

# Skills

> AIHubMix Skill 為 Codex、Claude Code、Cursor、Cline 等 AI Agent 提供即時模型查詢、接入配置、呼叫範例生成與錯誤排查能力。

**AIHubMix Skill** 是面向 AI 編程助手的一套本地擴展能力。安裝後，你可以在 Codex、Claude Code、Cursor、Cline 等支援 Skills 的 Agent 裡，用自然語言完成 AIHubMix 接入、模型查詢、能力選型、範例生成和錯誤排查。

該 Skill 不內建固定模型清單，而是在需要時從 AIHubMix 官方介面讀取模型、價格、上下文、協議契約等即時資訊，讓 Agent 避免依賴過期記憶。

## 適用場景

| 場景          | 你可以這樣說                         | Skill 會做什麼                            |
| ----------- | ------------------------------ | ------------------------------------- |
| 接入 AIHubMix | “把這個專案接入 AIHubMix”             | 識別專案技術棧，選擇合適協議，給出最小可執行接入方式            |
| 查詢模型        | “查一下 gemini 最新可用模型”            | 從 AIHubMix 即時模型介面查詢並整理結果              |
| 按能力選型       | “有哪些可用的圖片輸入模型？”                | 按視覺、文生圖、影片、TTS、STT、向量、重排等能力篩選候選模型     |
| 生成範例        | “給我一個 Anthropic messages 呼叫範例” | 生成 OpenAI、Anthropic、Gemini 等協議下的可執行範例 |
| 校驗 Key      | “幫我確認這個模型能不能用”                 | 透過真實最小呼叫校驗 API Key 與模型可呼叫性            |
| 排查錯誤        | “這個 401 / 400 是什麼原因？”          | 結合介面、模型、錯誤體和請求 ID 分析處理方式              |

## 前置條件

* 至少安裝一個支援 Skills 的 AI Agent，例如 Codex、Claude Code、Cursor、Cline、Gemini CLI、OpenCode 等。
* 本機可執行 Python 3.8 或更高版本。
* 如需真實呼叫模型，需要準備 [AIHubMix API Key](https://console.aihubmix.com/token)。
* 如需查詢餘額、Key 列表或目前帳號可呼叫模型，需要額外安裝並登入官方 `aihubmix` CLI。

## 安裝

### 方式一：讓 Agent 幫你安裝

把下面這段話交給目前使用的 AI Agent：

```text theme={null}
請安裝 AIHubMix Skill：從 https://github.com/AIhubmix/skills 取得，放入目前工具的 Skills 目錄。

Claude Code 可使用 ~/.claude/skills，
Codex 可使用 ~/.codex/skills。

安裝後執行 python <skill>/scripts/AiHubMixAPI.py --help 驗證。
```

### 方式二：手動安裝

```bash theme={null}
# Claude Code
cp -r AiHubMixAPI ~/.claude/skills/

# Codex
cp -r AiHubMixAPI ~/.codex/skills/
```

<Tip>
  不同 Agent 的 Skills 目錄可能不同。如果你的工具使用統一目錄，可優先查看該 Agent 的 Skills 文件，或讓 Agent 自動判斷安裝位置。
</Tip>

## 可選：安裝 AIHubMix CLI

`AiHubMixAPI` 腳本可以讀取公開模型和協議資訊；帳戶餘額、Key 管理、目前帳號實際可呼叫模型等資料需要官方 CLI 登入後查詢。

```powershell theme={null}
# Windows
irm https://raw.githubusercontent.com/AIhubmix/platfrom-cli/main/install.ps1 | iex
```

```bash theme={null}
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/AIhubmix/platfrom-cli/main/install.sh | sh
```

安裝後執行：

```bash theme={null}
aihubmix login
aihubmix whoami
aihubmix models list
```

## 如何使用

安裝完成後，通常不需要記命令。直接在 Agent 裡描述任務即可：

```text theme={null}
把這個 Next.js 專案接入 AIHubMix，用一個可呼叫的文字模型做 smoke test。

查一下 Claude 系列在 AIHubMix 裡的最新模型和價格。

我可以用哪些文生圖模型？只看我目前帳號能呼叫的。

這個介面返回 401，幫我判斷是 Key、Base URL 還是模型權限問題。
```

如果 Agent 沒有自動觸發，可以顯式呼叫對應 Skill，例如：

```text theme={null}
/AiHubMixAPI 查詢 gemini 最新模型
/AiHubMixAPI 排查這個 400 報錯
```

## 命令列用法

進入 Skill 目錄後，也可以直接呼叫腳本：

```bash theme={null}
# 查詢模型
python scripts/AiHubMixAPI.py list --limit 20
python scripts/AiHubMixAPI.py report gemini
python scripts/AiHubMixAPI.py compare <model-a> <model-b>

# 按能力查候選模型
python scripts/AiHubMixAPI.py candidates --capability vision
python scripts/AiHubMixAPI.py candidates --capability image-gen
python scripts/AiHubMixAPI.py candidates --capability rerank

# 只看目前帳號可呼叫的候選模型，需要已登入 aihubmix CLI
python scripts/AiHubMixAPI.py candidates --capability vision --mine

```

中文輸出可以追加 `--lang zh`，或設定：

```bash theme={null}
export AIHUBMIX_LANG=zh
```

## 能力速查

| 能力                | 推薦命令                                                                |
| ----------------- | ------------------------------------------------------------------- |
| 查看模型列表            | `list`                                                              |
| 查詢某個模型或系列         | `get <model-id>` / `report <query>`                                 |
| 對比多個模型            | `compare <model-a> <model-b> ...`                                   |
| 按能力選型             | `candidates --capability <capability>`                              |
| 只看帳號可呼叫模型         | `candidates --capability <capability> --mine`                       |
| 校驗 API Key        | `doctor --model <model-id>`                                         |
| 校驗圖片輸入            | `doctor --model <model-id> --image`                                 |
| 生成 OpenAI 相容範例    | `example chat --model <model-id>`                                   |
| 生成 Anthropic 相容範例 | `example messages --model <model-id>`                               |
| 排查錯誤              | `troubleshoot --status <code> --endpoint <path> --model <model-id>` |

## 常見問題

### 安裝後 Agent 沒有自動呼叫

不同 Agent 對 Skill 觸發的策略不同。可以先直接輸入 `/AiHubMixAPI` 顯式呼叫；也可以把需求說得更明確，例如包含“AIHubMix”“模型”“Base URL”“API Key”“報錯碼”等關鍵詞。

### 公開模型列表裡有模型，但我的 Key 調不通

公開模型列表只說明平台存在該模型，不代表目前帳號一定有權限或餘額可呼叫。需要使用 `aihubmix models list` 或 `candidates --mine` 查看目前帳號實際可呼叫範圍，再用 `doctor --model <model-id>` 做真實校驗。

### 什麼時候需要安裝 `aihubmix` CLI

只查公開資料時不需要。需要餘額、Key 管理、帳號可呼叫模型、`--mine` 篩選等帳戶相關能力時，需要安裝並登入 CLI。

### 會不會洩露 API Key

Skill 的腳本會對密鑰做脫敏處理。仍然建議不要把真實 Key 寫入倉庫檔案、Issue、PR 描述或聊天記錄中；本地調試時使用環境變數傳入即可。

## 相關資源

* Skill 倉庫：[https://github.com/AIhubmix/skills](https://github.com/AIhubmix/skills)
* AIHubMix CLI：[https://github.com/AIhubmix/platfrom-cli](https://github.com/AIhubmix/platfrom-cli)
* AIHubMix 模型廣場：[https://aihubmix.com/models](https://aihubmix.com/models)