Skip to content
Merged
Show file tree
Hide file tree
Changes from 31 commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
22504b0
feat: add extension for gemini and claude
LaZzyMan Jan 7, 2026
50dac93
feat: migrate command format
LaZzyMan Jan 7, 2026
18713ef
feat: install from gemini
LaZzyMan Jan 7, 2026
74013bd
feat: settings extension
LaZzyMan Jan 8, 2026
551e546
feat: move extension to core package
LaZzyMan Jan 14, 2026
70991e4
fix/lint error
LaZzyMan Jan 14, 2026
0a88dd7
fix: fix tests
LaZzyMan Jan 14, 2026
b37ede0
fix/gemini extension install error
LaZzyMan Jan 14, 2026
4c7605d
Merge branch 'main' into feat/extension
LaZzyMan Jan 14, 2026
f00f764
feat: claude subagents transform
LaZzyMan Jan 15, 2026
f7fb624
feat: extension slash commands
LaZzyMan Jan 16, 2026
f10fcc8
fix: hot refresh agents
LaZzyMan Jan 16, 2026
592bf2b
fix: auto update error
LaZzyMan Jan 16, 2026
c8b0efa
feat: add i18n
LaZzyMan Jan 19, 2026
df33029
Merge branch 'main' into feat/extension
LaZzyMan Jan 19, 2026
706cdb2
fix: merge skillManager change
LaZzyMan Jan 19, 2026
a546e84
fix: settings in arg
LaZzyMan Jan 19, 2026
6e641b8
feat: add docs
LaZzyMan Jan 19, 2026
f8e41fb
fix i18n
LaZzyMan Jan 19, 2026
8b4626a
fix test
LaZzyMan Jan 19, 2026
a61a3c5
Merge branch 'main' into feat/extension
LaZzyMan Jan 19, 2026
143beb5
fix code merge
LaZzyMan Jan 19, 2026
b0c3e5d
fix ci test
LaZzyMan Jan 20, 2026
2e80f7f
fix config test
LaZzyMan Jan 20, 2026
452bbc1
fix test online
LaZzyMan Jan 20, 2026
2c22961
fix test on windows
LaZzyMan Jan 20, 2026
ba14e9e
add settings command and update extension examples
LaZzyMan Jan 20, 2026
e87376e
i18n add extension commands
LaZzyMan Jan 20, 2026
f467054
feat: remove excludeTools in extension
LaZzyMan Jan 20, 2026
140e8c9
Merge branch 'main' into feat/extension
LaZzyMan Jan 21, 2026
1e41965
fix settings in interactive mode
LaZzyMan Jan 21, 2026
3f3c5ff
feat add explore command
LaZzyMan Jan 21, 2026
5f3f81b
docs move extension to user and hide create docs
LaZzyMan Jan 21, 2026
bc7e586
Merge branch 'main' into feat/extension
LaZzyMan Jan 22, 2026
9af348d
fix ci test
LaZzyMan Jan 22, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 70 additions & 10 deletions docs/developers/extensions/extension.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,25 @@ Qwen Code extensions package prompts, MCP servers, and custom commands into a fa

## Extension management

We offer a suite of extension management tools using `qwen extensions` commands.
We offer a suite of extension management tools using both `qwen extensions` CLI commands and `/extensions` slash commands within the interactive CLI.

Note that these commands are not supported from within the CLI, although you can list installed extensions using the `/extensions list` subcommand.
### Runtime Extension Management (Slash Commands)

Note that all of these commands will only be reflected in active CLI sessions on restart.
You can manage extensions at runtime within the interactive CLI using `/extensions` slash commands. These commands support hot-reloading, meaning changes take effect immediately without restarting the application.

| Command | Description |
| ------------------------------------------------------ | --------------------------------------------------------------- |
| `/extensions` or `/extensions list` | List all installed extensions with their status |
| `/extensions install <source>` | Install an extension from a git URL, local path, or marketplace |
| `/extensions uninstall <name>` | Uninstall an extension |
| `/extensions enable <name> --scope <user\|workspace>` | Enable an extension |
| `/extensions disable <name> --scope <user\|workspace>` | Disable an extension |
| `/extensions update <name>` | Update a specific extension |
| `/extensions update --all` | Update all extensions with available updates |

