Skip to main content

​
What are Commands?

Commands are slash commands (e.g., /ct-check) that provide quick entry points to specific workflows. They parse arguments, validate inputs, and invoke skills or agents with the right context.
Commands are the user-facing API for your plugin. They should be memorable, concise, and clearly describe what they do.

​
Command Structure

Commands are markdown files in the commands/ directory with YAML frontmatter: 
plugins/my-plugin/
  commands/
    command-name.md       # Command implementation
    another-command.md    # Additional commands

​
Frontmatter Format

command-name.md
---
name: namespace:command-name
description: Brief description of what the command does
argument-hint: "<required-arg> [optional-arg] [--flag]"
allowed-tools:
  - Bash
  - Read
  - Grep
---

​
Frontmatter Fields

​
name
string
required
Command name with optional namespace. Format: namespace:command-name or just command-name.Examples:
  • trailofbits:ct-check (namespaced)
  • scan-apk (no namespace)
​
description
string
required
Brief description shown in command palette and help text.
​
argument-hint
string
Argument syntax shown to users. Use angle brackets for required args, square brackets for optional.Example: "<source-file> [--warnings] [--json] [--arch <arch>]"
​
allowed-tools
array
List of tools the command can use. Same as skill allowed-tools.

​
Command Body

The markdown body contains instructions for Claude on how to handle the command:
command-name.md
---
name: trailofbits:ct-check
description: Detects timing side-channels in cryptographic code
argument-hint: "<source-file> [--warnings] [--json] [--arch <arch>]"
allowed-tools:
  - Bash
  - Read
  - Grep
  - Glob
---

# Check Constant-Time Properties

**Arguments:** $ARGUMENTS

Parse arguments:
1. **Source file** (required): Path to source file to analyze
2. **Flags** (optional): `--warnings`, `--json`, `--arch <arch>`, `--opt-level <level>`, `--func <pattern>`

Invoke the `constant-time-analysis` skill with these arguments for the full workflow.
Use $ARGUMENTS to reference the arguments passed by the user.

​
Argument Parsing Patterns

​
Simple Arguments

**Arguments:** $ARGUMENTS

Parse arguments:
1. **File path** (required): Path to the file to process
2. **Output format** (optional): `--json` or `--text` (default: text)

​
Complex Arguments with Validation

**Arguments:** $ARGUMENTS

Parse and validate arguments:

1. **Required: Base branch**
   - Format: `main`, `develop`, or any valid branch name
   - Validate: Branch must exist in repository

2. **Required: Head branch**
   - Format: Branch name or commit SHA
   - Validate: Must exist and be different from base

3. **Optional flags:**
   - `--security-focus`: Prioritize security-relevant changes
   - `--verbose`: Include detailed analysis
   - `--format <json|markdown>`: Output format (default: markdown)

Validation steps:
1. Verify both branches exist: `git rev-parse --verify <branch>`
2. Verify branches are different
3. Check for uncommitted changes if analyzing current branch

​
Multiple Argument Forms

**Arguments:** $ARGUMENTS

Supports multiple forms:

**Form 1: File path**
/entry-points [file-path] 

**Form 2: Directory scan**
/entry-points [directory] —recursive 

**Form 3: Package analysis**
/entry-points —package [package-name] 

Parse based on first argument type:
- If path to file: analyze single file
- If path to directory: scan directory (use --recursive for subdirectories)
- If --package flag: analyze installed package

​
Invoking Skills

Commands typically invoke skills to perform the actual work: 
After parsing arguments, invoke the `skill-name` skill with the parsed context:

- Source file: [parsed file path]
- Analysis mode: [parsed mode]
- Output format: [parsed format]
Example from ct-check.md: 
Invoke the `constant-time-analysis` skill with these arguments for the full workflow.

​
Invoking Agents

Commands can also launch autonomous agents: 
Launch the `agent-name` agent with:
- Input: [parsed input]
- Configuration: [parsed config]
- Output path: [parsed output]

​
Real Examples

---
name: trailofbits:ct-check
description: Detects timing side-channels in cryptographic code
argument-hint: "<source-file> [--warnings] [--json] [--arch <arch>]"
allowed-tools:
  - Bash
  - Read
  - Grep
  - Glob
---

# Check Constant-Time Properties

**Arguments:** $ARGUMENTS

Parse arguments:
1. **Source file** (required): Path to source file to analyze
2. **Flags** (optional): `--warnings`, `--json`, `--arch <arch>`, 
   `--opt-level <level>`, `--func <pattern>`

Invoke the `constant-time-analysis` skill with these arguments for the 
full workflow.

