YouTip

Custom commands allow you to package commonly used prompts into a short command that can be executed with a single press in the TUI using `/command-name`, avoiding repeated input of the same prompts. For example, package the complex prompt "Run tests and analyze failure reasons" into `/test`, which can be triggered by entering just two characters each time. Custom commands are extensions beyond built-in commands like `/init`, `/undo`, `/redo`, `/share`, `/help`. > If your custom command has the same name as a built-in command, **the custom command will override the built-in command**. Avoid using `init`, `undo`, `redo`, `share`, `help` as custom command names unless you explicitly need to replace the built-in behavior. * * * ## Two Definition Methods Custom commands support two definition methods with identical effects, and you can choose based on personal preference: | Method | File | Use Case | | --- | --- | --- | | **JSON Configuration** | `command` field in `opencode.json` | Fewer commands, prefer centralized configuration management | | **Markdown File** | `.md` files in `commands/` directory | Longer command content, prefer maintaining each command separately | * * * ## Method One: JSON Configuration Define in the `command` field of `opencode.json`, where the key is the command name: ## Example { "$schema":"https://opencode.ai/config.json", "command":{ "test":{// Command name, invoked via /test in TUI "template":"Run the full test suite with coverage report and show any failures.n Focus on the failing tests and suggest fixes.", // template: The prompt content sent to LLM (required) "description":"Run tests with coverage", // description: Description shown in TUI command list (optional) "agent":"build",// agent: Specify the agent to execute this command (optional) "model":"anthropic/claude-3-5-sonnet-20241022" // model: Override the model used for this command (optional) } } } After configuration, enter `/test` in the TUI input box and press Enter to execute the command. * * * ## Method Two: Markdown File Create `.md` files in the `commands/` directory to define commands, **where the filename is the command name**. The file content consists of two parts: * **Frontmatter** (YAML section wrapped by `---`): Defines command properties * **Body** (content below Frontmatter): Becomes the prompt template sent to LLM Markdown files support two storage locations: * **Project-level:** `.opencode/commands/command-name.md` (only effective for current project) * **Global:** `~/.config/opencode/commands/command-name.md` (effective for all projects) --- 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. The filename is `test.md`, so the command name is `test`, invoked via `/test` in the TUI. * * * ## Prompt Template Syntax The command prompt (`template` field or Markdown body) supports the following special syntax, allowing prompts to dynamically respond to parameters, inject command output in real-time, or reference file content. ### 1、Passing Arguments ($ARGUMENTS) Use the `$ARGUMENTS` placeholder to receive arguments passed when invoking the command, inserted as a single string: --- description: Create a new React component --- Create a new React component named $ARGUMENTS with TypeScript support. Include proper typing and basic structure. When invoking, append arguments after the command name: /component Button `$ARGUMENTS` will be replaced with `Button`, and the actual executed prompt becomes: Create a new React component named Button with TypeScript support.Include proper typing and basic structure. ### 2、Positional Parameters ($1, $2, $3…) When needing to pass multiple independent arguments, you can use positional parameters `$1`, `$2`, `$3` to reference each argument separately, separated by spaces, with arguments containing spaces wrapped in quotes: --- description: Create a new file with content --- Create a file named $1 in the directory $2 with the following content: $3 Invocation example (arguments with spaces wrapped in quotes): /create-file config.json src "{ "key": "value" }" Placeholder replacement results: | Placeholder | Replaced With | | --- | --- | | `$1` | `config.json` | | `$2` | `src` | | `$3` | `{ "key": "value" }` | ### 3、Inject Shell Command Output (!`command`) Using the `!`shell command`` syntax allows running a Shell command during command execution and directly inserting its output into the prompt. Shell commands run in the **project root directory**. This is useful when needing the LLM to analyze real-time data (such as test results, git logs, etc.): --- description: Analyze test coverage --- Here are the current test results: !`npm test` Based on these results, suggest improvements to increase coverage. --- description: Review recent git changes --- Recent git commits: !`git log --oneline -10` Review these changes and suggest any improvements or potential issues. When executing the command, `!`git log --oneline -10`` will be replaced with the actual git log output, then sent to the LLM along with the prompt. ### 4、Reference File Content (@file path) Using the `@file path` syntax can automatically include the content of the specified file in the prompt without manual copy-pasting: --- description: Review a component for performance issues --- Review the component in @src/components/Button.tsx. Check for performance issues and suggest improvements. When executing the command, `@src/components/Button.tsx` will be replaced with the complete content of that file, allowing the LLM to directly analyze the file code. * * * ## Configuration Options Detailed Explanation Below are all configuration options supported by custom commands. In Markdown files, they are written in frontmatter; in JSON configuration, they are written under the command object: | Option | Required | Type | Description | | --- | --- | --- | --- | | `template` | Required (JSON method) | String | The prompt content sent to LLM. In Markdown method, the body is the template, no separate declaration needed | | `description` | Optional | String | Brief description of the command, displayed in TUI command list when entering `/`, helps quickly identify command purpose | | `agent` | Optional | String | Specifies the agent name to execute this command. Uses currently selected agent if not specified. If a subagent is specified, the command triggers subagent invocation by default | | `subtask` | Optional | Boolean | Set to `true` to force command to run as subagent, avoiding polluting main session context. Set to `false` to disable subagent invocation behavior | | `model` | Optional | String | Override the model used for this command, format is `provider/model-id`, such as `anthropic/claude-3-5-sonnet-20241022` | ### Relationship Between agent and subtask `agent` and `subtask` together control the command's execution method: * If `agent` specifies a subagent (mode is subagent), the command **triggers subagent invocation by default**, executing in an isolated context without affecting the main session * If this behavior is not desired, set `subtask` to `false` to force execution in the main session * If `subtask` is set to `true`, regardless of the agent's `mode` setting, the command always runs as a subagent, suitable for scenarios requiring complete context isolation ## Example { "$schema":"https://opencode.ai/config.json", "command":{ "analyze":{ "template":"Analyze the codebase for potential security vulnerabilities.", "description":"Security analysis (runs independently, does not pollute main session)", "subtask":true,// Force subagent execution, analysis results do not occupy main session context "model":"anthropic/claude-3-5-sonnet-20241022" }, "review":{ "template":"Review the current code changes.", "description":"Code review (runs in current agent)", "agent":"plan",// Use plan agent to execute "subtask":false// Disable subagent invocation, runs in main session } } } * * * ## Comprehensive Usage Examples ### Example One: Multi-Parameter Code Generation Command --- 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. ### Example Two: Code Review Command Combining Shell Output and File References --- 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). ### Example Three: Scheduled Data Snapshot Command (JSON Method) { "$schema": "https://opencode.ai/config.json", "command": { "healthcheck": { "description": "Check project health status", "template": "Analyze the project health based on the following data:nnDependency vulnerabilities:n!`npm audit --json`nnOutdated packages:n!`npm outdated`nnTest results:n!`npm test -- --passWithNoTests 2>&1 | tail -20`nnSummarize the issues by severity and suggest a prioritized action plan.", "model": "anthropic/claude-3-5-sonnet-20241022", "subtask": true } }}