docs: document plugin slash commands (#1253)

docs/en/customization/plugins.md

@@ -158,8 +158,71 @@ Supported fields:
 | `skillInstructions` | Additional instructions appended whenever a Skill from this plugin is loaded |
 | `mcpServers` | MCP server declarations; enabled by default, can be disabled from `/plugins` |
 | `hooks` | Hook rules run on lifecycle events while the plugin is enabled; see [Hooks in Plugins](#hooks-in-plugins) |
+| `commands` | One or more `./` paths pointing to a directory or `.md` file; registers the Markdown files within as slash commands. See [Plugin Slash Commands](#plugin-slash-commands) |
 
-Unsupported runtime fields such as `tools`, `commands`, `apps`, `inject`, and `configFile` appear as diagnostics and are ignored.
+Unsupported runtime fields such as `tools`, `apps`, `inject`, and `configFile` appear as diagnostics and are ignored.
+
+## Plugin Slash Commands
+
+Slash commands save a prompt you use often as a `/command`, so you can trigger it by typing the command instead of retyping the whole thing.
+
+Here is a minimal end-to-end example. The plugin's directory structure:
+
+```text
+kimi-finance/
+  kimi.plugin.json
+  commands/
+    report.md
+```
+
+In the manifest (`kimi.plugin.json`), the `commands` field points to where the command files live:
+
+```json
+{
+  "name": "kimi-finance",
+  "version": "1.0.0",
+  "commands": "./commands/"
+}
+```
+
+The command file `commands/report.md`. The block between the two `---` lines at the top is frontmatter (metadata describing the command); everything below is the prompt sent to the Agent:
+
+```markdown
+---
+description: Pull and summarize a stock's latest financials
+---
+
+Pull the latest financials for $ARGUMENTS and summarize revenue, profit, and key risks.
+```
+
+After installing and enabling the plugin, type this in the chat:
+
+```text
+/kimi-finance:report TSLA
+```
+
+Kimi replaces `$ARGUMENTS` in the body with `TSLA`, then runs the prompt. The three details below cover each step.
+
+### Declaring Commands (the `commands` field)
+
+`commands` takes a single `./` path or an array of paths, each pointing to a directory or `.md` file inside the plugin root:
+
+- Pointing at a **directory**: collects every `.md` file under it recursively; each becomes one command.
+- Pointing at a **single `.md` file**: registers just that one.
+- Pointing at a non-`.md` file or a missing path: appears as a diagnostic (shown in the `/plugins` panel) and is ignored.
+
+### Writing a Command File
+
+A command file has two parts: an optional **frontmatter** (the metadata between the two `---` lines at the top, where you set `name` and `description`) and the **body** (the prompt after the `---`). When a field is omitted, it falls back as follows:
+
+- `name` (the command name): derived from the file's path relative to the declared `commands` path (without `.md`, using `/` separators), e.g. `commands/frontend/component.md` → `frontend/component`. A `name` set in the frontmatter takes precedence.
+- `description` (shown in the command list): the first non-empty line of the body (truncated past 240 characters); if the body is empty too, `No description provided.` is shown.
+
+### Running Commands and Passing Arguments
+
+Commands are prefixed with the plugin id (their namespace) and registered as `<plugin>:<command>`, so the command above is actually `/kimi-finance:report` — this keeps same-named commands from different plugins from colliding.
+
+Whatever you type after the command replaces `$ARGUMENTS` in the body (above, `TSLA` replaces `$ARGUMENTS`). If the body has no `$ARGUMENTS` but you pass arguments anyway, they are not dropped — they are appended to the end of the body as `ARGUMENTS: <what you typed>`.
 
 ## Skills and Session Start
 

docs/zh/customization/plugins.md

@@ -158,8 +158,71 @@ Plugin 是一个带 manifest 的目录或 zip 文件。Manifest 可以放在以
 | `skillInstructions` | 每次加载此 plugin 的 Skill 时一并附带的额外说明 |
 | `mcpServers` | MCP server 声明，默认启用，可从 `/plugins` 中禁用 |
 | `hooks` | 在 plugin 启用期间于生命周期事件上运行的 hook 规则；见[插件中的 Hooks](#插件中的-hooks) |
+| `commands` | 一个或多个 `./` 路径，指向目录或 `.md` 文件，把其中的 Markdown 文件注册为斜杠命令；见[插件斜杠命令](#插件斜杠命令) |
 
-`tools`、`commands`、`apps`、`inject`、`configFile` 等不支持的运行时字段会显示为 diagnostics 并被忽略。
+`tools`、`apps`、`inject`、`configFile` 等不支持的运行时字段会显示为 diagnostics 并被忽略。
+
+## 插件斜杠命令
+
+斜杠命令把一段常用提示词存成 `/命令`，输入它就能触发，省得每次重打。
+
+下面是一个最小完整例子，插件目录结构：
+
+```text
+kimi-finance/
+  kimi.plugin.json
+  commands/
+    report.md
+```
+
+manifest（`kimi.plugin.json`）用 `commands` 字段指出命令文件的位置：
+
+```json
+{
+  "name": "kimi-finance",
+  "version": "1.0.0",
+  "commands": "./commands/"
+}
+```
+
+命令文件 `commands/report.md`。顶部两行 `---` 之间是 frontmatter（描述命令的元数据），下面的正文是触发时发给 Agent 的提示词：
+
+```markdown
+---
+description: 拉取指定股票的财报并总结
+---
+
+拉取 $ARGUMENTS 的最新财报数据，总结营收、利润和关键风险。
+```
+
+装好并启用后，在对话里输入：
+
+```text
+/kimi-finance:report TSLA
+```
+
+Kimi 会把正文里的 `$ARGUMENTS` 替换成 `TSLA`，再执行这段提示词。三处细节分述如下。
+
+### 声明命令（`commands` 字段）
+
+`commands` 填一个 `./` 路径或路径数组，指向 plugin 根目录内的目录或 `.md` 文件：
+
+- 指向**目录**：递归收集其中所有 `.md` 文件，每个各成为一个命令。
+- 指向**单个 `.md` 文件**：只注册这一个。
+- 指向非 `.md` 或不存在的路径：显示为 diagnostics（`/plugins` 面板里的诊断提示）并被忽略。
+
+### 编写命令文件
+
+命令文件分两部分：可选的 **frontmatter**（顶部两行 `---` 之间的元数据，可写 `name`、`description`）和**正文**（`---` 之后的提示词）。两个字段省略时的回退规则：
+
+- `name`（命令名）：省略时用文件相对 `commands` 路径的路径命名（去 `.md`、`/` 分隔），如 `commands/frontend/component.md` → `frontend/component`；frontmatter 里显式写的优先。
+- `description`（命令列表里的说明）：省略时取正文首行非空文字（超 240 字符截断）；正文也为空则显示 `No description provided.`。
+
+### 调用命令与传参
+
+命令自动以插件 id 作前缀（即命名空间），注册成 `<插件名>:<命令名>`，所以上面的命令实际叫 `/kimi-finance:report`，不同插件的同名命令因此不会冲突。
+
+命令后输入的文字会替换正文里的 `$ARGUMENTS`（上例中 `TSLA` 替换掉 `$ARGUMENTS`）。若正文没写 `$ARGUMENTS` 却传了参数，参数不会丢弃，而是以 `ARGUMENTS: <你输入的内容>` 追加到正文末尾。
 
 ## Skills 与会话启动