Where Qwen Code stores QWEN.md, skills, agents, and MCP servers

Qwen Code is a fork of Gemini CLI, and its file layout shows it: a global ~/.qwen/ folder mirroring ~/.gemini/, per-project .qwen/ folders, and a QWEN.md context file where Gemini reads GEMINI.md. It tracks its upstream closely but has diverged in a few places worth knowing. ~ is your home directory; paths starting with .qwen/ are relative to a project root.

At a glance

Artifact	Global	Per-project	Format
Context / rules	~/.qwen/QWEN.md	QWEN.md (project root, parents, and subdirectories)	Markdown
Skills	~/.qwen/skills/<name>/SKILL.md	.qwen/skills/<name>/SKILL.md	Markdown + YAML frontmatter
Subagents	~/.qwen/agents/*.md	.qwen/agents/*.md	Markdown + YAML frontmatter
Commands	~/.qwen/commands/**/*.md	.qwen/commands/**/*.md	Markdown (TOML deprecated)
MCP servers	~/.qwen/settings.json → mcpServers	.qwen/settings.json → mcpServers	JSON
Settings	~/.qwen/settings.json	.qwen/settings.json	JSON
Extensions	~/.qwen/extensions/<name>/qwen-extension.json	—	JSON manifest + bundled dirs

QWEN.md context files

Qwen Code searches for QWEN.md from the current working directory up through each parent until it hits the project root (the first .git folder) or your home directory, plus the global ~/.qwen/QWEN.md for instructions that apply to every project. Everything found is concatenated — with separators naming each file’s origin — into the system prompt. Context files can import other Markdown files with @path/to/file.md, so a large QWEN.md can be split into modules.

The filename is configurable — and renames hide the file

context.fileName in settings.json can rename the context file (a string or an array, so a team can read AGENTS.md and QWEN.md together). Handy for cross-tool setups — but any backup script or scanner grepping only for QWEN.md misses a renamed context file entirely.

Skills

Same SKILL.md-folder convention as Claude Code and Cursor: a directory per skill under ~/.qwen/skills/ (personal) or .qwen/skills/ (committed with the repo). Frontmatter requires name and description; Qwen adds optional extras — priority (sort order in /skills), paths (the skill stays invisible until a matching file is touched), and flags to hide a skill from either the user or the model.

Subagents

Subagent definitions are Markdown files with YAML frontmatter in ~/.qwen/agents/ (all projects) or .qwen/agents/ (one project) — project agents win on name collisions. The /agents create wizard writes these files for you; they’re plain Markdown underneath, so they index and convert like any other agent file.

Custom commands

Each Markdown file under a commands/ directory becomes a slash command, with subdirectories as namespaces (commands/git/commit.md → /git:commit) and {{args}} for parameter injection.

Markdown commands — a divergence from Gemini CLI

Upstream Gemini CLI writes custom commands as TOML. Qwen Code deprecated TOML in favor of Markdown with YAML frontmatter (old .toml commands still load). Copying a command file between the two tools works in one direction more often than the other — this is the most visible place the fork has drifted.

settings.json and MCP servers

Settings merge across four levels — system defaults, user (~/.qwen/settings.json), project (.qwen/settings.json), and a system-override file (/etc/qwen-code/settings.json on Linux, C:\ProgramData\qwen-code\settings.json on Windows). MCP servers live in the same file, as a top-level mcpServers map: command/args/env for stdio servers, url or httpUrl plus headers for remote ones. The env and headers values are where API keys end up — treat both settings files as secret-adjacent.

Invalid JSON gets your settings renamed away

Qwen Code validates settings.json strictly. If the file doesn’t match the expected schema, the app renames it to settings.json.corrupted and starts fresh — your MCP servers and settings silently vanish until you notice the renamed file. Hand-edit carefully, and check for a .corrupted sibling when config mysteriously disappears.

Extensions

Installed extensions live under ~/.qwen/extensions/<name>/, each with a qwen-extension.json manifest that can bundle MCP servers, a commands/ directory, skills/, agents/, and its own context file. Like Claude Code’s plugin cache, these bundled artifacts behave exactly like your own but live where no one looks.

Seeing all of it at once

Quartermaster’s scanner indexes every location on this page — QWEN.md files, skills, agents, commands, and one record per MCP server parsed out of settings.json — into one searchable registry alongside Claude Code, Cursor, Codex, and 8 more tools. Secrets are never indexed — env/header key names kept, values dropped — and conversion can move a skill or MCP config between Qwen Code and any of them. See the full discovery map or the quickstart.