create-slash-commands

Objective

Create effective slash commands for Antigravity that enable users to trigger reusable prompts with /command-name syntax. Slash commands expand as prompts in the current conversation, allowing teams to standardize workflows and operations.

Commands can be global (available everywhere in ~/.agent/commands/) or project-specific (shared with team in .agent/commands/). This skill teaches you to structure commands with proper formatting (Markdown), YAML frontmatter, dynamic context loading, and intelligent argument handling.

CRITICAL WORKFLOW: This skill enforces a mandatory research phase where you MUST:

1. Read all reference documentation
2. Examine existing slash commands for patterns
3. Understand syntax and best practices
4. Only then create the command

This prevents poorly-structured commands and ensures consistency with established patterns.

Quick Start

Workflow

1. Create .agent/commands/ directory (project) or use ~/.agent/commands/ (personal)
2. Create command-name.md file
3. Add YAML frontmatter (at minimum: description)
4. Write command prompt
5. Test with /command-name [args]

Example

File: .agent/commands/optimize.md

---
description: Analyze this code for performance issues and suggest optimizations
---

Analyze the performance of this code and suggest three specific optimizations:

Usage: /optimize

Antigravity receives the expanded prompt and analyzes the code in context.

Markdown Structure

Slash commands should use Markdown headings (Headers) in the body (after YAML frontmatter).

Format:

