DEV Community

Ahab
Ahab

Posted on • Originally published at indieseek.co

Qwen Code 0.21.11: Install Agent Plugins v1 Without Assuming Full Compatibility

#ai #qwen #mcp #devtools

Qwen Code 0.21.11: install Agent Plugins v1 without assuming every capability works

Quick answer

Qwen Code 0.21.11 can install and link a standard Agent Plugins v1 package without converting its plugin.json, mcp.json, or SKILL.md files into qwen-extension.json.

That does not mean every component in an Agent Plugin runs in Qwen Code. The stable runtime loads direct-child Agent Skills plus stdio and Streamable HTTP MCP servers. It ignores commands, agents, hooks, context, settings, channels, apps, client namespaces, and legacy HTTP+SSE MCP entries.

Treat 0.21.11 as a portable-core release. Before enabling a third-party plugin broadly, prove the package is unchanged, inventory which capabilities actually load, test path and credential boundaries, verify persistent state, and keep a project-scoped rollback.

Who this is for

This guide is for extension authors and teams that want one portable plugin package to work in Qwen Code and other Agent Plugins clients. It is also for operators searching for “Qwen Code plugin not supported” after a package installs but a command, hook, agent, or MCP server is missing.

If you are migrating the same portable package into Codex, compare the Codex Agent Plugins rollout guide. The shared format reduces packaging work; each client still decides which capabilities it executes.

What changed in 0.21.11

The August 13 stable release adds native Agent Plugins v1 support. Qwen Code recognizes the canonical v1 schema, preserves the original package files, and uses the existing qwen extensions lifecycle for local directories, links, archives, Git repositories, archive URLs, and scoped npm packages.

The implementation deliberately matches a portable capability boundary rather than translating every client-specific feature. A root plugin.json for Agent Plugins takes precedence over other extension manifests. Unsupported schema versions fail explicitly; a missing or blank package version is represented internally as 1.0.0.

Agent Plugins v1 is a package format, not a marketplace integration. Native loading makes a package installable; it does not make every marketplace, command system, permission model, or client namespace portable.

Start with the real compatibility matrix

Package component Qwen Code 0.21.11 behavior Acceptance evidence
skills//SKILL.md as a direct child Loaded when valid Skill appears and can be invoked
Nested or malformed Skill Skipped independently Valid sibling still works
stdio MCP Supported Server connects with expected arguments and cwd
Streamable HTTP MCP Supported with URL and credential controls HTTPS or loopback HTTP connects safely
Legacy HTTP+SSE MCP Skipped Entry is absent; no silent transport substitution
Commands, agents, hooks Ignored None appears or executes
Context, settings, channels, apps, client namespaces Ignored No client-specific behavior is assumed
allowed-tools in a Skill Parsed as metadata, not pre-approval Tool still follows Qwen permission policy

This matrix is the contract. Do not label an ignored capability a failed installation, and do not label a successful installation full compatibility.

A seven-gate rollout workflow

1. Pin the client and package identity

Record qwen --version and require 0.21.11 or later. Pin the plugin source revision, archive checksum, or exact npm version. Review the root manifest before running any bundled server:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-agent-plugin",
  "version": "1.0.0"
}
Enter fullscreen mode Exit fullscreen mode

Reject an unexpected schema, a changed source, or an identity collision. Installation consent is not a substitute for package provenance.

2. Start at project scope

Use a disposable repository and the narrowest existing scope:

qwen extensions install ./my-agent-plugin --scope project
qwen extensions list
qwen mcp list
Enter fullscreen mode Exit fullscreen mode

For active development, qwen extensions link ./my-agent-plugin avoids copying the package. For a release canary, install the exact artifact users will receive. Do not begin with a global enablement.

3. Prove native loading did not rewrite the package

Hash the source files before installation. Confirm the installed or linked package retains plugin.json, mcp.json, SKILL.md, and server files byte-for-byte and does not gain a generated qwen-extension.json.

Also verify Qwen reports the origin as AgentPlugins. A converted Claude, Gemini, Qoder, or native Qwen extension follows a different compatibility path even if the visible feature looks similar.

4. Test supported and unsupported siblings together

