Agent Skill 接入与使用指南

防止异步逻辑出错

强制规范大模型执行“提交任务 → 获取 taskId → 10 秒轮询 → 成功读取 result”的 SOP，杜绝模型因死循环轮询被 429 限流。

消除参数幻觉

明确规避 geo.checker 标题校验与 JSON 字符串数组等边界限制，使 AI 代码生成准确率达 100%。

前置条件：先创建 API Key，并写入环境变量 AIBASE_API_KEY。技能要求 AI 助手只从该环境变量读取密钥，不硬编码、不索要明文；生成的代码在缺少该变量时会直接报错停止。

1. 快速安装

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

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

通用（Claude Code / Cursor / Codex）
WorkBuddy
装到用户级（所有项目可用）

请执行 npx skills add https://docs.aibase.com，把 AIBase 官方 Agent Skill 安装到本项目，安装完告诉我装到了哪个目录。

请把 https://docs.aibase.com/.well-known/skills/aibase-api/skill.md 下载并保存为本项目的 .workbuddy/skills/aibase-api/SKILL.md，之后我让你调用 AIBase API 时，按该文件里的 SYNC / ASYNC 规范执行。

请执行 npx skills add https://docs.aibase.com -g，把 AIBase 官方 Agent Skill 安装到用户级目录，安装完告诉我装到了哪个目录。

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

1.2 自己执行一行命令

在项目根目录执行：

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`

请先阅读 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/`

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

2. 验证是否生效

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

看输出是否提到轮询规范：向助手提问「写一个调用 AIBase geo.ranking 的脚本」，返回的代码应满足三点——
- 提交到 POST https://api.aibase.cn/v1/openapi/tasks；
- 从响应中提取 data.taskId，而不是直接找 result；
- 按 10 秒间隔轮询 GET /v1/openapi/tasks/{taskId}，在 status = 2 时读取 data.result。
看是否避开已知参数坑：让助手写 geo.checker 的请求体，platforms 应为逗号分隔字符串而非数组，title 不应包含待检测的 URL。
用 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 模板

模板 1：生成 GEO 排名查询代码（ASYNC 异步模式）

参考 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 时抛出明确异常。

模板 2：生成 GEO 推广链接检测代码（带避坑约束）

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

模板 3：生成 AI 对话问题挖掘代码（SYNC 同步模式）

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

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

阅读同步与异步任务模式专题

深入了解底层协议设计、状态流转与多语言实现样例。

快速开始

业务 API

Agent Skill

语言示例

公共规范

Agent Skill 接入与使用指南

防止异步逻辑出错

消除参数幻觉

1. 快速安装

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

1.2 自己执行一行命令

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

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

2. 验证是否生效

3. 安装后怎么用

4. 常用 Prompt 模板

阅读同步与异步任务模式专题

防止异步逻辑出错

消除参数幻觉

​1. 快速安装

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

​1.2 自己执行一行命令

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

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

​2. 验证是否生效

​3. 安装后怎么用

​4. 常用 Prompt 模板

阅读同步与异步任务模式专题

1. 快速安装

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

1.2 自己执行一行命令

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

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

2. 验证是否生效

3. 安装后怎么用

4. 常用 Prompt 模板