Why your Qwen Code skill or subagent never activates

A Qwen Code skill stays on disk; the model sees only its name, description and level until something chooses it. Qwen keeps each SKILL.md and puts that metadata into the <available_skills> block at the start of the session; the body arrives when the model calls the skill tool or you type /<name>. A subagent is a separate agent loop that the agent tool starts: it gets the session's context files but not the parent's messages.

/skills and /agents manage separate the two failures: discovery or selection. A skill missing from /skills was never loaded or is hidden by settings; a skill listed there that the model never uses was loaded and not chosen. A subagent missing from /agents manage was skipped or never found; one listed but never called has a selection problem.

Run qwen --version first. This page was checked against v0.26.2 (tag 4029111) and against main at 32f6713 on 27 October 2026; behaviours marked "at the commit I read" are from that main commit.

Checked against Qwen Code's documentation and source on 27 October 2026.

Status, 27 October 2026: a parallel batch of agent calls can produce no result and an empty roster (#14410, open, 16 October 2026). A subagent can start with a prompt several times the parent's (#15660, open, 26 October 2026).

Start with the two lists#

In the terminal, /skills opens the skills panel; /agents manage opens the subagent roster and re-reads the folders before it draws the list. /skills is not a complete inventory: a skill with user-invocable: false is absent while still offered to the model, a skill hidden by skills.disabled is absent too, and a skill that appears can still be ignored. /agents manage should show every valid agent; a file that fails validation is skipped, with the reason usually only in the debug log. Start with qwen --debug when the list is short. Current 0.26 builds have no qwen agents list.

Where a Qwen Code skill has to live#

Qwen discovers skills from personal folders (~/.qwen/skills/, ~/.agents/skills/), project folders (.qwen/skills/, .agents/skills/), each path in skills.directories, installed extensions, and the bundled set.

Each skill is one directory directly under one of those roots: <root>/<skill-name>/SKILL.md. The scan is one level deep. .qwen/skills/migration-review/SKILL.md works; .qwen/skills/backend/migration-review/SKILL.md does not.

The filename is exact: SKILL.md, not skill.md. The folder name is only a container; the frontmatter name is what /skills shows and what you type after / (extension skills add an owner prefix; see below). A folder called migration-review with name: db-review becomes /db-review.

Precedence is project, then personal (including custom directories), then extension, then bundled. Inside a level, .qwen/skills beats .agents/skills, and a custom directory loads after the personal defaults. Extension skills carry their owner in the name: a pdf skill from an extension called rust is registered as rust:pdf, and /pdf is not an alias.

Two settings hide things without deleting them. skills.disabledLevels skips a whole level (project, user, extension, bundled). skills.disabled and skills.defaultDisabled hide individual names, merged case-insensitively across scopes; a user-level disabled entry cannot be undone by a project-level enabled entry. Check both ~/.qwen/settings.json and .qwen/settings.json.

skills.directories is scanned one level deep, loads its skills as personal skills, and needs a restart. Qwen watches personal and project skill folders, so adding or editing a SKILL.md usually refreshes the list after a short delay; bare mode does not start the watchers.

In an ACP (Agent Client Protocol) client such as Zed or JetBrains, /skills prints a read-only text list instead of opening the panel. If it is empty while the terminal shows the skill, check the terminal first (#5007, open, last updated 19 June 2026; a related serve/ACP loading bug was fixed in #7575, closed 24 July 2026).

Frontmatter must start on line 1 with ---, close with ---, and carry non-empty name and description. The name may use letters, digits, _, :, . and -; spaces and slashes are rejected. A missing delimiter, a tab, or a bad name skips the file without a visible error; qwen --debug shows the reason.

---
name: migration-review
description: Reviews database migrations in packages/db. Use when a migration file changes or a migration fails.
---
Review the migration for locking and rollback risk. Do not edit files.

A skill that is listed but never chosen#

Before invocation, the model sees the skill's name, description and level in an <available_skills> block. It does not see the body. The description is the routing rule, not a summary. "Helps with migrations" is weaker than "Reviews database migrations in packages/db. Use when a migration file changes, a migration fails, or the user asks about rollback risk."

Three fields change whether the model can choose it:

• disable-model-invocation: true removes it from the model's listing while leaving /<name> available.
• user-invocable: false does the opposite: the model can still call it, but it is absent from /skills and /<name>. If the slash command says "unknown command", this is the likely reason.
• A paths: list keeps the skill out of the model's listing until a tool call touches a matching file. Once activated it stays active for the session. A slash invocation runs the body but does not make the skill visible to the model; touch a matching file first if you want the model to call it too.

At the commit I read, the listing has a size cap. When the rendered block passes 8,000 characters, Qwen keeps bundled skills whole and reduces every other skill's description to its first line. Put the "use when" clause in the first line.

The reliable test is a Skill tool call in the transcript, or /<name> for the user path. /name proves the file loads and its body is usable; it does not prove the model will choose it. Reading SKILL.md with an ordinary file tool is not activation: the text arrives, but the skill's allowedTools and hooks (commands that run on tool events) are not registered. Those side effects only happen through the Skill tool or the slash command. allowedTools is a permission grant, not a limit, and an allowed-tools field written for Claude Code is ignored.

Where a subagent has to live#

A named subagent is one Markdown file in .qwen/agents/ or ~/.qwen/agents/; installed extensions can supply more. The folder is flat. Qwen reads .md files directly in it and does not descend into subdirectories. .qwen/agents/review/security.md is never loaded, and .MD does not match. /agents create walks through the fields and writes a valid file.

Precedence is project, then user, then extension, then built-in. A project file with the same name as your user file wins, even if the user file is newer. That is why editing ~/.qwen/agents/reviewer.md can appear to do nothing inside a repository that also has .qwen/agents/reviewer.md. The name comes from the frontmatter, not the filename: review.md with name: code-review registers as code-review.

name must be 2 to 50 characters of letters, numbers, hyphens or underscores. It cannot start or end with a hyphen or underscore, and self, system, user, model, tool, config, default and main are reserved. description is required. The body becomes the system prompt and must be non-empty and at least 10 characters. A file that fails any of that is skipped; ordinary validation failures go to the debug log, so /agents manage omits the file and qwen --debug shows why.

A newly added file is usually picked up without a restart: /agents manage refreshes the roster, and dispatch falls back to reading the file by name when the cache misses it. The July 2026 report about needing a restart is closed as fixed; on an older build, restart once.

A subagent that is listed but never called#

The description is the routing rule, as with a skill. The main model sees each agent's name and description and chooses from them. Write the trigger into the description, with the area, the task and the situations that should call it. Qwen's docs suggest phrases such as "use PROACTIVELY" or "MUST BE USED" for agents that should be picked up without a direct request. "Security expert" is weaker than "Reviews authentication and authorization changes in packages/api. Use when a route, middleware or permission check changes."

To invoke one explicitly, name it in the request: "Use the migration-reviewer agent to review this migration." Qwen's docs give a plain-language request, not a documented @name form; @name is the Gemini CLI habit, not the Qwen one.

A named agent runs in the background by default. The result arrives as a completion notification; if you expected an inline answer, that can look like nothing happened. /tasks lists background tasks, including a running agent. Set background: false in the definition, or run_in_background: false on the call, when the current turn must wait.

Parallel batches have a reported failure. On 0.25.2, several agent calls in one message, including the run_in_background: false form, produced no result, no error and an empty roster (#14410, open on 27 October 2026). If a batch returns nothing, launch one agent at a time and check /tasks after each.

Tool names are the other silent failure. tools: is an allowlist: omit it and the agent inherits the parent's tools; list it and the agent gets only those. Qwen resolves its own tool names and display names, but it does not translate Claude Code's. Use Qwen's canonical names: read_file, write_file, edit, run_shell_command, grep_search and glob. Edit, Grep and Glob also work as display names; Claude's Read, Write and Bash match nothing. An unrecognised name is kept as-is and matches no tool. The agent still runs, with fewer tools than you intended, and the only trace is a debug log line. This is the usual reason a copied reviewer agent cannot read files.

MCP tools, the tools exposed by external servers, follow the same rule: with no tools list the agent inherits them all; with an explicit list, only the named ones are available.

What a subagent inherits#

A named subagent starts a fresh conversation. It does not see the parent's messages or the files the parent already read. But fresh is not empty. Before the task prompt, Qwen gives it:

• its own system prompt, from the body of the file;
• the QWEN.md and AGENTS.md files Qwen loaded for the session, including @file imports, plus the session's auto-memory when it is enabled (notes Qwen wrote for itself);
• the environment bootstrap: date, operating system, working directory and a folder tree;
• the tool definitions for its tool set, including inherited MCP tools;
• an <available_skills> catalogue, but only if the skill tool is in that set;
• the approval mode: a permissive parent stays permissive, a plan-mode parent stays in plan, and a default-mode parent in a trusted folder gives the agent auto-edit.

That is enough to explain a large bill. One open report measured the parent at 42k tokens, about 21k of it startup, then a subagent task prompt of 1k and a first request the provider reported at 105k (#15660, open, 26 October 2026). The report does not isolate the component; the fixed costs above explain the direction.

The parent's /context detail describes the parent's prompt, not the child's request. To see the child's prompt tokens, use the provider's request log or usage report. To reduce them: narrow tools, remove MCP servers the task does not need, keep QWEN.md short, and do not give a subagent a skill catalogue it will not use. A subagent restricted to read_file and grep_search cannot invoke a skill at all.

A fork is the exception. subagent_type: "fork" inherits the parent conversation by default, or the last few user turns with fork_turns. It always runs detached in the background, cannot spawn another subagent, and shares the parent's working directory, so concurrent forks can overwrite each other. Use a named agent for an isolated task and a fork for work that needs the conversation you already have.

What does not carry over#

• Folders. Qwen does not read ~/.claude/skills, .claude/skills, .claude/agents, .gemini/skills or .gemini/agents. Add a Claude skills folder to skills.directories and restart, or move it; copy an agent file to .qwen/agents.
• Names. Claude's allowed-tools is ignored (Qwen reads allowedTools), and Read, Write and Bash match none of Qwen's tools. Remap them to read_file, write_file and run_shell_command.
• Shared folder. .agents/skills is read by both Qwen and Gemini; Gemini agents must move to .qwen/agents. The Gemini CLI skills and subagents guide covers the other side.

Where to go next#

• Qwen Code guides — the rest of the set.
• Why Qwen Code keeps asking for permission — when the agent is found but its tool call is blocked.
• Qwen Code says MCP is connected — when a tool exists in the main session but not inside a subagent.
• What a Claude Code subagent can and can't see — the same inheritance question for the other tool.