• Markdown Headers: The standard for Antigravity commands (## Objective, ## Process)
• Compatibility: Antigravity parses Markdown headers effectively for instruction structuring.

Required Sections

## Objective - What the command does and why it matters

## Objective

What needs to happen and why this matters.
Context about who uses this and what it accomplishes.

## Process - How to execute the command

## Process

1. First step
2. Second step
3. Final step

## Success Criteria - How to know the command succeeded

## Success Criteria

- Clear, measurable criteria for successful completion.

Conditional Sections

## Context - When loading dynamic state or files

## Context

Current state: ! `git status`
Relevant files: @ package.json

(Note: Remove the space after @ in actual usage)

## Verification - When producing artifacts that need checking

## Verification

Before completing, verify:

- Specific test or check to perform
- How to confirm it works

## Testing - When running tests is part of the workflow

## Testing

Run tests: ! `npm test`
Check linting: ! `npm run lint`

## Output - When creating/modifying specific files

## Output

Files created/modified:

- `./path/to/file.ext` - Description

Structure Example

---
name: example-command
description: Does something useful
argument-hint: [input]
---

## Objective

Process #$ARGUMENTS to accomplish [goal].

This helps [who] achieve [outcome].

## Context

Current state: ! `relevant command`
Files: @ relevant/files

## Process

1. Parse #$ARGUMENTS
2. Execute operation
3. Verify results

## Success Criteria

- Operation completed without errors
- Output matches expected format

Intelligence Rules

Simple commands (single operation, no artifacts):

• Required: ## Objective, ## Process, ## Success Criteria
• Example: /check-todos, /first-principles

Complex commands (multi-step, produces artifacts):

• Required: ## Objective, ## Process, ## Success Criteria
• Add: ## Context (if loading state), ## Verification (if creating files), ## Output (what gets created)
• Example: /commit, /create-prompt, /run-prompt

Commands with dynamic arguments:

• Use #$ARGUMENTS in body
• Include argument-hint in frontmatter
• Make it clear what the arguments are for

Commands that produce files:

• Always include ## Output section specifying what gets created
• Always include ## Verification section with checks to perform

Commands that run tests/builds:

• Include ## Testing section with specific commands
• Include pass/fail criteria in ## Success Criteria

Arguments Intelligence

The skill should intelligently determine whether a slash command needs arguments.

Commands That Need Arguments

User provides specific input:

• /fix-issue [issue-number] - Needs issue number
• /review-pr [pr-number] - Needs PR number
• /optimize [file-path] - Needs file to optimize
• /commit [type] - Needs commit type (optional)

Pattern: Task operates on user-specified data Include argument-hint: [description] in frontmatter and reference #$ARGUMENTS in the body.

Commands Without Arguments

Self-contained procedures:

• /check-todos - Operates on known file (TO-DOS.md)
• /first-principles - Operates on current conversation
• /whats-next - Analyzes current context

Pattern: Task operates on implicit context (current conversation, known files, project state) Omit argument-hint and don't reference #$ARGUMENTS.

Incorporating Arguments

In Objective:

## Objective

Fix issue #$ARGUMENTS following project conventions.

In Process:

## Process

1. Understand issue #$ARGUMENTS from issue tracker

In Context:

## Context

Issue details: @ issues/#$ARGUMENTS.md
Related files: ! `grep -r "TODO.*#$ARGUMENTS" src/`

Positional Arguments

For structured input, use $1, $2, $3:

---
argument-hint: <pr-number> <priority> <assignee>
---

## Objective

Review PR #$1 with priority $2 and assign to $3.

Usage: /review-pr 456 high alice

File Structure

Project commands: .agent/commands/ (in project root)

• Shared with team via version control
• Project-specific workflows
• Shows (project) in /help list

Global commands: ~/.agent/commands/ (user home directory)

• Available across all your projects
• Personal productivity commands
• Shows (user) in /help list

Choosing between global and project:

• Use global for: Personal workflows, general utilities, commands you use everywhere
• Use project for: Team workflows, project-specific operations, shared conventions

YAML Frontmatter

Field: description

Required - Describes what the command does

description: Analyze this code for performance issues and suggest optimizations

Field: allowed-tools

Optional - Restricts which tools Antigravity can use

allowed-tools: [Read, Edit, Write]
# or
allowed-tools: Bash(git add:*)

Arguments Usage

All Arguments String

Use #$ARGUMENTS to capture all arguments strings.

Fix issue #$ARGUMENTS following our coding standards

Usage: /fix-issue 123 high-priority Received: "Fix issue #123 high-priority following our coding standards"

Positional Arguments

Use $1, $2 for split arguments.

Review PR #$1 with priority $2

Usage: /review-pr 456 high Received: "Review PR #456 with priority high"

Dynamic Context

Execute bash commands before the prompt using the exclamation mark prefix directly before backticks !.

## Context

- Current git status: ! `git status`
- Current git diff: ! `git diff HEAD`

Use @ prefix to reference specific files:

Review the implementation in @ src/utils/helpers.js

Best Practices

1. Always use Markdown Structure After frontmatter, use standard Markdown headers:

• ## Objective
• ## Process
• ## Success Criteria

2. Clear descriptions Write descriptive summaries for the /help list.

3. Use dynamic context for state-dependent tasks Load fresh status for git ops or tests.

4. Restrict tools when appropriate Use allowed-tools to prevent unintended actions (e.g. restrict to Analysis tools only).

5. Use #$ARGUMENTS for flexibility Let users specify files or IDs at runtime.

6. Reference relevant files Use @filename to load context automatically.

Common Patterns

Simple Analysis Command

---
description: Review this code for security vulnerabilities
---

## Objective

Review code for security vulnerabilities and suggest fixes.

## Process

1. Scan code for common vulnerabilities
2. Identify specific issues
3. Suggest remediation

## Success Criteria

- All major vulnerability types checked
- Issues identified with locations

Git Workflow with Context

---
description: Create a git commit
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
---

## Objective

Create a git commit for current changes following repository conventions.

## Context

- Current status: ! `git status`
- Changes: ! `git diff HEAD`
- Recent commits: ! `git log --oneline -5`

## Process

1. Review staged and unstaged changes
2. Stage relevant files
3. Write commit message
4. Create commit

## Success Criteria

- Commit created successfully
- Message follows conventions

Reference Guides

Slash command specific references:

• arguments.md
• patterns.md
• tool-restrictions.md
• prompt-examples.md

Generation Protocol (See mandatory research steps in previous sections)