<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 (XML or Markdown), YAML frontmatter, dynamic context loading, and intelligent argument handling.

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

•Read all reference documentation
•Examine existing slash commands for patterns
•Understand syntax and best practices
•Only then create the command

This prevents poorly-structured commands and ensures consistency with established patterns. </objective>

<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]` </workflow> <example> **File**: `.agent/commands/optimize.md`

markdown

---
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. </example> </quick_start>

<xml_structure> Slash commands can use either XML tags OR Markdown headings in the body (after YAML frontmatter).

Format choice depends on:

•User preference (ask if not specified)
•Command complexity (XML better for complex, Markdown fine for simple)
•Existing project patterns (match what's already in use)

See references/prompt-examples.md for real examples of both formats in production.

<required_tags>

<objective> - What the command does and why it matters

markdown

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

<process> or <steps> - How to execute the command

markdown

<process>
Sequential steps to accomplish the objective:
1. First step
2. Second step
3. Final step
</process>

<success_criteria> - How to know the command succeeded

markdown

<success_criteria>
Clear, measurable criteria for successful completion.
</success_criteria>

</required_tags>

<conditional_tags>

<context> - When loading dynamic state or files

markdown

<context>
Current state: ! `git status`
Relevant files: @ package.json
</context>

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

<verification> - When producing artifacts that need checking

markdown

<verification>
Before completing, verify:
- Specific test or check to perform
- How to confirm it works
</verification>

<testing> - When running tests is part of the workflow

markdown

<testing>
Run tests: ! `npm test`
Check linting: ! `npm run lint`
</testing>

<output> - When creating/modifying specific files

markdown

<output>
Files created/modified:
- `./path/to/file.ext` - Description
</output>

</conditional_tags>

<structure_example>

markdown

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

<objective>
Process #$ARGUMENTS to accomplish [goal].

This helps [who] achieve [outcome].
</objective>

<context>
Current state: ! `relevant command`
Files: @ relevant/files
</context>

<process>
1. Parse #$ARGUMENTS
2. Execute operation
3. Verify results
</process>

<success_criteria>

- Operation completed without errors
- Output matches expected format
  </success_criteria>

</structure_example>

<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 <objective> or <process> tags
•Include argument-hint in frontmatter
•Make it clear what the arguments are for

Commands that produce files:

•Always include <output> tag specifying what gets created
•Always include <verification> tag with checks to perform

Commands that run tests/builds:

•Include <testing> tag with specific commands
•Include pass/fail criteria in <success_criteria> </intelligence_rules> </xml_structure>

<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_that_need_arguments>

<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. </commands_without_arguments>

<incorporating_arguments>

In <objective> tag:

markdown

<objective>
Fix issue #$ARGUMENTS following project conventions.

This ensures bugs are resolved systematically with proper testing.
</objective>

In <process> tag:

markdown

<process>
1. Understand issue #$ARGUMENTS from issue tracker
2. Locate relevant code
3. Implement fix
4. Add tests
</process>

In <context> tag:

markdown

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

(Note: Remove the space after the exclamation mark in actual usage) </incorporating_arguments>

<positional_arguments>

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

markdown

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

<objective>
Review PR #$1 with priority $2 and assign to $3.
</objective>

Usage: /review-pr 456 high alice </positional_arguments> </arguments_intelligence>

<file_structure>

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

•Shared with team via version control
•Project-specific workflows
•Shows (project) in /help list
•Committed to git for team use

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

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

File naming: command-name.md → invoked as /command-name

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 </file_structure>

<yaml_frontmatter>

<field name="description"> **Required** - Describes what the command does

yaml

description: Analyze this code for performance issues and suggest optimizations

Shown in the /help command list. </field>

<field name="allowed-tools"> **Optional** - Restricts which tools Antigravity can use

yaml

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

Formats:

•Array: allowed-tools: [Read, Edit, Write]
•Single tool: allowed-tools: SequentialThinking
•Bash restrictions: allowed-tools: Bash(git add:*)

If omitted: All tools available </field> </yaml_frontmatter>

Command file: .agent/commands/fix-issue.md

markdown

---
description: Fix issue following coding standards
---

Fix issue #$ARGUMENTS following our coding standards

Usage: /fix-issue 123 high-priority

Antigravity receives: "Fix issue #123 high-priority following our coding standards" </all_arguments_string>

<positional_arguments_syntax>

Command file: .agent/commands/review-pr.md

markdown

---
description: Review PR with priority and assignee
---

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

Usage: /review-pr 456 high alice

Antigravity receives: "Review PR #456 with priority high and assign to alice"

See references/arguments.md for advanced patterns. </positional_arguments_syntax> </arguments>

<dynamic_context>

Execute bash commands before the prompt using the exclamation mark prefix directly before backticks (no space between).

Note: Examples below show a space after the exclamation mark to prevent execution during skill loading. In actual slash commands, remove the space.

Example:

markdown

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

## Context

- Current git status: ! `git status`
- Current git diff: ! `git diff HEAD`
- Current branch: ! `git branch --show-current`
- Recent commits: ! `git log --oneline -10`

## Your task

Based on the above changes, create a single git commit.

The bash commands execute and their output is included in the expanded prompt. </dynamic_context>

<file_references>

Use @ prefix to reference specific files:

markdown

---
description: Review implementation
---

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

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

Antigravity can access the referenced file's contents. </file_references>

<best_practices>

1. Always use XML structure

yaml

# All slash commands should have XML-structured bodies

After frontmatter, use XML tags:

•<objective> - What and why (always)
•<process> - How to do it (always)
•<success_criteria> - Definition of done (always)
•Additional tags as needed (see xml_structure section)

2. Clear descriptions

yaml

# Good
description: Analyze this code for performance issues and suggest optimizations

# Bad
description: Optimize stuff

3. Use dynamic context for state-dependent tasks

markdown

Current git status: ! `git status`
Files changed: ! `git diff --name-only`

4. Restrict tools when appropriate

yaml

# For git commands - prevent running arbitrary bash
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)

# For analysis - thinking only
allowed-tools: SequentialThinking

5. Use #$ARGUMENTS for flexibility

markdown

Find and fix issue #$ARGUMENTS

6. Reference relevant files

markdown

Review @ package.json for dependencies
Analyze @ src/database/\* for schema

(Note: Remove the space after @ in actual usage) </best_practices>

<common_patterns>

Simple analysis command:

markdown

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

<objective>
Review code for security vulnerabilities and suggest fixes.
</objective>

<process>
1. Scan code for common vulnerabilities (XSS, SQL injection, etc.)
2. Identify specific issues with line numbers
3. Suggest remediation for each issue
</process>

<success_criteria>

- All major vulnerability types checked
- Specific issues identified with locations
- Actionable fixes provided
  </success_criteria>

Git workflow with context:

markdown

---
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.
</objective>

<context>
- Current status: ! `git status`
- Changes: ! `git diff HEAD`
- Recent commits: ! `git log --oneline -5`
</context>

<process>
1. Review staged and unstaged changes
2. Stage relevant files
3. Write commit message following recent commit style
4. Create commit
</process>

<success_criteria>

- All relevant changes staged
- Commit message follows repository conventions
- Commit created successfully
  </success_criteria>

Parameterized command:

markdown

---
description: Fix issue following coding standards
argument-hint: [issue-number]
---

<objective>
Fix issue #$ARGUMENTS following project coding standards.

This ensures bugs are resolved systematically with proper testing.
</objective>

<process>
1. Understand the issue described in ticket #$ARGUMENTS
2. Locate the relevant code in codebase
3. Implement a solution that addresses root cause
4. Add appropriate tests
5. Verify fix resolves the issue
</process>

<success_criteria>

- Issue fully understood and addressed
- Solution follows coding standards
- Tests added and passing
- No regressions introduced
  </success_criteria>

File-specific command:

markdown

---
description: Optimize code performance
argument-hint: [file-path]
---

<objective>
Analyze performance of @ #$ARGUMENTS and suggest specific optimizations.

This helps improve application performance through targeted improvements.
</objective>

<process>
1. Review code in @ #$ARGUMENTS for performance issues
2. Identify bottlenecks and inefficiencies
3. Suggest three specific optimizations with rationale
4. Estimate performance impact of each
</process>

<success_criteria>

- Performance issues clearly identified
- Three concrete optimizations suggested
- Implementation guidance provided
- Performance impact estimated
  </success_criteria>

Usage: /optimize src/utils/helpers.js

See references/patterns.md for more examples. </common_patterns>

<reference_guides>

Slash command specific references:

•arguments.md - #$ARGUMENTS, positional args, parsing strategies
•patterns.md - Git workflows, code analysis, file operations, subagent patterns
•tool-restrictions.md - Bash patterns, security best practices
•prompt-examples.md - Real-world command examples by pattern

Prompt engineering references from create-prompt skill:

•clarity-principles.md - Being clear and direct
•xml-structure.md - XML tag usage
•few-shot-patterns.md - Example-based prompting
•reasoning-techniques.md - Chain of thought, step-by-step
•system-prompt-patterns.md - System prompt templates
•anthropic-best-practices.md - Antigravity-specific techniques
•context-management.md - Context windows, long-horizon reasoning
•anti-patterns.md - Common mistakes to avoid </reference_guides>

<generation_protocol>

<step_0_mandatory_research> CRITICAL: Complete this research phase BEFORE proceeding to any other steps.

You MUST read and understand these materials before creating any slash command:

1. Read ALL reference files in order:

Use the Read tool to read these files:

•references/prompt-examples.md - Real-world patterns and examples
•references/patterns.md - Verified command patterns
•references/arguments.md - Argument handling examples
•references/tool-restrictions.md - Tool restriction patterns

2. Examine existing slash commands:

Use Bash to find and Read existing commands:

bash

find ~/.agent/commands -name "*.md" -type f | head -10

Then Read 2-3 relevant existing commands to understand:

•How they structure their YAML frontmatter
•What format they use (XML vs Markdown)
•How they handle arguments (#$ARGUMENTS vs positional)
•What tool restrictions they apply
•How they structure their workflow sections

3. Identify the right pattern:

Based on the user's request, match it to one of these patterns from prompt-examples.md:

•Pattern 1: Numbered workflow (git ops, CI, EPCT) - for multi-step processes
•Pattern 2: Reference/docs (CLI wrappers) - for command documentation
•Pattern 3: Section-based analysis (research, investigation) - for analysis tasks
•Subagent patterns: For commands that launch Task tool agents
•Hybrid patterns: Combining multiple approaches

4. Check for similar existing commands:

Before creating a new command, check if a similar command already exists:

bash

grep -l "description.*<similar-concept>" ~/.agent/commands/*.md

If a similar command exists, read it to:

•Avoid duplication
•Learn from its structure
•Understand how to differentiate the new command

VERIFICATION CHECKLIST:

Before proceeding to step 1, confirm you have:

•✅ Read all 4 reference files
•✅ Examined at least 2 existing slash commands
•✅ Identified which pattern to use
•✅ Checked for similar existing commands
•✅ Understand the correct syntax (#$ARGUMENTS, tool restrictions, etc.)

DO NOT PROCEED until all items are checked. This research phase is non-negotiable and prevents creating poorly structured commands.

</step_0_mandatory_research>

<step_1_analyze_request> Analyze the user's request to understand what they want:

•What is the command's purpose?
•Does it need user input (#$ARGUMENTS)?
•Does it produce files or artifacts?
•Does it require verification or testing?
•Is it simple (single-step) or complex (multi-step)?
•What pattern does it match? (see references/prompt-examples.md)

Intelligence rule: Only proceed to questions if critical information is missing. If the request is clear, skip directly to format choice. </step_1_analyze_request>

<step_2_ask_questions_if_needed> INTELLIGENCE RULE: Only ask questions if critical information is truly missing.

If the request is clear, skip directly to scope and format questions. Most requests like "create a command to X" contain enough information to proceed.

Ask clarifying questions ONLY if essential information is missing:

Use AskUserQuestion to gather ONLY what's needed:

•
Command purpose (if completely unclear):
- •header: "Purpose"
- •question: "What should this command do?"
- •Let user provide via "Other" option
•
Arguments (if truly ambiguous - rare):
- •header: "Arguments"
- •question: "Does this command need user input?"
- •options: "Yes - takes arguments", "No - uses context only"

SKIP questions for:

•Clear purposes: "create a command to commit and push" → obvious purpose
•Obvious complexity: "simple command to..." vs "command that monitors and fixes..."
•Clear arguments: "for [file-path]" → needs args, "to analyze current code" → no args
•Standard tools: Git commands → Bash(git :*), file operations → Read/Edit/Write

Default assumptions (use unless contradicted):

•Git operations → Bash(git :*)
•Analysis tasks → No tool restrictions
•File modifications → Read, Edit, Write
•Complex multi-step → Add verification and testing sections </step_2_ask_questions_if_needed>

<step_2b_ask_scope> ALWAYS ask about scope unless explicitly specified in the request:

Use AskUserQuestion:

•header: "Scope"
•question: "Where should this command be available?"
•
options:
- •"Global (all projects)" - description: "Saved to ~/.agent/commands/ - available everywhere"
- •"Project only" - description: "Saved to .agent/commands/ - shared with team via git"

Detection rules:

•If request says "global command" → Skip, use global scope
•If request says "project command" or "team command" → Skip, use project scope
•Otherwise → ALWAYS ask

Important: This determines the save location:

•Global: ~/.agent/commands/command-name.md
•Project: .agent/commands/command-name.md (in current working directory) </step_2b_ask_scope>

<step_3_choose_format> Determine format based on existing patterns:

Before asking the user, check what format existing commands in the target directory use:

•If creating global command: Check ~/.agent/commands/*.md
•If creating project command: Check .agent/commands/*.md

Read 2-3 existing commands to see if they use XML or Markdown format.

Then ask for format preference:

Use AskUserQuestion:

•header: "Format"
•question: "What format do you prefer for this slash command?"
•
options:
- •First option based on what you found: If most commands use Markdown, make "Markdown (matches existing)" the first option
- •Second option: The alternative format
- •Include note about what existing commands use

Recommendation:

•Match existing commands format for consistency
•XML for complex multi-step commands
•Markdown for simple straightforward commands

See references/prompt-examples.md for format examples. </step_3_choose_format>

<step_4_create_frontmatter> Create YAML frontmatter based on gathered information:

yaml

---
name: command-name
description: Clear description of what it does
argument-hint: [input] # Only if arguments needed
allowed-tools: [...] # Only if tool restrictions needed
---

Frontmatter rules:

•description: Always required, clear and concise
•argument-hint: Include if command takes user input
•allowed-tools: Include if restricting tools for security
•model: Include only if need specific model (haiku for speed, opus for complexity) </step_4_create_frontmatter>

<step_5_create_body> Create command body in chosen format (XML or Markdown):

<xml_body> Always include:

•<objective> - What and why
•<process> - How to do it (numbered steps)
•<success_criteria> - Definition of done

Include when relevant:

•<context> - Dynamic state (! commands) or file references (@ files)
•<verification> - Checks to perform if creating artifacts
•<testing> - Test commands if tests are part of workflow
•<output> - Files created/modified

Reference: Apply prompt engineering best practices from create-prompt skill:

•clarity-principles.md - Being clear and direct
•xml-structure.md - XML tag usage
•anthropic-best-practices.md - Antigravity-specific techniques </xml_body>

<markdown_body> Always include:

•## Objective - What and why
•## Process or ## Workflow - How to do it (numbered list)
•## Success Criteria - Definition of done

Include when relevant:

•## Context - Dynamic state or file references
•## Verification - Checks to perform if creating artifacts
•## Testing - Test commands if tests are part of workflow
•## Output - Files created/modified </markdown_body> </step_5_create_body>

<step_6_integrate_arguments> Integrate #$ARGUMENTS if command takes input:

•If user input needed: Add argument-hint and use #$ARGUMENTS in body
•If self-contained: Omit argument-hint and #$ARGUMENTS
•For structured input: Use positional args $1, $2, $3

Examples: See references/arguments.md </step_6_integrate_arguments>

<step_7_apply_intelligence> Apply appropriate complexity level:

•Simple commands: Keep concise (objective + process + success criteria)
•Complex commands: Add context, verification, testing as needed
•Don't over-engineer: Simple tasks stay simple
•Don't under-specify: Complex tasks get full structure

Pattern matching: Choose pattern from references/prompt-examples.md:

•Pattern 1: Numbered workflow (git ops, CI, EPCT)
•Pattern 2: Reference/docs (CLI wrappers)
•Pattern 3: Section-based analysis (research, investigation) </step_7_apply_intelligence>

<step_8_save_file> Save the command file based on chosen scope:

Global scope (user selected "Global (all projects)"):

•Path: ~/.agent/commands/command-name.md
•Available across all projects
•Personal commands, not shared with team

Project scope (user selected "Project only"):

•Path: .agent/commands/command-name.md (in current working directory)
•Shared with team via version control
•Project-specific commands

Verification:

•File created at correct location based on scope
•YAML frontmatter valid
•Body follows chosen format consistently
•All required sections present

After saving:

•Confirm location to user
•Remind them to commit if project scope
•Provide usage example: /command-name [args] </step_8_save_file>

</generation_protocol>

<success_criteria> A well-structured slash command meets these criteria:

YAML Frontmatter:

•description field is clear and concise
•argument-hint present if command accepts arguments
•allowed-tools specified if tool restrictions needed

XML Structure:

•All three required tags present: <objective>, <process>, <success_criteria>
•Conditional tags used appropriately based on complexity
•No raw markdown headings in body
•All XML tags properly closed

Arguments Handling:

•#$ARGUMENTS used when command operates on user-specified data
•Positional arguments ($1, $2, etc.) used when structured input needed
•No #$ARGUMENTS reference for self-contained commands

Functionality:

•Command expands correctly when invoked
•Dynamic context loads properly (bash commands, file references)
•Tool restrictions prevent unauthorized operations
•Command accomplishes intended purpose reliably

Quality:

•Clear, actionable instructions in <process> tag or ## Workflow section
•Measurable completion criteria in <success_criteria> tag or ## Success Criteria section
•Appropriate level of detail (not over-engineered for simple tasks)
•Examples provided when beneficial </success_criteria>

<common_mistakes>

Critical Anti-Patterns to Avoid

These are common mistakes that result from skipping the mandatory research phase:

❌ MISTAKE 1: Skipping the Research Phase

Wrong:

code

User asks to create /quick-search command
→ Immediately ask scope/format questions
→ Create command without reading references or existing commands
→ Use wrong syntax, wrong format, miss best practices

Correct:

code

User asks to create /quick-search command
→ Read all 4 reference files first
→ Find and examine existing commands (especially /search if it exists)
→ Understand patterns and syntax
→ Then ask questions and create command

❌ MISTAKE 2: Using Wrong Argument Syntax

Wrong:

markdown

---
description: Quick search
---
Answer the question: #args

Correct:

markdown

---
description: Quick search
argument-hint: <question>
---
User: #$ARGUMENTS

The correct syntax is #$ARGUMENTS (not #args). This is documented in references/arguments.md.

❌ MISTAKE 3: Not Checking for Similar Commands

Wrong:

•Create /quick-search without checking if /search already exists
•Result: Duplicate functionality, confusion

Correct:

•Check existing commands first: find ~/.agent/commands -name "*.md"
•If similar command exists, read it to understand how to differentiate
•Consider if the new command is really needed

❌ MISTAKE 4: Wrong Format Choice

Wrong:

•User asks for command
•Randomly choose XML or Markdown without checking existing commands
•Result: Inconsistent codebase

Correct:

•Check what format existing commands use
•Match that format for consistency
•Only deviate if user explicitly requests different format

❌ MISTAKE 5: Missing Tool Restrictions

Wrong:

yaml

---
description: Quick search with Haiku model
model: haiku
---

Correct:

yaml

---
description: Quick search with Haiku model
model: haiku
allowed-tools: [Grep, Glob, Read]
---

For speed-optimized commands, restrict tools to prevent using slow agents like Task.

❌ MISTAKE 6: Not Matching Existing Patterns

Wrong:

•Create unique structure that doesn't match any existing pattern
•Result: Hard to maintain, unfamiliar to users

Correct:

•Read prompt-examples.md to see verified patterns
•Match your command to Pattern 1, 2, 3, or hybrid
•Follow the established structure

❌ MISTAKE 7: Not Including "User: #$ARGUMENTS" at the End

Wrong:

markdown

---
description: Search command
argument-hint: <question>
---

You are a search specialist.

## Workflow
1. Search for the answer
2. Provide results

Correct:

markdown

---
description: Search command
argument-hint: <question>
---

You are a search specialist.

## Workflow
1. Search for the answer
2. Provide results

---

User: #$ARGUMENTS

Many commands end with User: #$ARGUMENTS to properly pass the user's input to the command.

❌ MISTAKE 8: Over-Engineering Simple Commands

Wrong:

markdown

<objective>Create comprehensive search system</objective>
<context>Load all git state</context>
<verification>Run extensive checks</verification>
<testing>Test all edge cases</testing>

For a simple search command, this is too much.

Correct:

markdown

You are a rapid search specialist.

## Workflow
1. Search
2. Answer

User: #$ARGUMENTS

Match complexity to the task.

How to Avoid These Mistakes

Follow the Step 0 checklist religiously:

•✅ Read all 4 reference files
•✅ Examine 2-3 existing commands
•✅ Identify the pattern to use
•✅ Check for similar commands
•✅ Understand correct syntax

If you skip Step 0, you WILL make these mistakes.

</common_mistakes>