OpenCode カスタムコマンド

カスタムコマンドを使用すると、よく使うプロンプトを短いコマンドにカプセル化し、TUIで/コマンド名と入力するだけで実行でき、同じプロンプトを繰り返し入力する手間を省けます。

例えば、「テストを実行して失敗原因を分析する」という複雑なプロンプトを/testにカプセル化すれば、毎回2文字入力するだけで実行できます。

カスタムコマンドは、/init、/undo、/redo、/share、/helpなどのビルトインコマンド以外の拡張機能です。

定義したカスタムコマンドがビルトインコマンドと同じ名前の場合、カスタムコマンドがビルトインコマンドを上書きします。次の使用は避けてください：init、undo、redo、share、helpをカスタムコマンド名として使用すること。ただし、ビルトインの動作を明示的に置き換える必要がある場合を除きます。

2つの定義方法

カスタムコマンドは2つの定義方法をサポートしており、効果は完全に同じです。個人の習慣に合わせて選択できます：

方法1：JSON設定

にopencode.jsonのcommandフィールドで定義し、キー名がそのままコマンド名になります：

設定が完了したら、TUIの入力ボックスに/testと入力してEnterキーを押すと、コマンドを実行できます。

方法2：Markdownファイル

にcommands/ディレクトリに.mdファイルを作成してコマンドを定義します。ファイル名がそのままコマンド名になります。ファイルの内容は2つの部分に分かれます：

• Frontmatter（---で囲まれたYAML部分）：コマンドの属性を定義します
• 本文（Frontmatterより下の内容）：LLMに送信するプロンプトテンプレートになります

Markdownファイルの保存場所は2か所サポートされています：

• プロジェクトレベル：.opencode/commands/命令名.md（現在のプロジェクトのみ有効）
• グローバル：~/.config/opencode/commands/命令名.md（すべてのプロジェクトで有効）

<!-- 文件路径：.opencode/commands/test.md -->
---
description: Run tests with coverage
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

このファイル名はtest.mdであるため、コマンド名はtestとなり、TUIでは/testとして呼び出します。

プロンプトテンプレート構文

コマンドのプロンプト（templateフィールドまたはMarkdown本文）は以下の特殊構文をサポートしており、プロンプトがパラメータに動的に応答したり、コマンド出力をリアルタイムに注入したり、ファイル内容を参照したりできます。

1、引数の受け渡し（$ARGUMENTS）

を使用すると、$ARGUMENTSプレースホルダーがコマンド呼び出し時に渡された引数を受け取り、全体が1つの文字列として挿入されます：

<!-- 文件路径：.opencode/commands/component.md -->
---
description: Create a new React component
---

Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing and basic structure.

呼び出し時にコマンド名の後ろに引数を追加します：

/component Button

$ARGUMENTSはButtonに置き換えられ、実際に実行されるプロンプトは次のようになります：

Create a new React component named Button with TypeScript support.
Include proper typing and basic structure.

2、位置パラメータ（$1、$2、$3…）

複数の独立した引数を渡す必要がある場合は、位置パラメータ$1、$2、$3を使用して各引数を個別に参照します。スペース区切りで、スペースを含む引数は引用符で囲みます：

<!-- 文件路径：.opencode/commands/create-file.md -->
---
description: Create a new file with content
---

Create a file named $1 in the directory $2
with the following content: $3

呼び出し例（スペースを含む引数は引用符で囲みます）：

/create-file config.json src "{ \"key\": \"value\" }"

各プレースホルダーの置換結果：

3、Shellコマンド出力の注入（!`command`）

を使用すると、!`shell命令`構文でコマンド実行時にShellコマンドを実行し、その出力結果をプロンプトに直接挿入できます。Shellコマンドはプロジェクトルートディレクトリで実行されます。これは、LLMにリアルタイムデータ（テスト結果、gitログなど）を分析させる場合に非常に便利です：

<!-- 文件路径：.opencode/commands/analyze-coverage.md -->
---
description: Analyze test coverage
---

Here are the current test results:
!`npm test`

Based on these results, suggest improvements to increase coverage.

<!-- 文件路径：.opencode/commands/review-changes.md -->
---
description: Review recent git changes
---

Recent git commits:
!`git log --oneline -10`

Review these changes and suggest any improvements or potential issues.

コマンド実行時、!`git log --oneline -10`は実際のgitログ出力に置き換えられ、プロンプトとともにLLMに送信されます。

4、ファイル内容の参照（@ファイルパス）

を使用すると、@ファイルパス構文で指定したファイルの内容をプロンプトに自動的に含めることができ、手動でのコピー＆ペーストは不要です：

<!-- 文件路径：.opencode/commands/review-component.md -->
---
description: Review a component for performance issues
---

Review the component in @src/components/Button.tsx.
Check for performance issues and suggest improvements.

コマンド実行時、@src/components/Button.tsxはそのファイルの完全な内容に置き換えられ、LLMはファイルのコードを直接分析できます。

設定オプションの詳細

以下はカスタムコマンドがサポートするすべての設定オプションです。Markdownファイルではfrontmatterに、JSON設定ではコマンドオブジェクト内に記述します：

agent と subtask の関係

agentとsubtaskagent と subtask は、コマンドの実行方法を共同で制御します：

• 若 agent指定されたのが子エージェント（modeがsubagent）の場合、コマンドはデフォルトで子エージェント呼び出しをトリガーし、独立したコンテキストで実行されるため、メインセッションには影響しません
• この動作を望まない場合は、subtaskをfalseに設定すると、メインセッションでの実行を強制できます
• また、subtaskをtrueに設定すると、エージェントのmode設定に関係なく、コマンドは常に子エージェントモードで実行されます。コンテキストを完全に分離する必要があるシーンに適しています

総合使用例

例1：複数パラメータのコード生成コマンド

<!-- 文件路径：.opencode/commands/gen-api.md -->
---
description: Generate a REST API endpoint
agent: build
---

Generate a $1 REST API endpoint for the resource "$2".
Place the file in the $3 directory.
Include input validation, error handling, and JSDoc comments.

<!-- 调用示例：/gen-api POST user src/api -->
<!-- $1 = POST，$2 = user，$3 = src/api -->

例2：Shell出力とファイル参照を組み合わせたコードレビューコマンド

<!-- 文件路径：.opencode/commands/pr-review.md -->
---
description: Review changes in current branch against main
agent: plan
subtask: true
---

Please review the following changes for code quality, potential bugs, and security issues.

## Recent commits
!`git log main..HEAD --oneline`

## Changed files
!`git diff main --name-only`

## Diff content
!`git diff main`

## Project coding guidelines
@.opencode/AGENTS.md

Provide structured feedback with severity levels (critical / warning / suggestion).

例3：定期データスナップショットコマンド（JSON方式）

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "healthcheck": {
      "description": "Check project health status",
      "template": "Analyze the project health based on the following data:\n\nDependency vulnerabilities:\n!`npm audit --json`\n\nOutdated packages:\n!`npm outdated`\n\nTest results:\n!`npm test -- --passWithNoTests 2>&1 | tail -20`\n\nSummarize the issues by severity and suggest a prioritized action plan.",
      "model": "anthropic/claude-3-5-sonnet-20241022",
      "subtask": true
    }
  }
}