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

# Agent Skill 接入与使用指南

> 一句话或一条命令，把 AIBase 开放平台的调用规范装进 WorkBuddy、Claude Code、Cursor、Codex 等 AI 助手，让它写出的调用代码符合 SYNC / ASYNC 执行要求。

<Note>
  **前置条件**：先[创建 API Key](/quickstart/get-api-key)，并写入环境变量 `AIBASE_API_KEY`。技能要求 AI 助手只从该环境变量读取密钥，不硬编码、不索要明文；生成的代码在缺少该变量时会直接报错停止。
</Note>

***

## 1. 快速安装

### 1.1 一句话安装：把这段话发给 AI 助手

复制对应的一句，粘贴到 AI 助手的对话框发送，它会自己完成下载安装并回报结果，你不需要记任何路径。

<Tabs>
  <Tab title="通用（Claude Code / Cursor / Codex）">
    ```text theme={null}
    请执行 npx skills add https://docs.aibase.com，把 AIBase 官方 Agent Skill 安装到本项目，安装完告诉我装到了哪个目录。
    ```
  </Tab>

  <Tab title="WorkBuddy">
    ```text theme={null}
    请把 https://docs.aibase.com/.well-known/skills/aibase-api/skill.md 下载并保存为本项目的 .workbuddy/skills/aibase-api/SKILL.md，之后我让你调用 AIBase API 时，按该文件里的 SYNC / ASYNC 规范执行。
    ```
  </Tab>

  <Tab title="装到用户级（所有项目可用）">
    ```text theme={null}
    请执行 npx skills add https://docs.aibase.com -g，把 AIBase 官方 Agent Skill 安装到用户级目录，安装完告诉我装到了哪个目录。
    ```
  </Tab>
</Tabs>

<Note>
  `npx skills add` 由 Vercel Skills CLI 提供，覆盖 40+ 编程助手，会自动写入你所用工具规定的 skills 目录。WorkBuddy 不在其覆盖范围内，请使用 WorkBuddy 专属那条指令。
</Note>

### 1.2 自己执行一行命令

在项目根目录执行：

```bash theme={null}
npx skills add https://docs.aibase.com
```

| 目的           | 命令                                                                |
| :----------- | :---------------------------------------------------------------- |
| 安装到本项目（默认）   | `npx skills add https://docs.aibase.com`                          |
| 只装给指定工具      | `npx skills add https://docs.aibase.com -a claude-code -a cursor` |
| 装到用户级，所有项目可用 | `npx skills add https://docs.aibase.com -g`                       |
| 先看看能装什么      | `npx skills add https://docs.aibase.com --list`                   |
| 确认是否已安装      | `npx skills list`                                                 |

### 1.3 免安装：把地址交给助手

不想在本项目落文件时，直接把地址贴给 AI 助手，让它自行读取：

| 用途                 | 地址                                                               |
| :----------------- | :--------------------------------------------------------------- |
| 技能原文（推荐给 Agent 读取） | `https://docs.aibase.com/.well-known/skills/aibase-api/skill.md` |
| 技能发现索引             | `https://docs.aibase.com/.well-known/skills/index.json`          |

```text theme={null}
请先阅读 https://docs.aibase.com/.well-known/skills/aibase-api/skill.md，
然后帮我用 Python 写一个调用 AIBase geo.ranking 的脚本，严格按其中的 ASYNC 流程轮询。
```

Dify、Coze、FastGPT 等低代码平台：把**技能原文**的内容粘贴到智能体的 System Prompt 或工具说明中即可。

### 1.4 安装落点对照（手动放置时参考）

使用 `npx skills add` 时目录由 CLI 自动处理，下表供你手动下载文件时参考；各工具目录以其官方文档为准。

| 工具             | 项目级目录                | 用户级目录                           |
| :------------- | :------------------- | :------------------------------ |
| Claude Code    | `.claude/skills/`    | `~/.claude/skills/`             |
| Cursor         | `.agents/skills/`    | `~/.cursor/skills/`             |
| Codex          | `.agents/skills/`    | `~/.codex/skills/`              |
| GitHub Copilot | `.agents/skills/`    | `~/.copilot/skills/`            |
| OpenCode       | `.agents/skills/`    | `~/.config/opencode/skills/`    |
| Antigravity    | `.agent/skills/`     | `~/.gemini/antigravity/skills/` |
| WorkBuddy      | `.workbuddy/skills/` | `~/.workbuddy/skills/`          |