---
name: diff-review
description: Performs differential security review between two git branches
argument-hint: "<base-branch> <head-branch> [--security-focus]"
allowed-tools:
  - Bash
  - Read
  - Grep
  - Glob
  - Write
---

# Differential Security Review

**Arguments:** $ARGUMENTS

Parse arguments:
1. **Base branch** (required): The baseline branch (e.g., `main`)
2. **Head branch** (required): The branch with changes to review
3. **Flags** (optional):
   - `--security-focus`: Prioritize security-relevant changes
   - `--verbose`: Include detailed analysis

Validation:
1. Verify both branches exist
2. Check for uncommitted changes
3. Verify branches are different

Launch the `differential-reviewer` agent with the parsed configuration.

---
name: entry-points
description: Analyzes entry points in code to map attack surface
argument-hint: "<file-or-directory> [--recursive] [--format <json|text>]"
allowed-tools:
  - Bash
  - Read
  - Grep
  - Glob
  - Write
---

# Analyze Entry Points

**Arguments:** $ARGUMENTS

Supports:
- Single file: `/entry-points src/main.rs`
- Directory: `/entry-points src/`
- Recursive: `/entry-points src/ --recursive`

Parse arguments:
1. **Target** (required): File path or directory path
2. **Flags** (optional):
   - `--recursive`: Scan subdirectories
   - `--format <json|text>`: Output format (default: text)
   - `--filter <pattern>`: Filter by function name pattern

Invoke the `entry-point-analyzer` skill with parsed configuration.

---
name: audit-context
description: Builds comprehensive security audit context for a codebase
argument-hint: "<target-directory> [--depth <1|2|3>] [--focus <area>]"
allowed-tools:
  - Bash
  - Read
  - Grep
  - Glob
  - Write
---

# Build Audit Context

**Arguments:** $ARGUMENTS

Parse arguments:
1. **Target directory** (required): Root directory to analyze
2. **Analysis depth** (optional): 
   - `--depth 1`: High-level overview
   - `--depth 2`: Detailed analysis (default)
   - `--depth 3`: Ultra-granular per-function analysis
3. **Focus area** (optional): `--focus <crypto|auth|network|storage>`

Workflow:
1. Validate target directory exists
2. Determine analysis depth
3. Launch the `audit-context-builder` agent
4. If depth=3, also launch `function-analyzer` agent for critical paths
5. Generate consolidated report

​
Command Naming

Use Namespaces

For organization-wide plugins:trailofbits:ct-checkFor personal/project plugins:scan-apk

Be Descriptive

Good:
  • diff-review
  • entry-points
  • audit-context
Bad:
  • dr
  • ep
  • check

Use Verbs

Good:
  • scan-apk
  • analyze-contract
  • review-diff
Bad:
  • apk
  • contract
  • diff

Keep It Short

Good:
  • ct-check (constant-time check)
  • diff-review
Avoid:
  • constant-time-analysis-check
  • differential-security-review

​
Argument Hint Best Practices

Argument hints show users the expected syntax. Follow these conventions:
Use angle brackets: <argument-name>
"<source-file>"
"<base-branch> <head-branch>"

​
Command Discovery

Users discover commands through:
  1. Command palette - Shows all available commands with descriptions
  2. Autocomplete - Typing / shows command suggestions
  3. Help text - --help flag shows argument hints
Make sure your description and argument-hint are clear and informative.

​
Error Handling

Provide clear error messages when arguments are invalid: 
Validation steps:
1. If source file not provided:
   → Error: "Source file is required. Usage: /ct-check <source-file> [options]"

2. If source file doesn't exist:
   → Error: "File not found: {file-path}"

3. If invalid --arch value:
   → Error: "Invalid architecture: {arch}. Supported: x86, arm, mips"

4. If conflicting flags:
   → Error: "Cannot use --json and --text together. Choose one output format."

​
Testing Commands

1

Test with minimal arguments

/command-name required-arg
2

Test with all arguments

/command-name required-arg --flag1 --flag2 value
3

Test error cases

/command-name           # Missing required arg
/command-name invalid   # Invalid arg value
/command-name arg --invalid-flag
4

Test edge cases

/command-name "path with spaces"
/command-name ../relative/path
/command-name /absolute/path

​
Best Practices

Keep It Simple

Most commands should just parse arguments and invoke a skill or agent.

Validate Early

Check arguments before invoking expensive operations.

Provide Defaults

Make optional arguments truly optional with sensible defaults.

Clear Errors

Show helpful error messages with usage examples.

​
Next Steps

Skills

Learn how skills provide the logic commands invoke

Agents

Understand autonomous agents launched by commands

Create a Command

Learn how to author custom commands

Command Examples

Browse real command implementations

Build docs developers (and LLMs) love

Get started for freeTalk to us