# Shoplazza AI Toolkit 快速开始

> 在 Claude Code、Codex CLI、Cursor IDE、Gemini CLI、Antigravity CLI 或 GitHub Copilot 里配置 Shoplazza AI Toolkit：安装 Shoplazza CLI、添加 Agent Skills、完成店铺认证，再发出第一条指令。

AI Toolkit 运行在 [Shoplazza CLI](/zh-CN/docs/app/developer-tools/shoplazza-cli/) 之上，因此配置分四步：安装 CLI、添加技能、认证，再向智能体发指令。一条命令就能把技能装给你正在用的智能体。

## 环境要求

* [Node.js](https://nodejs.org/en/download) 16.0.0 或更高
* 受支持的 AI 编码智能体：[Claude Code](#claude-code)、[Codex CLI](#codex-cli)、[Cursor IDE](#cursor-ide)、[Gemini CLI](#gemini-cli)、[Antigravity CLI](#antigravity-cli) 或 [GitHub Copilot](#github-copilot)。其他能读取 `SKILL.md` 的智能体，用同一条命令安装即可。

## 1. 安装 Shoplazza CLI

```shell
npm install -g shoplazza-cli
```

其他方式（shell 脚本、Homebrew、预编译二进制）与完整说明，见[安装 Shoplazza CLI](/zh-CN/docs/app/developer-tools/shoplazza-cli/install)。

## 2. 添加 Agent Skills

```shell
npx skills add Shoplazza/shoplazza-cli -g
```

这条命令会检测本机已安装的智能体，把技能文件放进 `~/.agents/skills/`，再链接或暴露给各个智能体。只装给某一个智能体时，加上 `-a <agent>`。技能清单与工作方式见 [Agent Skills](./skills)。

#### Claude Code

```shell
npx skills add Shoplazza/shoplazza-cli -g -a claude-code
```

技能文件落在 `~/.agents/skills/`，并软链到 `~/.claude/skills/`。

确认是否已加载：在 Claude Code 里输入 `/`，列表中会出现 `shoplazza-products` 等技能。

调用方式：发送 `/shoplazza-products 看下店里所有带 shirt 关键词、已上架的商品`。

#### Codex CLI

```shell
npx skills add Shoplazza/shoplazza-cli -g -a codex
```

Codex CLI 直接读取 `~/.agents/skills/`，不会建软链。这些技能在 Codex 的 IDE 扩展里同样可用。

确认是否已加载：运行 `/skills`，或输入 `$` 打开技能选择列表。Codex 会自动检测技能变更；技能没出现就重启 Codex。

调用方式：发送 `$shoplazza-products 看下店里所有带 shirt 关键词、已上架的商品`。

#### Cursor IDE

```shell
npx skills add Shoplazza/shoplazza-cli -g -a cursor
```

Cursor IDE 直接读取 `~/.agents/skills/`，同时也读 `~/.cursor/skills/`。

确认是否已加载：打开侧栏的 **Customize → Skills**，查看已发现的技能。

调用方式：在 Agent 聊天里输入 `/` 搜索技能名，再发送 `/shoplazza-products 看下店里所有带 shirt 关键词、已上架的商品`。

#### Gemini CLI

```shell
npx skills add Shoplazza/shoplazza-cli -g -a gemini-cli
```

Gemini CLI 在用户级读取 `~/.agents/skills/`，其优先级高于 `~/.gemini/skills/`。

确认是否已加载：运行 `/skills list`。技能变更后运行 `/skills reload`。

Gemini CLI 没有 `/技能名` 这类调用语法，改用自然语言点名技能：`使用 shoplazza-products 技能，看下店里所有带 shirt 关键词、已上架的商品`。

#### Antigravity CLI

```shell
npx skills add Shoplazza/shoplazza-cli -g -a antigravity-cli
```

技能文件装进 Antigravity CLI 的全局技能目录 `~/.gemini/antigravity-cli/skills/`。Antigravity 同时也读当前工作区里的 `.agents/skills/`。

确认是否已加载：新开一个对话，让智能体列出它可用的技能——Antigravity 会在对话开始时把每个技能的名称和描述交给智能体。

Antigravity 没有 `/技能名` 这类调用语法，改用自然语言点名技能：`使用 shoplazza-products 技能，看下店里所有带 shirt 关键词、已上架的商品`。

#### GitHub Copilot

先在 VS Code 里安装 [GitHub Copilot 扩展](https://code.visualstudio.com/docs/setup/copilot) 并登录，再运行：

```shell
npx skills add Shoplazza/shoplazza-cli -g -a github-copilot
```

个人技能从 `~/.agents/skills/` 读取。

确认是否已加载：在聊天输入框输入 `/skills`，打开 Configure Skills 菜单。

调用方式：发送 `/shoplazza-products 看下店里所有带 shirt 关键词、已上架的商品`——每个技能都是一条斜杠命令。

## 3. 认证

```shell
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders
```

该命令会打开浏览器进行 OAuth 授权，并将凭据加密存储在 CLI 的配置目录中。用 `shoplazza auth status` 验证。UAT/CI 登录与店铺切换见[认证](/zh-CN/docs/app/developer-tools/shoplazza-cli/authentication)。

:::tip
也可以让智能体带你完成登录：发送 `/shoplazza-common log me in to my-store.myshoplaza.com`。若由 AI 智能体替你执行登录，它应从命令输出中提取授权 URL 并发给你——命令会轮询，直到你在浏览器中完成 OAuth。
:::

## 4. 向智能体发出指令

用 `/shoplazza-<域>` 前缀调用技能，再用自然语言描述任务：

```
/shoplazza-products 看下店里所有带 shirt 关键词、已上架的商品
```

各智能体的调用前缀不同：Claude Code、Cursor IDE、GitHub Copilot 用 `/`，Codex CLI 用 `$`，Gemini CLI 和 Antigravity CLI 则用自然语言点名技能。细节见[添加 Agent Skills](#2-添加-agent-skills)下各智能体小节。

在背后，智能体运行：

```shell
shoplazza products +search --keyword "shirt" --published published --format table
```

## 下一步

* [Agent Skills](./skills) —— 选对业务域并理解安全协议
* [使用示例](./usage/products) —— 各模块的即拷即用指令