> ## 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 코딩 Agent를 위한 로컬 확장 기능입니다. 설치 후 Codex, Claude Code, Cursor, Cline 등 Skills를 지원하는 Agent 안에서 자연어로 AIHubMix 연동, 모델 조회, 기능별 모델 선택, 예제 생성, 오류 진단을 진행할 수 있습니다.

이 Skill은 고정된 모델 목록을 포함하지 않습니다. 필요할 때 AIHubMix 공식 API에서 모델, 가격, 컨텍스트, 프로토콜 계약 등 실시간 정보를 읽어 Agent가 오래된 기억에 의존하지 않도록 합니다.

## 사용 시나리오

| 시나리오        | 이렇게 말할 수 있습니다                 | Skill이 하는 일                                                          |
| ----------- | ----------------------------- | -------------------------------------------------------------------- |
| AIHubMix 연동 | “이 프로젝트를 AIHubMix에 연결해 줘”     | 프로젝트 기술 스택을 파악하고 적절한 프로토콜을 선택한 뒤 최소 실행 가능한 연동 방법을 제시합니다              |
| 모델 조회       | “gemini 최신 사용 가능 모델을 확인해 줘”   | AIHubMix 실시간 모델 API에서 결과를 조회하고 정리합니다                                 |
| 기능별 모델 선택   | “사용 가능한 이미지 입력 모델은 뭐가 있어?”    | vision, 이미지 생성, 비디오, TTS, STT, embedding, rerank 등 기능별 후보 모델을 필터링합니다 |
| 예제 생성       | “Anthropic messages 호출 예제를 줘” | OpenAI, Anthropic, Gemini 등 프로토콜별 실행 가능한 예제를 생성합니다                   |
| Key 검증      | “이 모델을 호출할 수 있는지 확인해 줘”       | 실제 최소 호출로 API Key와 모델 호출 가능 여부를 검증합니다                                |
| 오류 진단       | “이 401 / 400은 왜 발생했어?”        | 엔드포인트, 모델, 오류 본문, 요청 ID를 바탕으로 처리 방법을 분석합니다                           |

## 사전 조건

* Codex, Claude Code, Cursor, Cline, Gemini CLI, OpenCode 등 Skills 지원 AI Agent가 하나 이상 설치되어 있어야 합니다.
* 로컬에서 Python 3.8 이상을 실행할 수 있어야 합니다.
* 실제 모델을 호출하려면 [AIHubMix API Key](https://console.aihubmix.com/token)를 준비해야 합니다.
* 잔액, Key 목록, 현재 계정에서 호출 가능한 모델을 조회하려면 공식 `aihubmix` CLI를 추가로 설치하고 로그인해야 합니다.

## 설치

### 방법 1: Agent에게 설치 요청

현재 사용하는 AI Agent에게 아래 지시를 전달하세요.

```text theme={null}
https://github.com/AIhubmix/skills 에서 AIHubMix Skill을 가져와 현재 도구의 Skills 디렉터리에 넣어 주세요.

Claude Code는 ~/.claude/skills,
Codex는 ~/.codex/skills 를 사용할 수 있습니다.

설치 후 python <skill>/scripts/AiHubMixAPI.py --help 를 실행해 검증해 주세요.
```

### 방법 2: 수동 설치

```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를 실행해 줘.

AIHubMix에서 Claude 계열 최신 모델과 가격을 확인해 줘.

내가 사용할 수 있는 이미지 생성 모델은 뭐가 있어? 현재 계정으로 호출 가능한 것만 보여줘.

이 엔드포인트가 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>` |

## FAQ

### 설치 후 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)