# skill.md 和可安装 Skill 有什么区别

用小白能看懂的方式说明普通 skill.md 与可通过 npx skills 安装的 Kaien GPT Image 2 Skill。

这里有两个名字很像的东西，但用途不同：

| 名称 | 要不要安装 | 用来做什么 |
|---|---|---|
| `https://kaienapi.com/docs/skill.md` | 不需要 | 给 Agent 阅读 Kaien API 的接口说明和安全规则 |
| `kaien-gpt-image-2` | 需要用 `npx skills` 安装 | 让 Agent 自动生成图片、等待结果并保存到本地 |

如果你只是想让 Codex、Claude Code 或 Cursor 帮你生图，直接阅读 [Agent 生图入门教程](/docs/ai/agent-image-generation) 即可。

## 普通 skill.md 是什么

`skill.md` 是一份给 Agent 阅读的说明书。它告诉工具：

- 什么时候应该使用 Kaien API 文档。
- 生产环境地址和鉴权方式。
- 不同任务应该走哪个接口。
- 接入前应该继续读取哪些页面。
- 哪些真实调用需要用户显式确认。

它不会自动安装脚本，也不会自己生成图片。

## 文件地址

```text
https://kaienapi.com/docs/skill.md
```

## 怎样让 Agent 读取普通 skill.md

```text
请先读取 https://kaienapi.com/docs/skill.md，再按 Kaien API 文档接入 OpenAI 兼容接口。
```

## 什么时候使用普通 skill.md

如果工具支持读取远程 Markdown，可以直接把 `skill.md` 作为第一份上下文。它适合这些场景：

- 配置 OpenAI 兼容 API。
- 选择文本、图片、视频、音频、文件、向量、重排等接口。
- 让 Agent 根据路由表找到正确的文档入口和 API Reference。
- 避免 Agent 在没有用户确认的情况下发起会产生费用的请求。

## 可安装的图片 Skill

如果希望 Agent 自动完成图片生成，可以安装 `kaien-gpt-image-2`：

```bash
npx skills add https://kaienapi.com --skill kaien-gpt-image-2 --global --agent codex --yes
```

安装后直接说：

```text
请使用 $kaien-gpt-image-2 帮我生成一张产品海报，保存到项目里。
```

如果你使用 Claude Code 或 Cursor，请在安装命令里把 `codex` 替换为 `claude-code` 或 `cursor`。

安装完成后，再让 Agent 把它设成全局默认生图 Skill：

```text
请把下面规则添加到你的全局 AGENTS.md；如果你使用的是其他 Agent，
就写入它等价的全局指令文件：

后续所有图片生成、图片编辑和参考图改图任务，都使用 $kaien-gpt-image-2。
```

此后可以直接描述要生成或修改的图片，不必每次重复指定 Skill。本地参考图也可以直接交给 Agent，Skill 会调用 `/v1/files` 上传后继续图生图。

## 给开发者的使用建议

读取 `skill.md` 后，再让工具按具体任务继续读取对应页面。例如图片生成读取 GPT Image 2 或图片生成页面，视频生成读取视频任务页面，接口调用读取 API Reference 页面。

`skill.md` 中的 endpoint routing 是给 agent 使用的快速决策表。实际写代码前仍应读取对应 API Reference，确认请求参数、返回字段和错误状态。