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

markdown
1---
2description: Analyze this code for performance issues and suggest optimizations
3---
4
5Analyze 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

markdown
1## Objective
2
3What needs to happen and why this matters.
4Context about who uses this and what it accomplishes.

## Process - How to execute the command

markdown
1## Process
2
31. First step
42. Second step
53. Final step

## Success Criteria - How to know the command succeeded

markdown
1## Success Criteria
2
3- Clear, measurable criteria for successful completion.

Conditional Sections

## Context - When loading dynamic state or files

markdown
1## Context
2
3Current state: ! `git status`
4Relevant files: @ package.json

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

## Verification - When producing artifacts that need checking

markdown
1## Verification
2
3Before completing, verify:
4
5- Specific test or check to perform
6- How to confirm it works

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

markdown
1## Testing
2
3Run tests: ! `npm test`
4Check linting: ! `npm run lint`

## Output - When creating/modifying specific files

markdown
1## Output
2
3Files created/modified:
4
5- `./path/to/file.ext` - Description

Structure Example

markdown
1---
2name: example-command
3description: Does something useful
4argument-hint: [input]
5---
6
7## Objective
8
9Process #$ARGUMENTS to accomplish [goal].
10
11This helps [who] achieve [outcome].
12
13## Context
14
15Current state: ! `relevant command`
16Files: @ relevant/files
17
18## Process
19
201. Parse #$ARGUMENTS
212. Execute operation
223. Verify results
23
24## Success Criteria
25
26- Operation completed without errors
27- 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:

markdown
1## Objective
2
3Fix issue #$ARGUMENTS following project conventions.

In Process:

markdown
1## Process
2
31. Understand issue #$ARGUMENTS from issue tracker

In Context:

markdown
1## Context
2
3Issue details: @ issues/#$ARGUMENTS.md
4Related files: ! `grep -r "TODO.*#$ARGUMENTS" src/`

Positional Arguments

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

markdown
1---
2argument-hint: <pr-number> <priority> <assignee>
3---
4
5## Objective
6
7Review 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

yaml
1description: Analyze this code for performance issues and suggest optimizations

Field: allowed-tools

Optional - Restricts which tools Antigravity can use

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

Arguments Usage

All Arguments String

Use #$ARGUMENTS to capture all arguments strings.

markdown
1Fix 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.

markdown
1Review 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 !.

markdown
1## Context
2
3- Current git status: ! `git status`
4- Current git diff: ! `git diff HEAD`

Use @ prefix to reference specific files:

markdown
1Review 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

markdown
1---
2description: Review this code for security vulnerabilities
3---
4
5## Objective
6
7Review code for security vulnerabilities and suggest fixes.
8
9## Process
10
111. Scan code for common vulnerabilities
122. Identify specific issues
133. Suggest remediation
14
15## Success Criteria
16
17- All major vulnerability types checked
18- Issues identified with locations

Git Workflow with Context

markdown
1---
2description: Create a git commit
3allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
4---
5
6## Objective
7
8Create a git commit for current changes following repository conventions.
9
10## Context
11
12- Current status: ! `git status`
13- Changes: ! `git diff HEAD`
14- Recent commits: ! `git log --oneline -5`
15
16## Process
17
181. Review staged and unstaged changes
192. Stage relevant files
203. Write commit message
214. Create commit
22
23## Success Criteria
24
25- Commit created successfully
26- 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)