> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/QwenLM/qwen-code/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Extensions

> Create custom slash commands that package complex prompts and workflows

# Creating Command Extensions

Custom commands are reusable prompt shortcuts that users can invoke with slash syntax (e.g., `/deploy`, `/test`). Extensions can package and distribute commands to share workflows and best practices.

## What are Custom Commands?

Custom commands:

* Are Markdown files with optional YAML frontmatter
* Support template variables for dynamic content
* Can execute shell commands and include output
* Use slash syntax for invocation: `/command-name`
* Support nested organization with `:`

## Command File Format

Commands are Markdown files:

```markdown theme={null}
---
description: Brief description shown in help
---

Your prompt template goes here.

You can use {{args}} for user input.

You can run commands: !{ls -la}
```

### Frontmatter (Optional)

```yaml theme={null}
---
description: What this command does
---
```

Currently, only `description` is supported.

### Template Variables

Use `{{args}}` to insert user-provided arguments:

```markdown theme={null}
Please analyze the following pattern: `{{args}}`
```

Invoked as: `/search "TODO"`

### Shell Command Execution

Execute shell commands and include their output:

```markdown theme={null}
Here are the search results:

!{grep -r "{{args}}" . --include="*.ts"}

Please summarize these findings.
```

**Important:** The shell command output is included in the prompt, not executed by the AI. Use this to gather information before sending to the AI.

## Extension Structure

Place command files in a `commands/` directory:

```
my-extension/
├── qwen-extension.json
└── commands/
    ├── deploy.md
    ├── test.md
    └── fs/
        ├── grep-code.md
        └── summarize.md
```

### Configure in Manifest

Update `qwen-extension.json`:

```json theme={null}
{
  "name": "my-extension",
  "version": "1.0.0",
  "commands": "commands"
}
```

The `commands` field specifies the directory (defaults to `"commands"` if not specified).

## Command Naming

Command names are derived from file paths:

### Top-Level Commands

```
commands/deploy.md → /deploy
commands/test.md → /test
```

### Nested Commands

```
commands/fs/grep-code.md → /fs:grep-code
commands/utils/format.md → /utils:format
commands/git/log/pretty.md → /git:log:pretty
```

### Conflict Resolution

If a command name conflicts with user or project commands:

```
commands/deploy.md → /my-extension.deploy
```

Extension commands have the lowest precedence. The extension name is automatically prefixed when conflicts occur.

## Example: Search and Summarize

From the built-in examples:

**File:** `commands/fs/grep-code.md`

```markdown theme={null}
---
description: Search for a pattern in code and summarize findings
---

Please summarize the findings for the pattern `{{args}}`.

Search Results:
!{grep -r "{{args}}" . --include="*.ts" --include="*.js" --include="*.py"}
```

**Usage:**

```
/fs:grep-code "TODO"
/fs:grep-code "FIXME"
/fs:grep-code "console.log"
```

## Example: File Summarizer

**File:** `commands/summarize.md`

```markdown theme={null}
---
description: Provide a concise summary of a file's contents and purpose
---

Please analyze and summarize the following file:

**File:** {{args}}

!{cat "{{args}}"}

Provide:
1. Purpose of the file
2. Key functionality
3. Important dependencies
4. Any issues or concerns
```

**Usage:**

```
/summarize src/index.ts
/summarize package.json
```

## Example: Code Review

**File:** `commands/review.md`

```markdown theme={null}
---
description: Perform a thorough code review of specified files
---

Perform a comprehensive code review of the following:

!{cat {{args}}}

Focus on:
- Code quality and readability
- Potential bugs or edge cases
- Performance considerations
- Security issues
- Best practices compliance

Provide specific suggestions with code examples.
```

**Usage:**

```
/review src/auth.ts
/review "src/**/*.test.ts"
```

## Example: Git Analysis

**File:** `commands/git/recent-changes.md`

```markdown theme={null}
---
description: Analyze recent git changes and provide summary
---

Recent Git Commits:

!{git log --oneline -10}

Detailed Changes:

!{git diff HEAD~5..HEAD --stat}

Please analyze these recent changes and:
1. Summarize what was changed
2. Identify any patterns
3. Suggest related areas that might need attention
4. Check for potential issues
```

**Usage:**

```
/git:recent-changes
```

## Example: Test Generator

**File:** `commands/generate-tests.md`