### CLI Extension Management

You can also manage extensions using `qwen extensions` CLI commands. Note that changes made via CLI commands will be reflected in active CLI sessions on restart.

### Installing an extension

Expand Down Expand Up @@ -98,7 +112,17 @@ The `qwen-extension.json` file contains the configuration for the extension. The
}
},
"contextFileName": "QWEN.md",
"excludeTools": ["run_shell_command"]
"commands": "commands",
"skills": "skills",
"agents": "agents",
"settings": [
{
"name": "API Key",
"description": "Your API key for the service",
"envVar": "MY_API_KEY",
"sensitive": true
}
]
}
```

Expand All @@ -107,13 +131,18 @@ The `qwen-extension.json` file contains the configuration for the extension. The
- `mcpServers`: A map of MCP servers to configure. The key is the name of the server, and the value is the server configuration. These servers will be loaded on startup just like MCP servers configured in a [`settings.json` file](./cli/configuration.md). If both an extension and a `settings.json` file configure an MCP server with the same name, the server defined in the `settings.json` file takes precedence.
- Note that all MCP server configuration options are supported except for `trust`.
- `contextFileName`: The name of the file that contains the context for the extension. This will be used to load the context from the extension directory. If this property is not used but a `QWEN.md` file is present in your extension directory, then that file will be loaded.
- `excludeTools`: An array of tool names to exclude from the model. You can also specify command-specific restrictions for tools that support it, like the `run_shell_command` tool. For example, `"excludeTools": ["run_shell_command(rm -rf)"]` will block the `rm -rf` command. Note that this differs from the MCP server `excludeTools` functionality, which can be listed in the MCP server config. **Important:** Tools specified in `excludeTools` will be disabled for the entire conversation context and will affect all subsequent queries in the current session.
- `commands`: The directory containing custom commands (default: `commands`). Commands are `.md` files that define prompts.
- `skills`: The directory containing custom skills (default: `skills`). Skills are discovered automatically and become available via the `/skills` command.
- `agents`: The directory containing custom subagents (default: `agents`). Subagents are `.yaml` or `.md` files that define specialized AI assistants.
- `settings`: An array of settings that the extension requires. When installing, users will be prompted to provide values for these settings. The values are stored securely and passed to MCP servers as environment variables.

When Qwen Code starts, it loads all the extensions and merges their configurations. If there are any conflicts, the workspace configuration takes precedence.

### Custom commands

Extensions can provide [custom commands](./cli/commands.md#custom-commands) by placing TOML files in a `commands/` subdirectory within the extension directory. These commands follow the same format as user and project custom commands and use standard naming conventions.
Extensions can provide [custom commands](./cli/commands.md#custom-commands) by placing Markdown files in a `commands/` subdirectory within the extension directory. These commands follow the same format as user and project custom commands and use standard naming conventions.

> **Note:** The command format has been updated from TOML to Markdown. TOML files are deprecated but still supported. You can migrate existing TOML commands using the automatic migration prompt that appears when TOML files are detected.

**Example**

Expand All @@ -123,15 +152,46 @@ An extension named `gcp` with the following structure:
.qwen/extensions/gcp/
├── qwen-extension.json
└── commands/
├── deploy.toml
├── deploy.md
└── gcs/
└── sync.toml
└── sync.md
```

Would provide these commands:

- `/deploy` - Shows as `[gcp] Custom command from deploy.toml` in help
- `/gcs:sync` - Shows as `[gcp] Custom command from sync.toml` in help
- `/deploy` - Shows as `[gcp] Custom command from deploy.md` in help
- `/gcs:sync` - Shows as `[gcp] Custom command from sync.md` in help

### Custom skills

Extensions can provide custom skills by placing skill files in a `skills/` subdirectory within the extension directory. Each skill should have a `SKILL.md` file with YAML frontmatter defining the skill's name and description.

**Example**

```
.qwen/extensions/my-extension/
├── qwen-extension.json
└── skills/
└── pdf-processor/
└── SKILL.md
```

The skill will be available via the `/skills` command when the extension is active.

### Custom subagents

Extensions can provide custom subagents by placing agent configuration files in an `agents/` subdirectory within the extension directory. Agents are defined using YAML or Markdown files.

