# Agent Skills

> Agent Skills 是 Shoplazza AI Toolkit 按业务域划分的 SKILL.md 指引文件，讲清怎么用 /shoplazza 前缀调用、怎么选对业务域、怎么遵守安全协议。

Agent Skills 是按业务域划分的 `SKILL.md` 指引文件——每个域一个——它们教会智能体每个任务该运行哪条命令，以及该域的字段、边界和安全规则。CLI 不装技能也能用，但技能会显著提升智能体的准确度。

## 安装

一条命令即可把技能装给你正在用的智能体。各智能体的具体命令与加载确认方式，见[快速开始 → 添加 Agent Skills](./get-started#2-添加-agent-skills)。

同一套技能也编译进了 CLI 二进制，智能体无需安装就能读到与当前 CLI 版本匹配的内容：`shoplazza skills list` 列出全部技能，`shoplazza skills read <name>` 打印其中一个（从 `shoplazza skills read shoplazza-common` 开始）。技能装进 `~/.agents/skills/` 后，`shoplazza update` 会随 CLI 一起刷新它们。

## 可用技能

| 业务域 | 技能 | 覆盖范围 |
|--------|------|---------|
| 地基 | `shoplazza-common` | 认证与 profile、命令分层、输出信封、schema 查询、筛选列表的核对，以及安全协议。其他技能都会让智能体先读它。 |
| 商品 | `shoplazza-products` | 建品 / 改价 / 库存 / 标签 / 上架、变体、合集、商品图片、礼品卡、评价、库位、供应商 |
| 折扣 | `shoplazza-discounts` | 满减、折扣码、闪购、买 X 送 Y、包邮码、优惠券活动 |
| 订单 | `shoplazza-orders` | 查订单、发货、退款、改运单号、取消、标记已支付、支付流水、风险订单、运费区域 |
| 客户 | `shoplazza-customers` | 客户资料、标签、营销订阅、地址 |
| 店铺 | `shoplazza-shop` | 店铺设置、元字段、媒体、分析、博客、页面、重定向、市场、语言 |
| 主题 | `shoplazza-themes` | 页面与卡片装修、主题设置、app 嵌入、自定义模板、AI 生成卡片、已安装主题（不含本地主题开发） |
| Webhook | `shoplazza-webhook` | 事件订阅 |
| 计费 | `shoplazza-billing` | 应用收费：一次性、订阅、用量 |

## 如何调用技能

在请求前加上 `/shoplazza-<域>` 前缀，再用自然语言描述任务：

```
/shoplazza-products 上架一个新品:夏季印花T恤,卖 129
```

前缀会在智能体动手前，先把该业务域的命令与注意事项装进上下文。

:::tip
前缀非强制——每个技能也内置了触发词——但显式带上更确定。因此文档统一使用 `/shoplazza-<域>`。
:::

## 选对业务域

每个技能只管一个域。按任务匹配对应的域：

| 做什么 | 用哪个技能 |
|--------|-----------|
| 上新 / 改价 / 补库存 / 礼品卡 | `/shoplazza-products` |
| 满减 / 折扣码 / 闪购 | `/shoplazza-discounts` |
| 发货 / 退款 / 查订单 | `/shoplazza-orders` |
| 客户资料与地址 | `/shoplazza-customers` |
| 店铺设置、元字段、媒体、分析 | `/shoplazza-shop` |
| 店铺页面与卡片装修、主题设置、模板 | `/shoplazza-themes` |
| 事件订阅(webhook) | `/shoplazza-webhook` |
| 应用计费——一次性 / 订阅 / 用量 | `/shoplazza-billing` |

### 需要留意的域边界

有些任务位于两个域的交界处，技能这样路由：

* **礼品卡**在 `products`，不在 `discounts`。
* **按邮箱查订单**在 `orders`;**客户资料**本身在 `customers`。
* **买家退款**在 `orders`，不在 billing。
* **页面与卡片装修**在 `themes`；自定义页面和博客的内容仍在 `shop`。

## 安全协议

地基技能 `shoplazza-common` 为破坏性（取消、删除）、批量以及动钱的写操作（如退款、收费）规定了安全协议：

1. **预览** —— 用 `--dry-run` 运行命令，只打印请求而不发送。
2. **复述** —— 概述该操作会改动什么。
3. **确认** —— 等你明确确认后再执行。

其他写操作，比如用 `+` 快捷命令建商品或建折扣，在必填值确认后直接执行；缺价格或金额时智能体会问你，而不是自己编。协议实操见[退款与删除示例](./usage/orders#4-部分退款资金操作)。

## 下一步

* [使用示例：商品](./usage/products)
* [使用示例：折扣](./usage/discounts)
* [使用示例：订单](./usage/orders)