Week 4: Custom Slash Commands¶

Slides for Live or Recorded Delivery¶

Slide 1: What Is a Custom Command?¶

A custom slash command is a templated prompt you save and reuse.

Instead of retyping:

"Run the full test suite, show me failures, and suggest fixes"

You type:

/test

Where they live: - .opencode/opencode.jsonc (project-local, shared with your team) - ~/.config/opencode/commands/ (personal, global across projects)

Slide 2: The Rule of Three¶

Write a command when you've typed the same prompt 3+ times.

This is not arbitrary. By the third time, you've proven: 1. The task is recurring 2. You have a consistent approach to it 3. Encoding it saves time and captures judgment

Before three: just ask the agent. Flexibility > automation.

Slide 3: Anatomy (Minimal)¶

{
  "command": {
    "test": {
      "template": "Run npm test. Show failures. Suggest fixes.",
      "description": "Run tests and suggest fixes"
    }
  }
}

Three required parts: - command block in opencode.jsonc - Command name (test) - template: the prompt the agent sees - description: brief label in the TUI

Slide 4: The $ARGUMENTS Placeholder¶

Commands with input use $ARGUMENTS:

{
  "command": {
    "component": {
      "template": "Create a React component named $ARGUMENTS with TypeScript and Tailwind."
    }
  }
}

Usage:

/component Button

$ARGUMENTS becomes Button. The template expands to: "Create a React component named Button with TypeScript and Tailwind."

Slide 5: Optional Fields: Agent & Model¶

Specify which agent and model to use:

{
  "command": {
    "security-check": {
      "template": "Audit this code for security vulns.",
      "agent": "code-reviewer",              // Subagent (read-only)
      "model": "anthropic/claude-opus-4-1"  // More powerful model
    }
  }
}

Why? - agent: Use a read-only subagent for audits (safer than full build access) - model: Use Opus for deep analysis, Haiku for quick tasks

Slide 6: Where Commands Live (Visual)¶

Project (shared with team):
  .opencode/opencode.jsonc
    └─ command.test
    └─ command.component
    └─ command.changelog

Home (personal):
  ~/.config/opencode/commands/
    ├─ changelog.jsonc
    ├─ write-tests.jsonc
    └─ format-docs.jsonc

Principle: Frequent, team-wide tasks → local. Personal workflows → global.

Slide 7: Demo Part 1 — /test¶

Scenario: Every PR, you run tests, find failures, ask the agent to fix them.

{
  "command": {
    "test": {
      "template": "Run npm test. Show the full output. For each failure, explain why and propose a fix. Ask permission before applying any changes.",
      "description": "Run full test suite with fixes",
      "agent": "build"
    }
  }
}

Live walkthrough: 1. Edit .opencode/opencode.jsonc 2. Add the command block above 3. Save and reload 4. Type /test in the TUI 5. Watch the agent run tests → find failures → suggest fixes

Slide 8: Demo Part 2 — /component ¶

Scenario: Every new React component should have TS, Tailwind, a test file, and an export.

{
  "command": {
    "component": {
      "template": "Create a React component named $ARGUMENTS in src/components/$ARGUMENTS.tsx. Use TypeScript (strict mode). Style with Tailwind CSS. Include a test file src/components/$ARGUMENTS.test.tsx. Export from src/components/index.ts.",
      "description": "Create a React component scaffold",
      "agent": "build"
    }
  }
}

Live walkthrough: 1. Add the command 2. Type /component LoginForm 3. Watch the agent create all three files (component, test, export)

Slide 9: Advanced: Shell Integration¶

Inject live data into prompts:

{
  "command": {
    "fix-tests": {
      "template": "Here are the test results:\n\n!npm test 2>&1\n\nFix each failure.",
      "description": "Fix failing tests"
    }
  }
}

The !command syntax: - Runs the command in your shell - Injects the output into the prompt - Agent always has fresh data

Slide 10: Advanced: File References¶

Include files in the prompt:

{
  "command": {
    "review-auth": {
      "template": "Security-audit this auth module for secrets, SQL injection, XSS.\n\n@src/auth.ts\n@src/db/queries.ts",
      "description": "Review auth module"
    }
  }
}

The @filename syntax includes the file content. Agent sees the code, can ask questions, propose fixes.

Slide 11: Common Mistakes¶

Mistake 1: Too Vague¶

❌ "template": "Make this better" ✓ "template": "Refactor for readability: use descriptive names, extract helpers, add comments."

Mistake 2: Too Specific¶

❌ "template": "Fix the password validation bug in LoginForm.tsx" ✓ "template": "Debug the failing test in $ARGUMENTS. Explain the root cause and fix it."

Mistake 3: Asking Permission Too Often¶

❌ "Should I add a test? [asks] Should I run it? [asks]" ✓ "Add a test, run it, show me the results."

Slide 12: Judgment: When NOT to Write a Command¶

Don't write a command if:

It's one-time work. (You write a login system once, not every week.)
It needs deep reasoning. (That's a skill or custom agent — Week 5–6.)
It's too vague. (/code is useless. /code-something-specific is better.)
It requires many arguments. (If you need 5+ inputs, use an interactive agent instead.)

The question: "Will I use this exact prompt 3+ times?" If not, just ask.

Slide 13: Recap¶

Commands: Templated prompts saved in .opencode/opencode.jsonc
When to use: You've typed the prompt 3+ times
Anatomy: template + description + optional agent/model
Parameterization: Use $ARGUMENTS for user input
Advanced: Shell integration (!command) and file refs (@file)
Judge wisely: Not every task is command-worthy

Next: Skills — commands' cousin, which the agent discovers and uses without you invoking.

Slide 14: Your Turn — Lab 4.1¶

This week, you'll author three personal commands tailored to work you do often.

Examples: - /explain-file — explain a file's purpose - /write-tests — write unit tests for a function - /changelog — draft a changelog entry - /refactor — refactor code for readability

See lab-4.1-three-commands.md for the full walkthrough.