**Example**

```
.qwen/extensions/my-extension/
├── qwen-extension.json
└── agents/
└── testing-expert.yaml
```

Extension subagents appear in the subagent manager dialog under "Extension Agents" section.

### Conflict resolution

Expand Down
110 changes: 104 additions & 6 deletions docs/developers/extensions/getting-started-extensions.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,22 +148,119 @@ Custom commands provide a way to create shortcuts for complex prompts. Let's add
mkdir -p commands/fs
```

2. Create a file named `commands/fs/grep-code.toml`:
2. Create a file named `commands/fs/grep-code.md`:

```markdown
---
description: Search for a pattern in code and summarize findings
---

```toml
prompt = """
Please summarize the findings for the pattern `{{args}}`.

Search Results:
!{grep -r {{args}} .}
"""
```

This command, `/fs:grep-code`, will take an argument, run the `grep` shell command with it, and pipe the results into a prompt for summarization.

> **Note:** Commands use Markdown format with optional YAML frontmatter. TOML format is deprecated but still supported for backwards compatibility.

After saving the file, restart the Qwen Code. You can now run `/fs:grep-code "some pattern"` to use your new command.

## Step 5: Add a Custom `QWEN.md`
## Step 5: Add Custom Skills and Subagents (Optional)

Extensions can also provide custom skills and subagents to extend Qwen Code's capabilities.

### Adding a Custom Skill

Skills are model-invoked capabilities that the AI can automatically use when relevant.

1. Create a `skills` directory with a skill subdirectory:

```bash
mkdir -p skills/code-analyzer
```

2. Create a `skills/code-analyzer/SKILL.md` file:

```markdown
---
name: code-analyzer
description: Analyzes code structure and provides insights about complexity, dependencies, and potential improvements
---

# Code Analyzer

## Instructions

When analyzing code, focus on:

- Code complexity and maintainability
- Dependencies and coupling
- Potential performance issues
- Suggestions for improvements

## Examples

- "Analyze the complexity of this function"
- "What are the dependencies of this module?"
```

### Adding a Custom Subagent

Subagents are specialized AI assistants for specific tasks.

1. Create an `agents` directory:

```bash
mkdir -p agents
```

2. Create an `agents/refactoring-expert.md` file:

```markdown
---
name: refactoring-expert
description: Specialized in code refactoring, improving code structure and maintainability
tools:
- read_file
- write_file
- read_many_files
---

You are a refactoring specialist focused on improving code quality.

Your expertise includes:

- Identifying code smells and anti-patterns
- Applying SOLID principles
- Improving code readability and maintainability
- Safe refactoring with minimal risk

For each refactoring task:

1. Analyze the current code structure
2. Identify areas for improvement
3. Propose refactoring steps
4. Implement changes incrementally
5. Verify functionality is preserved
```

3. Update your `qwen-extension.json` to include the new directories:

```json
{
"name": "my-first-extension",
"version": "1.0.0",
"skills": "skills",
"agents": "agents",
"mcpServers": { ... }
}
```

After restarting Qwen Code, your custom skills will be available via `/skills` and subagents via `/agents manage`.

## Step 6: Add a Custom `QWEN.md`

You can provide persistent context to the model by adding a `QWEN.md` file to your extension. This is useful for giving the model instructions on how to behave or information about your extension's tools. Note that you may not always need this for extensions built to expose commands and prompts.

Expand Down Expand Up @@ -194,7 +291,7 @@ You can provide persistent context to the model by adding a `QWEN.md` file to yo

Restart the CLI again. The model will now have the context from your `QWEN.md` file in every session where the extension is active.

## Step 6: Releasing Your Extension
## Step 7: Releasing Your Extension

Once you are happy with your extension, you can share it with others. The two primary ways of releasing extensions are via a Git repository or through GitHub Releases. Using a public Git repository is the simplest method.

Expand All @@ -207,6 +304,7 @@ You've successfully created a Qwen Code extension! You learned how to:
- Bootstrap a new extension from a template.
- Add custom tools with an MCP server.
- Create convenient custom commands.
- Add custom skills and subagents.
- Provide persistent context to the model.
- Link your extension for local development.

