Skip to main content

​
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: 
---
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)

---
description: What this command does
---
Currently, only description is supported.

​
Template Variables

Use {{args}} to insert user-provided arguments: 
Please analyze the following pattern: `{{args}}`
Invoked as: /search "TODO"

​
Shell Command Execution

Execute shell commands and include their output: 
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: 
{
  "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 
---
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 
---
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 
---
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 
---
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 
---
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 
---
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

Project Structure:

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

Recent Activity:

!{git log --oneline -5}

Please provide project overview.

​
Conditional Logic

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

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

---
description: Search codebase for TODO comments and prioritize them
---
Be specific about what the command does.

​
2. Validate Input

Check for required arguments: 
{{#if args}}
  Processing: {{args}}
  !{cat "{{args}}"}
{{else}}
  Error: Please provide a file path
{{/if}}

​
3. Error Handling

Handle command failures gracefully: 
!{cat "{{args}}" 2>/dev/null || echo "File not found: {{args}}"}

​
4. Helpful Output

Structure prompts for useful AI responses: 
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: 
!{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: 
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: 
/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