Build a harmless fixture containing one valid direct-child Skill, one invalid or nested Skill, one stdio MCP server, and one unsupported command or hook. The pass condition is asymmetric:

  • the valid Skill and stdio server load;
  • the invalid Skill is isolated rather than disabling the valid sibling;
  • the command or hook remains unavailable;
  • allowed-tools does not silently bypass Qwen approval.

This catches the most dangerous rollout mistake: assuming an install success means every directory became executable.

5. Verify state and path containment

For stdio MCP, Qwen expands ${PLUGIN_ROOT} and ${PLUGIN_DATA} once in arguments, environment values, and cwd. Write a harmless sentinel into PLUGIN_DATA, update or reinstall the same plugin identity, and confirm the sentinel remains. Keep mutable state out of the read-only package root.

Then include a symlink or relative-path escape fixture. A manifest escape should reject the plugin; a component escape should disable only that component. No discovered, read, or executed path should leave the resolved plugin root.

6. Run the HTTP credential canaries

Remote MCP endpoints must use HTTPS; plain HTTP is allowed only for loopback. Test a local Streamable HTTP fixture first, then a controlled HTTPS endpoint. Require these outcomes:

  • unsafe remote HTTP is rejected;
  • client-owned headers cannot be overridden;
  • a configured credential or authorization header is not forwarded across a redirect;
  • one malformed MCP entry does not disable valid siblings.

Use synthetic tokens and local endpoints. A security canary should prove policy without risking a real secret.

7. Promote only the portable slice

Enable the plugin for one project, run representative Skill and MCP tasks, disable and re-enable it, then test update and uninstall. Promote to user scope only when the evidence matches the matrix.

If your product depends on commands, agents, hooks, context, channels, apps, or a marketplace, keep the client-specific package or adapter. The portable core and the Qwen-specific layer can coexist; pretending they are identical creates silent feature loss.

Common mistakes

  • Assuming the Agent Plugins logo means all clients execute the same components.
  • Converting the package manually even though 0.21.11 preserves the v1 files.
  • Testing only a happy-path Skill and never proving unsupported components stay inert.
  • Treating allowed-tools as a Qwen permission grant.
  • Putting mutable state under PLUGIN_ROOT instead of PLUGIN_DATA.
  • Allowing credentials to follow redirects during an MCP connectivity test.
  • Enabling globally before a project-scoped rollback passes.
  • Calling a marketplace listing part of the Agent Plugins v1 runtime contract.

For a broader permission-precedence test, use the Qwen Code workspace trust checklist. For MCP calls that may repeat after reconnects, pair this rollout with the Qwen MCP safe-replay checklist.

Copyable evidence record 

date / owner / decision:
qwen_version / launcher:
plugin_name / version / source_revision_or_checksum:
install_scope: project | user
manifest_schema / origin:
source_hashes_match / generated_qwen_manifest_absent:
valid_skill / invalid_sibling_isolated:
stdio_mcp / streamable_http_mcp / legacy_sse_absent:
unsupported_commands_agents_hooks_absent:
allowed_tools_still_requires_policy:
plugin_data_persists_after_update:
path_escape_rejected:
unsafe_http_rejected / redirect_credential_stripped:
disable_enable_update_uninstall_results:
rollout: pass | hold | rollback
remaining_client_specific_layer:
Enter fullscreen mode Exit fullscreen mode

FAQ

Can I install an Agent Plugin from GitHub or npm?

Yes. Qwen Code's existing extension sources include local paths, archives, Git repositories, archive URLs, and scoped npm packages. Pin the artifact and start at project scope.

Why did the plugin install but its command or agent is missing?

Because 0.21.11 intentionally loads only the portable Skill and supported MCP slice. Commands, agents, and hooks are ignored, not translated.

Does allowed-tools pre-approve tools in Qwen Code?

No. The field is recognized as metadata but does not grant pre-approved Qwen tools. Qwen's permission policy remains authoritative.

Is legacy SSE MCP automatically upgraded to Streamable HTTP?

No. Legacy HTTP+SSE entries are skipped. Use a supported stdio or Streamable HTTP definition and verify it explicitly.

Sources

Top comments (0)