Skip to main content

​
Custom Slash Commands

In Trellis 0.5, only three slash commands ship out of the box (/trellis:start, /trellis:finish-work, /trellis:continue); anything else that used to be a command has moved to auto-trigger skills (see chapter 12). Use slash commands when you need an explicit entry point that the user will invoke on demand.

​
Command File Format and Location

Trellis groups the 13 configured platforms into three delivery models: Explicit slash commands — the user types /trellis:<name>; the platform injects the command file’s content as a prompt.
PlatformLocationInvoked as
Claude Code.claude/commands/trellis/{name}.md/trellis:{name}
Cursor.cursor/commands/trellis-{name}.md/trellis-{name}
OpenCode.opencode/commands/trellis/{name}.md/trellis:{name}
Codex.codex/prompts/trellis-{name}.md/trellis-{name}
Gemini CLI.gemini/commands/trellis/{name}.toml/trellis:{name}
CodeBuddy.codebuddy/commands/trellis/{name}.md/trellis:{name}
Droid.factory/commands/trellis/{name}.md/trellis:{name}
Copilot.github/prompts/trellis-{name}.prompt.mdprompt-file picker
Command files are Markdown; Gemini uses TOML (with a prompt = """...""" field). Workflow files — platforms without a dedicated slash-command primitive; the user runs a “workflow” by name.
PlatformLocationInvoked as
Kilo.kilocode/workflows/{name}.md/{name}.md (Kilo’s workflow UI)
Antigravity.agent/workflows/{name}.mdopened from .agent/workflows/
Windsurf.windsurf/workflows/trellis-{name}.md/trellis-{name}
Skill-only — platforms that do not expose a slash-command primitive at all; start / finish-work / continue are shipped as auto-trigger skills.
Platformstart / finish-work / continue as…Invoked as
Kiro.kiro/skills/trellis-{name}/SKILL.mdskill match (or @trellis:{name})
Qoder.qoder/skills/trellis-{name}/SKILL.mdauto-triggered by user intent match

​
When to use a command vs. a skill

Use a slash command when…Use a skill when…
The user should decide when to run itThe AI should trigger it automatically based on intent
It marks a session boundary (start, finish, resume)It’s a phase inside a task (before-dev, check, update-spec)
There’s no natural trigger phrase that would match reliablyThere’s a predictable user intent you can match on
You need it available even when no task is activeIt only makes sense in the context of an active task
If the answer is “both”, ship a skill and expose a command that manually triggers the skill.

​
Writing a command

A good command file:
  1. Starts with a one-line description of what will happen.
  2. Lists the steps the AI should take, in order.
  3. Specifies files the AI should read before acting.
  4. Defines the expected output format (report, checklist, diff, etc.).
Template: 
# Command Name

Brief description of what this command does.

## Read context

```bash
cat .trellis/spec/relevant-spec.md
```

## Analyze

Describe what to analyze and against which rules.

## Report

Output format and fields.

​
Example: a /trellis:deploy-check command

.claude/commands/trellis/deploy-check.md: 
# Deploy Check

Pre-deployment verification checklist.

## Read deployment config

```bash
cat deploy.config.js
cat .env.production
```

## Verify

Check these items:
- [ ] All tests pass
- [ ] No TODO comments in production code
- [ ] Environment variables are set
- [ ] Database migrations are up to date
- [ ] API endpoints are documented

## Report

Output a deployment readiness report.
To ship the same command on other platforms, create parallel files in the platform-specific locations from the table in §9.1. If you want Trellis to distribute the command as part of its update flow, place a canonical copy under packages/cli/src/templates/common/commands/ and add platform adapters in packages/cli/src/configurators/.