Qwen Code 是阿里通义团队开源的终端 AI 编程 Agent，代码托管在 QwenLM GitHub 组织，产品主页见 Qwen 官网。它为 Qwen 系列模型做了专门优化，官方仓库的口号是"lives in your terminal"，同时覆盖编辑器、桌面、浏览器与对话等形态。这类工具正在从"帮你写代码"进化为"替你完成工程任务"，而任务完成度的上限，越来越取决于它掌握了多少你所在领域的专业知识。
Agent Skills 就是 Qwen Code 给出的答案：把专业知识打包为可发现的目录单元，模型在相关场景自动加载。这套体系与社区通行的 SKILL.md 开放格式一致，意味着技能资产可以在不同助手之间流动。本文按"概述、结构、发现与调用、官方示例、生态互通、自动维护"的顺序展开，内容均来自官方文档与官方仓库。
1、Qwen Code 技能体系概述
官方文档对 Agent Skills 的定义非常直白——"把专业知识打包为可发现的能力"。每个技能是一个目录，核心是一份写了完整指令的 SKILL.md 文件，旁边可以放 reference.md、examples.md、scripts/、templates/ 等附加资源。模型会在判断当前任务与某个技能相关时加载它，而不是把所有规则一股脑塞进系统提示词。
与手写提示词模板相比，这套设计有三个特点：
- 声明式：Markdown 加 YAML 元数据，不用写胶水代码；
- 按需加载：只有相关技能才进入上下文，控制 token 开销；
- 目录即分发：一个文件夹就是完整的分发单元，git 仓库就是同步通道。
官方仓库本身内置了一批捆绑技能（bundled skills），例如源码里的 qc-helper；同时 QwenLM 组织还开源了独立的示例技能库，第 5 节会展开。
2、SKILL.md 的结构与字段
SKILL.md 由 YAML frontmatter 和 Markdown 正文组成：frontmatter 声明元数据，正文是写给模型看的操作指令。一个最小示例如下：
---
name: commit-style
description: 需要生成符合约定式提交规范的 commit message 时使用
paths:
- "**/*.go"
priority: 1
---
## 目标
检查暂存区改动，生成规范提交信息。
## 步骤
1. 运行 git diff --cached 概览改动
2. 归纳变更主题，套用提交模板
3. 标题用英文，正文用中文且不超过 50 字
解读：name 与 description 是模型判断"何时用我"的依据，官方建议 description 同时写清"是什么"和"什么时候用"；paths 是门控条件，只有当工具触碰了匹配文件，该技能才会在会话中激活。frontmatter 的完整字段如下：
| 字段 | 作用 |
|---|---|
name |
技能名，允许 Unicode 字母数字与 _ : . - |
description |
供模型判断相关性，建议包含 what 与 when |
paths |
glob 列表，按项目根相对路径匹配后才激活 |
priority |
数字，仅影响 /skills 面板排序 |
user-invocable |
false 时对用户隐藏，模型仍可调用 |
disable-model-invocation |
true 时对模型隐藏，仅保留手动调用 |
hooks |
声明确定性规则，脚本经 $QWEN_SKILL_ROOT 定位 |
值得一提的是，name 的校验规则基于 Unicode 字母数字——中文可以直接作为技能名，对中文团队命名内部规范类技能相当友好。更多细节见官方技能文档。
3、技能的存放与发现
技能按作用域分四类来源，目录约定如下：
~/.qwen/skills/ # 个人技能：所有项目可用
.qwen/skills/ # 项目技能：随仓库共享
└── commit-style/
├── SKILL.md # 必需：指令与元数据
├── reference.md # 可选：深度参考文档
├── examples.md # 可选：示例集合
├── scripts/ # 可选：配套脚本
└── templates/ # 可选：模板文件
解读：个人技能放在用户主目录，项目技能放在仓库内的 .qwen/skills/ 并提交到 git；此外还有扩展技能（随扩展的 skills/ 目录安装）和捆绑技能（随 Qwen Code 一起发布）。运行 /learn 时，系统还会把会话中沉淀的经验生成到 .qwen/skills/learned-skill-<name>/，frontmatter 标记 source: learned。
发现技能有三条路：输入 / 触发斜杠补全；/skills 打开管理面板，可浏览、搜索、启停技能；或者直接问模型"你有哪些技能"。用文件系统检查也很直接：
ls ~/.qwen/skills/ # 个人技能
ls .qwen/skills/ # 项目技能
官方文档明确：会话期间 Qwen Code 会监视技能目录变化，改完即生效；bare 模式不启动监视，需要重启；加载失败时用 qwen --debug 排查。想参考真实写法，可以读内置技能 qc-helper 的 SKILL.md。
4、调用方式与按需加载
技能的默认触发方式是模型自主调用（model-invoked）：模型根据 description 与当前任务的相关性决定是否加载，用户不必显式点名。想强制使用时，用斜杠命令 /<skill-name> 直接调用；注意旧版语法 /skills <skill-name> 已经变更——现在 /skills 只打开面板并忽略参数。
paths 门控是按需加载的关键：被门控的技能在匹配文件被触碰之前，根本不会出现在模型的可用列表里；编辑技能文件会触发缓存刷新，激活状态随之重置。这套机制把上下文预算花在刀刃上——写 Go 时不会加载前端规范，改文档时不会加载部署脚本。
扩展技能的命名带扩展前缀，注册为 <extensionName>:<name> 的形式（例如 rust:pdf），裸名不是别名，调用时要写全。参数文件按名称做归一化，冒号会被替换成下划线，rust:pdf 与 rust_pdf 会共用同一份参数文件——自定义技能时留意这个细节。
5、官方示例技能仓库
QwenLM 组织开源了 qwen-code-examples 示例仓库（MIT 协议），skills/ 目录收录了多个可直接使用的技能，每个目录内的 SKILL.md 附带完整设置说明。官方主推的四个如下：
| 技能 | 功能 |
|---|---|
youtube-transcript-extractor |
提取带时间戳的 YouTube 字幕，自动语言检测 |
image-generate |
基于 DashScope 万相文生图，含提示词优化 |
auto-pr |
分支准备、代码审查、经 GitHub CLI 自动提 PR |
dashboard-builder |
生成 React/Next.js 全栈仪表盘应用 |
解读：这四个示例分别代表技能的四种典型形态——数据处理、外部 API 调用、工程流程自动化和多文件脚手架生成。使用前需要 Python 3.9+ 与 Node.js 环境，个别技能（如文生图）要配置 DASHSCOPE_API_KEY；clone 仓库后按各技能目录里的说明安装即可。
6、开放格式与生态互通
SKILL.md 是社区通行的开放格式，Qwen Code 没有发明私有协议。这带来两个直接收益：其一，QwenLM 开源的技能不止服务 Qwen Code——多个社区技能收录站点已经收录了这些技能，并标注了它们可运行的其他助手；其二，反过来，社区里沉淀的既有技能资产，放进 .qwen/skills/ 就能被 Qwen Code 直接使用。
对工程团队来说，这意味着技能资产不被单一运行时锁定。今天用 Qwen Code 写的部署规范，明天换一个支持相同格式的终端 Agent，目录拷过去照常工作。评估技能体系时，格式开放性应当和功能强度放在同一天平上。
提示：判断一个技能能否跨助手复用，看它是否依赖特定运行时的专有能力——只由 Markdown 指令加普通脚本构成的技能，移植成本接近零。
7、Auto Skill 自动维护
技能多了会腐烂，Qwen Code 用 Auto Skill 机制自动治理：它只管理 .qwen/skills/auto-skill-* 且 frontmatter 标记 source: auto-skill 的目录，不碰手写技能。规则是——30 天没有成功使用就标记为 stale，90 天后移入 .qwen/archived-skills/ 归档目录，只归档不删除；整理动作至多每 7 天执行一次，被 pin 的技能豁免。
配套的 /curator 命令用于查看治理状态，支持 run --dry-run 预览、pin/unpin 固定或解除、restore 找回归档技能。这个设计思路值得借鉴：知识库需要新陈代谢，否则检索质量会随规模衰减。
8、总结
回顾全文：Qwen Code 的 Agent Skills 把领域知识组织为"目录 + SKILL.md"的开放单元——frontmatter 声明元数据与门控条件，正文写给模型看；个人、项目、扩展、捆绑四层来源覆盖不同作用域；模型自主调用加斜杠显式调用，paths 门控实现按需加载；官方示例仓库提供了从字幕提取到自动 PR 的完整参照；Auto Skill 则解决了技能堆积的长期治理问题。
对于正在评估终端 Agent 的团队，建议先用半天把一两条内部规范（提交信息格式、发版 checklist、部署 runbook）写成技能放进 .qwen/skills/ 并提交进 git，一周后对比模型的表现差异；对于已经积累了不少提示词资产的个人，把高频提示词改写成带 description 的 SKILL.md，是迁移成本最低、复用价值最高的一步。