```markdown theme={null}
---
description: Generate comprehensive unit tests for a file
---

Generate comprehensive unit tests for the following code:

**File:** {{args}}

!{cat "{{args}}"}

Requirements:
- Test all exported functions
- Cover edge cases and error conditions
- Use appropriate testing framework conventions
- Include setup and teardown as needed
- Add descriptive test names

Create the test file with the same name in a `__tests__` directory.
```

**Usage:**

```
/generate-tests src/utils/validation.ts
```

## Example: Dependency Analyzer

**File:** `commands/analyze-deps.md`

```markdown theme={null}
---
description: Analyze project dependencies and suggest updates
---

Package Information:

!{cat package.json}

Outdated Packages:

!{npm outdated || true}

Please analyze:
1. Which dependencies are outdated
2. Which updates are safe (patch/minor)
3. Which need careful review (major)
4. Any security concerns
5. Unused dependencies that could be removed
```

**Usage:**

```
/analyze-deps
```

## Advanced Patterns

### Multiple Shell Commands

```markdown theme={null}
Project Structure:

!{find . -type f -name "*.ts" | head -20}

Recent Activity:

!{git log --oneline -5}

Please provide project overview.
```

### Conditional Logic

```markdown theme={null}
Search for pattern: {{args}}

TypeScript files:
!{grep -r "{{args}}" . --include="*.ts" || echo "No matches in TypeScript"}

JavaScript files:
!{grep -r "{{args}}" . --include="*.js" || echo "No matches in JavaScript"}

Analyze and compare the usage patterns.
```

### Complex Workflows

```markdown theme={null}
---
description: Complete feature implementation workflow
---

Implement feature: {{args}}

## Current Structure

!{ls -R src/}

## Recent Patterns

!{git log --all --grep="feat" --oneline | head -5}

## Similar Files

!{find . -name "*{{args}}*" -type f}

Please:
1. Analyze existing patterns
2. Suggest file structure
3. Provide implementation plan
4. Generate initial code
5. Create corresponding tests
```

## Best Practices

### 1. Clear Descriptions

```markdown theme={null}
---
description: Search codebase for TODO comments and prioritize them
---
```

Be specific about what the command does.

### 2. Validate Input

Check for required arguments:

```markdown theme={null}
{{#if args}}
  Processing: {{args}}
  !{cat "{{args}}"}
{{else}}
  Error: Please provide a file path
{{/if}}
```

### 3. Error Handling

Handle command failures gracefully:

```markdown theme={null}
!{cat "{{args}}" 2>/dev/null || echo "File not found: {{args}}"}
```

### 4. Helpful Output

Structure prompts for useful AI responses:

```markdown theme={null}
Provide analysis in this format:

1. **Summary**: Brief overview
2. **Findings**: Specific issues found
3. **Recommendations**: Actionable improvements
4. **Examples**: Code snippets
```

### 5. Scope Appropriately

Limit shell command output:

```markdown theme={null}
!{git log --oneline -20}    # Last 20 commits
!{ls -la | head -50}         # First 50 files
!{grep -r "pattern" . | head -100}  # First 100 matches
```

Large outputs can exceed context limits.

## Command Organization

### Group by Domain

```
commands/
├── git/
│   ├── status.md
│   ├── commits.md
│   └── diff.md
├── test/
│   ├── run.md
│   ├── coverage.md
│   └── generate.md
└── docs/
    ├── generate.md
    └── update.md
```

### Naming Conventions

* Use kebab-case: `analyze-deps.md`
* Be descriptive: `generate-unit-tests.md` not `gen.md`
* Use verbs: `review-code.md`, `search-todos.md`

## Migration from TOML

Older extensions used TOML format:

```toml theme={null}
description = "Command description"

[[prompts]]
role = "user"
content = "Prompt content"
```

TOML files are still supported but deprecated. Qwen Code will prompt you to migrate when detected.

**Markdown is now the standard format** and is much simpler to work with.

## Command Discovery

Users can discover commands through:

```bash theme={null}
/help            # List all commands
/help search     # Search for commands
```

Extension commands are marked with `[extension-name]` in help output.

## Testing Commands

During development:

1. Link your extension: `qwen extensions link .`
2. Restart Qwen Code
3. Try your commands
4. Edit command files
5. Restart to see changes (or use runtime hot-reload for some changes)

## Next Steps

* [Creating Extensions](/extensions/creating-extensions) - Build a complete extension
* [Skills](/extensions/skills) - Create AI-invoked capabilities
* [Agents](/extensions/agents) - Build specialized assistants
* [Best Practices](/extensions/best-practices) - Extension development guidelines