---
title: "建立自定義命令"
description: "用自定義命令把重複提示詞沉澱成可複用入口。"
verifiedAt: "2026-05-09"
---

Custom commands 讓你把重複提示詞做成 TUI 裡的 `/xxx` 入口。它不是為了少打幾個字，而是把任務邊界、執行 agent、模型選擇、引數和輸出結構固定下來。

> [!NOTE]
> **這一篇用 10 分鐘換什麼**：你會知道什麼時候該寫 command、Markdown 和 JSON 兩種方式怎麼選、`$ARGUMENTS` / `$1` 怎麼用、`!` 和 `@` 怎麼注入上下文，以及為什麼不要隨便覆蓋內建命令。

## 先判斷該不該沉澱成 command

一條提示詞至少反覆用過幾次，再考慮寫成 command。

```mermaid
flowchart LR
    Prompt["一次性提示詞"] --> Repeat{"同類流程反覆出現?"}
    Repeat -->|否| Keep["繼續在對話裡寫"]
    Repeat -->|是| Stable{"邊界和輸出穩定?"}
    Stable -->|否| Improve["先打磨提示詞"]
    Stable -->|是| Command["寫成 /command"]
    Command --> Share{"團隊也需要?"}
    Share -->|是| Project["放 .opencode/commands/"]
    Share -->|否| Global["放 ~/.config/opencode/commands/"]

    style Command fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Project fill:#dcfce7,stroke:#22c55e
```

適合做成 command：

- 每週都會做的固定動作，例如測試、審查、生成釋出說明。
- 需要穩定輸出結構的動作，例如“先列風險，再給改法，再列測試”。
- 團隊希望統一做法的動作，例如 PR 自檢、遷移檢查、文件審查。

不適合：一次性問題、邊界還沒想清楚的複雜需求、開放式探索任務、已經有內建命令覆蓋的動作。

## 1. Markdown command 推薦起步

專案級命令放在 `.opencode/commands/`。例如：

```md title=".opencode/commands/test.md"
---
description: Run tests with coverage
agent: build
---

Run the full test suite with coverage report.
If anything fails, identify the failing case, likely cause, and smallest next fix.
```

文件名就是命令名。`test.md` 对应：

```text
/test
```

Markdown 文件更适合长 prompt，因为它容易阅读、review、版本化。项目命令可以提交到 Git，让团队使用同一套任务入口。

## 2. 全局和项目级怎么选

| 位置 | 适合什么 |
| --- | --- |
| `.opencode/commands/` | 当前仓库的测试、发布、迁移、PR 审查、文档检查 |
| `~/.config/opencode/commands/` | 个人跨项目通用命令，例如总结 diff、解释报错、整理提交信息 |

默认从项目级开始。只要 prompt 里引用了项目路径、测试命令、目录结构或团队规则，就不要放进全局。

## 3. JSON command 适合短命令

也可以在 `opencode.json` / `opencode.jsonc` 里用 `command` 配置。

```jsonc title="opencode.jsonc"
{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "review": {
      "template": "Review the current git diff. Focus on bugs, regressions, security, and missing tests.",
      "description": "Review current changes",
      "agent": "plan"
    }
  }
}
```

`template` 是必填项，`description` 会显示在 TUI 命令列表里。JSON 适合一两个短命令；长提示词、步骤和示例更适合 Markdown 文件。

## 4. 参数怎么用

`$ARGUMENTS` 代表命令后面的整段输入。

```md title=".opencode/commands/component.md"
---
description: Create a component plan
---

Create an implementation plan for $ARGUMENTS.
Include files to touch, edge cases, and tests.
```

运行：

```text
/component Button
```

这里 `$ARGUMENTS` 会变成 `Button`。

也可以使用位置参数：`$1`、`$2`、`$3`。但位置参数越多，命令越像脚本，越容易误用。新手优先用 `$ARGUMENTS`。

## 5. 注入 shell 输出和文件

Command prompt 可以使用 `!` 注入 shell 输出，也可以用 `@` 引用文件。

```md title=".opencode/commands/review-diff.md"
---
description: Review current diff
---

Current changes:
!`git diff --stat`
!`git diff`

Review only. Do not modify files.
```

檔案引用示例：

`Review @src/components/Button.tsx for performance and accessibility issues.`

> [!WARNING]
> `!` 會執行命令並把輸出放進 prompt。只讀命令適合，刪除、釋出、資料庫寫操作和修改全域性環境的命令不適合寫進 command。

## 6. agent、subtask 和 model

Command 可以指定執行它的 agent 和 model。

幾個邊界要記住：

- `agent` 可選；不指定時使用當前 agent。
- 如果 `agent` 是 subagent，官方文件說明 command 預設會觸發 subagent invocation。
- 如果不想讓 subagent 預設執行，可以設定 `subtask: false`。
- `subtask: true` 可以強制讓命令作為 subagent 執行，避免汙染主會話上下文。
- `model` 可以覆蓋當前預設模型，但只在確實需要特殊模型時配置，不要每個 command 都硬綁模型。

## 7. 不要覆蓋內建命令

OpenCode 已有 `/init`、`/undo`、`/redo`、`/share`、`/help` 等內建命令。官方文件說明 custom commands 可以覆蓋內建命令。

> [!CAUTION]
> 除非你明確知道後果，否則不要建立 `init.md`、`undo.md`、`share.md` 這類同名 command。要改變安全邊界，用 config 和 permission；不要靠覆蓋內建命令製造隱性行為。

## 8. 怎麼判斷寫對了

一個可交付的 command 應該滿足：

- 名字短，一眼能看懂。
- 一個 command 只做一類任務。
- 輸出結構穩定，不需要每次再補說明。
- 引數少，最好先用 `$ARGUMENTS`。
- shell 注入只用只讀命令。
- 專案級命令可 review、可刪除、可追蹤影響範圍。

如果每次執行還要補一大段解釋，說明 command 沒有把任務邊界寫清楚。

## 接下來去哪

<Cards>
  <Card title="配置" description="理解 command 應該放在專案配置、Markdown 檔案還是全域性配置。" href="/zh-Hant/docs/opencode/official/01-customization/config" />
  <Card title="Rules" description="長期約束寫進 rules，重複流程寫成 command，不要混用。" href="/zh-Hant/docs/opencode/official/02-agents-skills/rules" />
  <Card title="Agents" description="當 command 需要固定角色、模型或許可權時，再考慮自定義 agent。" href="/zh-Hant/docs/opencode/official/02-agents-skills/agents" />
  <Card title="TUI" description="Command 最終在 TUI 裡使用，先理解 `/` 命令和快捷鍵。" href="/zh-Hant/docs/opencode/official/00-getting-started/tui" />
</Cards>

## 官方資料

- OpenCode Commands：[https://opencode.ai/docs/commands](https://opencode.ai/docs/commands)
- OpenCode TUI Commands：[https://opencode.ai/docs/tui#commands](https://opencode.ai/docs/tui#commands)
- OpenCode Config：[https://opencode.ai/docs/config](https://opencode.ai/docs/config)
- OpenCode Agents：[https://opencode.ai/docs/agents](https://opencode.ai/docs/agents)
