> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-docs-responses-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Venice Skills

> 官方 Venice Agent Skills 将端点知识加载到 Claude Code、Cursor、Codex、OpenCode、Hermes 和 Cline，打造可靠的编码 agent。

[Venice Skills](https://github.com/veniceai/skills) 是面向 Venice API 的 [Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) 的权威集合。每个 skill 是一个自包含文件夹，其中包含 `SKILL.md`，LLM agent 按需加载它，以便正确操作 API 的特定表面。

<Card title="GitHub: veniceai/skills" icon="github" href="https://github.com/veniceai/skills">
  19 个 skill，覆盖完整的 Venice API。MIT 许可。与公开的 [`swagger.yaml`](/api-reference/api-spec) 保持同步。
</Card>

<CardGroup cols={3}>
  <Card title="19 个 Skill" icon="layer-group">
    每个 Venice API 表面对应一个
  </Card>

  <Card title="运行时无关" icon="plug">
    可用于 Claude Code、Cursor、Codex、OpenCode、Hermes、Cline 以及任何其他 Agent Skills 宿主
  </Card>

  <Card title="与规范同步" icon="rotate">
    源自 Venice 的 OpenAPI 规范，并通过 CI 检查漂移
  </Card>
</CardGroup>

## 为何需要 skills？

没有 skills，您的 agent 就只能费力地自行发现 Venice 的怪癖：`venice_parameters`、模型类型枚举、402 需付款流程、视频 queue/retrieve 生命周期、character slug 等等。Skills 将这些知识打包到聚焦、按需的文件中，使 agent 只为当前任务加载所需内容。

每个 `SKILL.md` 包含：

* 它所覆盖的端点
* 必需的请求头、参数和响应结构
* 一个 curl 示例加上一个最小化 SDK 示例
* 包含真实集成者常踩坑点的"陷阱"小节

## Skill 目录

| Skill | 覆盖范围 |
| - | - |
| `venice-api-overview` | Base URL、认证模式、响应头、定价模型、版本管理 |
| `venice-auth` | Bearer API 密钥 + Sign-In-With-X / x402 钱包身份验证 |
| `venice-chat` | `/chat/completions` 配合 `venice_parameters`、多模态、tools、推理、流式 |
| `venice-responses` | `/responses`，OpenAI 兼容的 Responses API（Alpha） |
| `venice-embeddings` | `/embeddings` 模型、编码格式、维度 |
| `venice-image-generate` | `/image/generate`、`/images/generations`、`/image/styles` |
| `venice-image-edit` | `/image/edit`、`/image/multi-edit`、`/image/upscale`、`/image/background-remove` |
| `venice-audio-speech` | `/audio/speech` TTS 模型、voice、格式、流式 |
| `venice-audio-music` | `/audio/quote`、`/audio/queue`、`/audio/retrieve`、`/audio/complete` |
| `venice-audio-transcription` | 配合 Whisper、Parakeet、Scribe、Wizper、xAI STT 的 `/audio/transcriptions` |
| `venice-video` | `/video/*` 生成、编辑、放大和异步任务生命周期 |
| `venice-models` | `/models`、`/models/traits`、`/models/compatibility_mapping` |
| `venice-characters` | `/characters*` + `venice_parameters.character_slug` |
| `venice-api-keys` | CRUD `/api_keys`、速率限制、Web3 密钥生成 |
| `venice-billing` | `/billing/balance`、`/billing/usage`、`/billing/usage-analytics` |
| `venice-x402` | `/x402/*` 钱包额度，Base 或 Solana 上的 USDC |
| `venice-crypto-rpc` | `/crypto/rpc/*` JSON-RPC 代理，1×/2×/4× 定价 |
| `venice-augment` | `/augment/text-parser`、`/augment/scrape`、`/augment/search` |
| `venice-errors` | 错误结构、402 需付款、422 内容政策、429 速率限制、重试策略 |

## 安装

每个 skill 只是一个包含 `SKILL.md` 的文件夹，开头是 YAML frontmatter：

```yaml theme={null}
---
name: venice-chat
description: When the agent should load this skill and what's in it
---
```

将 `skills/` 文件夹（或任意子集）放入您的运行时所监视的路径。

<Tabs>
  <Tab title="Claude Code">
    项目本地：

    ```bash theme={null}
    git clone https://github.com/veniceai/skills.git
    cp -r skills/skills/* .claude/skills/
    ```

    或全局，为机器上每个项目使用：

    ```bash theme={null}
    git clone https://github.com/veniceai/skills.git ~/src/venice-skills
    ln -s ~/src/venice-skills/skills ~/.claude/skills/venice
    ```
  </Tab>

  <Tab title="Cursor">
    项目本地：

    ```bash theme={null}
    git clone https://github.com/veniceai/skills.git .cursor/skills-venice
    ```

    或复制单个 skill：

    ```bash theme={null}
    cp -r skills/venice-chat .cursor/skills/
    ```
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    git clone https://github.com/veniceai/skills.git ~/src/venice-skills
    ln -s ~/src/venice-skills/skills ~/.codex/skills/venice
    ```

    对于项目本地安装，请改为目标 `.codex/skills/`。
  </Tab>

  <Tab title="OpenCode">
    ```bash theme={null}
    git clone https://github.com/veniceai/skills.git ~/src/venice-skills
    ln -s ~/src/venice-skills/skills ~/.config/opencode/skills/venice
    ```

    OpenCode 还会从项目根目录读取 `.opencode/skills/`、`.claude/skills/` 和 `.agents/skills/`。
  </Tab>

  <Tab title="Hermes Agent">
    Hermes 为 Venice skills 提供了内置安装器：

    ```bash theme={null}
    hermes skills install veniceai/skills
    ```

    或直接 symlink：

    ```bash theme={null}
    git clone https://github.com/veniceai/skills.git ~/src/venice-skills
    ln -s ~/src/venice-skills/skills ~/.hermes/skills/venice
    ```
  </Tab>

  <Tab title="Cline">
    ```bash theme={null}
    git clone https://github.com/veniceai/skills.git .clinerules/skills-venice
    ```
  </Tab>
</Tabs>

### 路径参考

| 运行时 | 项目本地 | 全局 |
| - | - | - |
| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
| Codex | `.codex/skills/` | `~/.codex/skills/`（或 `$CODEX_HOME/skills/`） |
| OpenCode | `.opencode/skills/`（也包括 `.claude/skills/`、`.agents/skills/`） | `~/.config/opencode/skills/` |
| Hermes Agent | `$HERMES_OPTIONAL_SKILLS_DIR` | `~/.hermes/skills/` |
| Cursor | `.cursor/skills/` | `~/.cursor/skills/` |
| Cline | `.clinerules/skills/` | n/a |
| 其他运行时 | `.agents/skills/`（约定） | `~/.agents/skills/` |

<Tip>
  定义额外 frontmatter 字段（`version`、`platforms`、`metadata.*`、`compatibility` 等）的运行时，规范要求其忽略未知字段，因此同一个 skill 文件可在各处工作而无需分叉。
</Tip>

### 作为 git 子模块

如果您希望在自己的仓库中锁定版本：

```bash theme={null}
git submodule add https://github.com/veniceai/skills.git vendor/venice-skills
```

然后将所需子集 symlink 或复制到您 agent 的 skill 路径中。

## Agent 如何加载

agent 通过每个 `SKILL.md` 的 frontmatter `name` 和 `description` 发现它。当用户提出与某 skill 用途匹配的内容时，agent 只将该文件加载到上下文中（而不是整个目录），因此 prompt 保持精简，回答保持准确。

例如，需要生成音乐的 agent 将加载 `venice-audio-music` 并立即知道：

* 音乐通过 queue/retrieve/complete 生命周期，而不是同步端点
* 哪些模型可用以及它们的每分钟定价
* 如何先调用 `/audio/quote` 进行成本估算
* 轮询退避应该是什么样

没有 skill，agent 可能会尝试为音乐调用 `/audio/speech` 并得到无用的响应。

## 编写新 skill

1. 将 `template/` 复制到 `skills/<your-skill>/`。
2. 填写 frontmatter 和正文。`description` 要具体，因为它是 agent 决定何时加载 skill 的依据。
3. 在底部链接相关 skill，便于交叉导航。
4. 向 [`veniceai/skills`](https://github.com/veniceai/skills) 提交 PR。

风格约定请参阅仓库的 `CONTRIBUTING.md`（简短首段、明确的端点表格、curl + 一个 SDK 示例、"陷阱"小节、≤ 500 行）。

## 资源

<CardGroup cols={2}>
  <Card title="GitHub" icon="github" href="https://github.com/veniceai/skills">
    源代码、贡献指南和 skill 模板
  </Card>

  <Card title="Venice MCP Server" icon="plug" href="/guides/integrations/venice-mcp">
    将 skill 与官方 MCP 服务器搭配以获得运行时工具访问
  </Card>

  <Card title="Agent Skills 规范" icon="arrow-up-right-from-square" href="https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview">
    了解底层格式
  </Card>

  <Card title="Venice API 规范" icon="book" href="/api-reference/api-spec">
    这些 skill 所派生的 OpenAPI 单一来源
  </Card>
</CardGroup>


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