<Tip>
  文件名保持 `SKILL.md`，放在上述目录下的 `aibase-api/` 子目录中（例如 `.workbuddy/skills/aibase-api/SKILL.md`）。技能内容会随文档站更新，重新执行安装命令即可同步。
</Tip>

***

## 2. 验证是否生效

安装或引用后，用下面任意一种方式验证：

1. **看输出是否提到轮询规范**：向助手提问「写一个调用 AIBase `geo.ranking` 的脚本」，返回的代码应满足三点——
   * 提交到 `POST https://api.aibase.cn/v1/openapi/tasks`；
   * 从响应中提取 `data.taskId`，而不是直接找 `result`；
   * 按 10 秒间隔轮询 `GET /v1/openapi/tasks/{taskId}`，在 `status = 2` 时读取 `data.result`。
2. **看是否避开已知参数坑**：让助手写 `geo.checker` 的请求体，`platforms` 应为逗号分隔字符串而非数组，`title` 不应包含待检测的 URL。
3. **用 CLI 确认**（1.2 方式安装时）：执行 `npx skills list`，列表中出现 `aibase-api` 即已安装。

若助手没有遵守上述约束，说明它没有加载到技能——先确认安装结果，或在提问时显式附上第 1.3 节的地址。

***

## 3. 安装后怎么用

| 场景      | 怎么用                                                                                 |
| :------ | :---------------------------------------------------------------------------------- |
| 已安装     | 直接提需求即可，无需 `@` 引用文件，例如「帮我写个调用 AIBase geo.ranking 的脚本」。                              |
| 助手似乎没读到 | 在提问前加一句「参考 AIBase Agent Skill」，或把 1.3 节的地址贴在问题里。                                    |
| 项目规则文件  | 在 `CLAUDE.md`、`.cursorrules` 等文件中写明「调用 AIBase API 前先读取 AIBase Agent Skill」，团队内保持一致。 |
| 低代码平台   | 把技能原文放进 System Prompt 或工具说明（见 1.3）。                                                 |

***

## 4. 常用 Prompt 模板

<AccordionGroup>
  <Accordion title="模板 1：生成 GEO 排名查询代码（ASYNC 异步模式）">
    ```text theme={null}
    参考 AIBase Agent Skill，用 [Python/TypeScript/Java] 编写一个调用 "GEO 排名查询工具 (geo.ranking)" 的完整程序。
    要求：
    1. 从环境变量 AIBASE_API_KEY 读取密钥；
    2. 构造正确的请求体（keyword, brandKeyword, platforms）；
    3. 严格遵循 ASYNC 异步模式 SOP，提交后提取 taskId，以 10 秒为间隔轮询 GET /v1/openapi/tasks/{taskId}；
    4. 当 status=2 时解析并打印每个平台的推荐状态与排名；当 status>=3 时抛出明确异常。
    ```
  </Accordion>

  <Accordion title="模板 2：生成 GEO 推广链接检测代码（带避坑约束）">
    ```text theme={null}
    参考 AIBase Agent Skill，为我编写 AIBase "GEO 推广链接检测 (geo.checker)" 的请求代码。
    注意事项：
    1. platforms 参数必须是英文逗号隔开的字符串，而非数组；
    2. questions 参数必须是 JSON 序列化的字符串数组格式；
    3. title 绝对不能是 URL 格式，也不能包含 url 参数的内容；
    4. 实现 10 秒轮询直到检测完成，并提取 urlCountList 排行榜。
    ```
  </Accordion>

  <Accordion title="模板 3：生成 AI 对话问题挖掘代码（SYNC 同步模式）">
    ```text theme={null}
    参考 AIBase Agent Skill，编写调用 "AI 对话问题挖掘 (geo.questions_corr_recommend)" 接口的代码。
    要求：
    1. 本接口为 SYNC 同步模式，直接在 POST 请求的响应体中读取 data.result；
    2. 提取 aiQuestions 与 baiduQuestions 列表并按热度打印；
    3. 记录响应中的 data.requestId 用于日志排查。
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  模板开头写的是「参考 AIBase Agent Skill」。已安装时这样写即可；免安装场景请替换为 1.3 节的技能原文地址。接口字段与参数的权威说明，仍以对应的 API 参考页为准。
</Tip>

***

<Card title="阅读同步与异步任务模式专题" icon="clock" href="/quickstart/task-modes" horizontal>
  深入了解底层协议设计、状态流转与多语言实现样例。
</Card>