Expand Down
94 changes: 61 additions & 33 deletions docs/users/features/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,8 @@ Environment Variables: Commands executed via `!` will set the `QWEN_CODE=1` envi

Save frequently used prompts as shortcut commands to improve work efficiency and ensure consistency.

> **Note:** Custom commands now use Markdown format with optional YAML frontmatter. TOML format is deprecated but still supported for backwards compatibility. When TOML files are detected, an automatic migration prompt will be displayed.

### Quick Overview

| Function | Description | Advantages | Priority | Applicable Scenarios |
Expand All @@ -135,14 +137,34 @@ Priority Rules: Project commands > User commands (project command used when name

#### File Path to Command Name Mapping Table

| File Location | Generated Command | Example Call |
| ---------------------------- | ----------------- | --------------------- |
| `~/.qwen/commands/test.toml` | `/test` | `/test Parameter` |
| `<project>/git/commit.toml` | `/git:commit` | `/git:commit Message` |
| File Location | Generated Command | Example Call |
| -------------------------- | ----------------- | --------------------- |
| `~/.qwen/commands/test.md` | `/test` | `/test Parameter` |
| `<project>/git/commit.md` | `/git:commit` | `/git:commit Message` |

Naming Rules: Path separator (`/` or `\`) converted to colon (`:`)

### TOML File Format Specification
### Markdown File Format Specification (Recommended)

Custom commands use Markdown files with optional YAML frontmatter:

```markdown
---
description: Optional description (displayed in /help)
---

Your prompt content here.
Use {{args}} for parameter injection.
```

| Field | Required | Description | Example |
| ------------- | -------- | ---------------------------------------- | ------------------------------------------ |
| `description` | Optional | Command description (displayed in /help) | `description: Code analysis tool` |
| Prompt body | Required | Prompt content sent to model | Any Markdown content after the frontmatter |

### TOML File Format (Deprecated)

> **Deprecated:** TOML format is still supported but will be removed in a future version. Please migrate to Markdown format.

| Field | Required | Description | Example |
| ------------- | -------- | ---------------------------------------- | ------------------------------------------ |
Expand Down Expand Up @@ -191,15 +213,19 @@ Naming Rules: Path separator (`/` or `\`) converted to colon (`:`)

Example: Git Commit Message Generation

```
# git/commit.toml
description = "Generate Commit message based on staged changes"
prompt = """
````markdown
---
description: Generate Commit message based on staged changes
---

Please generate a Commit message based on the following diff:
diff

```diff
!{git diff --staged}
"""
```
````

````

#### 4. File Content Injection (`@{...}`)

Expand All @@ -212,36 +238,38 @@ diff

Example: Code Review Command

```
# review.toml
description = "Code review based on best practices"
prompt = """
```markdown
---
description: Code review based on best practices
---

Review {{args}}, reference standards:

@{docs/code-standards.md}
"""
```
````

### Practical Creation Example

#### "Pure Function Refactoring" Command Creation Steps Table

| Operation | Command/Code |
| ----------------------------- | ------------------------------------------- |
| 1. Create directory structure | `mkdir -p ~/.qwen/commands/refactor` |
| 2. Create command file | `touch ~/.qwen/commands/refactor/pure.toml` |
| 3. Edit command content | Refer to the complete code below. |
| 4. Test command | `@file.js` → `/refactor:pure` |

```# ~/.qwen/commands/refactor/pure.toml
description = "Refactor code to pure function"
prompt = """
Please analyze code in current context, refactor to pure function.
Requirements:
1. Provide refactored code
2. Explain key changes and pure function characteristic implementation
3. Maintain function unchanged
"""
| Operation | Command/Code |
| ----------------------------- | ----------------------------------------- |
| 1. Create directory structure | `mkdir -p ~/.qwen/commands/refactor` |
| 2. Create command file | `touch ~/.qwen/commands/refactor/pure.md` |
| 3. Edit command content | Refer to the complete code below. |
| 4. Test command | `@file.js` → `/refactor:pure` |

```markdown
---
description: Refactor code to pure function
---

Please analyze code in current context, refactor to pure function.
Requirements:

1. Provide refactored code
2. Explain key changes and pure function characteristic implementation
3. Maintain function unchanged
```

### Custom Command Best Practices Summary
Expand Down
Loading