技能与子智能体

Agent Skills

技能是通过包含指令（以及可选的脚本/资源）的有组织文件夹来扩展模型效能的模块化能力。每个技能由一个带指令的 SKILL.md 文件加可选的辅助文件（如脚本和模板）组成，模型在相关时加载它。技能是模型调用的：模型根据你的请求和技能的描述自主决定何时使用，这与你显式输入 /command 的用户调用的斜杠命令不同。想显式调用某个技能，把它的名称作为斜杠命令输入：/<skill-name>；输入 / 会自动补全并浏览可用技能及其描述；/skills 命令打开技能面板，可以交互式地浏览、搜索、切换和启动技能。<skill-name> 总是技能的注册名；来自已安装扩展的技能，名称带所有者前缀（rust:pdf 而不是 pdf），所以要输入 /rust:pdf。好处：为你的工作流扩展 Qwen Code；通过 git 在团队内共享专长；减少重复提示；组合多个技能处理复杂任务。

创建技能

技能存储为包含 SKILL.md 文件的目录。用 /learn 生成项目技能：把现有的知识来源提炼成可复用的项目技能，如 /learn https://docs.example.com/api、/learn ~/projects/acme-sdk、/learn Our deploy process: run migrate, deploy the service, then check health。该命令作为普通的智能体轮次运行，结果创建在 .qwen/skills/learned-skill-<name>/SKILL.md 下，frontmatter 里带 source: learned；使用或共享前要评审生成的指令。/learn 还接受本地或直链的 .mp4、.webm、.mov 和 .m4v 视频，在路径或 URL 之后加文字可以让生成的技能聚焦教程的某个部分（如 /learn ./tutorial.mp4 focus on the deployment workflow）；视频学习需要 OpenAI 兼容提供商上支持视频的模型，YouTube 页面 URL 不是直接视频输入，要把视频下载到工作区并传本地路径。

• 个人技能：跨你所有项目可用，存放在 ~/.qwen/skills/（mkdir -p ~/.qwen/skills/my-skill-name），用于你个人的工作流和偏好、你正在开发的技能和个人效率助手。
• 项目技能：与你的团队共享，存放在项目里的 .qwen/skills/，用于团队工作流和约定、项目特定的专长以及共享的实用工具和脚本；项目技能可以检入 git，自动对队友可用。

维护自动生成的项目技能：Qwen Code 在本地跟踪生成的项目技能的成功使用，即使新的 Auto Skill 生成被禁用时也如此。启用 Auto Skill 时，它定期把不活跃的生成技能移出活动库：30 天没有成功使用或 SKILL.md 编辑，自动技能被标记为过时；90 天后，它的完整目录被移到 .qwen/archived-skills/，没有任何东西被永久删除；自动维护在受信任的工作区里最多每 7 天运行一次，每个新观察到的自动技能在维护开始前都有完整的宽限期；被固定的自动技能不参与自动的过时和归档转换。用 /curator 查看活动、过时、归档和固定的自动技能；/curator run --dry-run 预览一次维护，/curator run 立即应用，/curator pin <directory> / unpin <directory> 控制按技能的维护，/curator restore <directory> 把归档的自动技能移回；状态和 dry-run 预览在安全模式和不受信任的工作区里可用，应用维护、更改固定和恢复归档需要安全模式之外的受信任工作区。

编写 SKILL.md

创建带 YAML frontmatter 和 Markdown 内容的 SKILL.md：

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
priority: 10
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for Qwen Code.

## Examples
Show concrete examples of using this Skill.

字段要求：name 是非空字符串，匹配 /^[\p{L}\p{N}_:.-]+$/u（Unicode 字母和数字（CJK/西里尔/带重音的拉丁字母都行），加 _、:、.、-；空白、斜杠、括号和其他结构上不安全的字符在解析时被拒绝；被允许的 : 正是让扩展注册的技能能带所有者前缀的原因）；description 是非空字符串；priority 可选，存在时必须是有限数字，值越高在 /skills 列表里越靠前（只影响 /skills 列表，输入 / 的补全和 /help 的自定义命令视图仍按字母序，所以高优先级技能永远不会重排内置命令；省略或无效的值视为未设置，负优先级允许，排在未设置的技能之下）。推荐的约定：可共享的名称优先用小写 ASCII 加连字符（如 tsx-helper）；让 description 具体，既包含技能做什么也包含何时使用（用户自然会提到的关键词）；谨慎使用 priority。

可选：用文件路径门控技能（paths:）：对只与代码库特定部分相关的技能，添加 glob 模式的 paths: 列表；技能在工具调用触及匹配的文件之前不出现在模型的可用技能列表里：

---
name: tsx-helper
description: React TSX component helper
paths:
  - 'src/**/*.tsx'
  - 'packages/*/src/**/*.tsx'
---

注意：glob 用 picomatch 相对项目根目录匹配，项目根之外的文件永远不触发激活；路径门控的技能一旦触及匹配文件，就在会话剩余时间里保持激活，新会话，或编辑任何技能文件触发的 refreshCache 会重置激活；paths: 只门控模型的发现，且只在 SkillTool 列表层面：除非设了 user-invocable: false，你始终可以通过 /<skill-name> 或 /skills 选择器自己调用路径门控的技能（这条用户路径不管激活状态如何都运行技能正文）；把 paths: 与 disable-model-invocation: true 组合是允许的，但门控没有效果（技能不论如何都对模型隐藏）。可选：控制用户和模型调用：技能默认可由用户调用；想对直接的斜杠命令使用隐藏、同时保持对模型调用可用，设置 user-invocable: false。

子智能体

子智能体是处理 Qwen Code 内特定类型任务的专门 AI 助手，让你把聚焦的工作委派给配置了任务特定提示、工具和行为的 AI 智能体。它们：专注于特定任务（每个子智能体配置了针对特定类型工作的聚焦系统提示）；有独立的上下文（维护自己的对话历史，与你的主聊天分开）；使用受控的工具（可配置每个子智能体能访问哪些工具）；自主工作（一旦被给予任务，就独立工作直到完成或失败）；提供详细的反馈（实时看到它们的进度、工具使用和执行统计）。

Claude Code 和 Codex 子智能体：内置的 claude-code 和 codex 智能体委派给单独安装的原生工具：安装并认证 Claude Code 及其 claude-agent-acp 适配器，或 Codex 及其 codex 可执行文件，并让可执行文件在 PATH 上。这些智能体使用它们原生的模型和认证设置。它们默认前台执行，设 run_in_background: true 以接收后台完成通知；需要受信任的工作区且在安全模式下不可用；两个执行器都支持 macOS/Linux（包括 WSL），原生 Windows 启动会在启动前被拒绝并给出平台指引。Claude Code 使用 ACP 执行器，会话保留期间支持继续输入；Codex 为单个任务使用临时的 app-server 线程并返回最终答案（Codex 任务不能接收消息或恢复，需另开新任务）。自定义 Codex 智能体用 executor frontmatter：

---
name: codex-review
description: Review code with Codex
executor:
  kind: codex
  command: codex
background: false
---

Review the changes and report verified defects.

省略 executor.args 会启动 codex app-server --stdio；提供的参数会替换该默认值。自定义 Claude Code 智能体用 kind: acp 和 command: claude-agent-acp。外部执行器不支持 Qwen 模型覆盖、工具列表、子智能体 hooks、maxTurns、fork 历史、团队和工作流。Codex 无人值守运行：没有智能体覆盖时，default、plan 和 auto 会话使用只读沙盒（Qwen 的 AUTO 分类器不检查原生命令）；要允许写入，在会话或 Codex 智能体定义里显式选 auto-edit。

Fork 子智能体：除具名子智能体外，Qwen Code 还支持fork，用 subagent_type: "fork" 显式选择。fork 继承父级的完整对话上下文，通常在后台分离运行；交互和无头会话里都能用 fork（无头 fork 总是走后台路径）。fork_turns 只对 fork 有效：省略或用 all 继承完整的父对话；正整数字符串如 "3" 继承最近三个真实用户轮次（工具响应和纯系统提醒不算用户轮次）。fork_tools 限制 fork 的工具执行：数组可含确切的规范工具名（如 read_file 和 grep_search）或 MCP 服务器模式（如 mcp__github）；fork 仍收到与不受限的 fork 相同的模型可见工具声明（保留其提示缓存前缀），但执行时只允许列出的工具；fork 从不执行 ask_user_question（需要用户输入时，向父智能体报告阻碍）；省略 fork_tools 允许其他所有继承的工具；空数组拒绝每次工具调用；不接受 *；通配符只接受 mcp__* 或尾部的 MCP 工具前缀模式（如 mcp__github__read_*）；shell 命令参数模式不被支持。这是调用方提供的单次调用限制，会缩小子 fork 的能力，但不是管理员强制的安全沙盒。fork_profile 复用 fork 限制：项目可以在 .qwen/fork-profiles/<name>.md 里保存命名的 fork 限制（frontmatter 里 name、必需的 tools、可选的 ≤200 字符的 promptHint），然后用 fork_profile 选择；它只对 fork 有效，不能与 fork_tools 或具名队友组合，目前仅限项目，启动时解析一次，在安全模式和 bare 模式下不可用。

AI 在需要这些时自动使用 fork：并行运行多个研究任务（如「调查模块 A、B 和 C」）；在继续主对话的同时做后台工作；委派需要理解当前对话上下文的任务。所有 fork 共享父级完全相同的 API 请求前缀（系统提示、工具、对话历史），启用 DashScope 提示缓存命中：3 个 fork 并行运行时，共享前缀只缓存一次并复用，比独立子智能体节省 80% 以上的 token 成本。fork 子级不能再派生任何子智能体（运行时强制：fork 调用 Agent 工具会收到要求它直接执行任务的错误）。目前的限制：没有 worktree 隔离，fork 共享父级的工作目录，多个 fork 并发修改文件可能冲突。

后台智能体续接：顶层的常规子智能体默认在后台运行。后台智能体完成后，Qwen Code 保留足够的状态来继续相关工作而不启动重复的智能体：list_agents 返回当前会话里可寻址的后台智能体（包括随恢复的会话还原的兼容智能体），每个条目含 task_id、状态以及是否能接收消息；带该 task_id 的 send_message 为运行中的智能体排队一条消息、恢复暂停的智能体或继续已完成的智能体（已完成的智能体在可用时复用其常驻运行时，否则从保留的转录复活）；继续的智能体通过另一次完成通知报告它的下一个结果。相关的后续工作用续接，不相关的任务或前一个智能体无法恢复时启动新的智能体。在交互式 TUI 和 ACP 会话里，后台智能体、shell、监视器和工作流的完成通知共享一个队列，会话空闲后排空进入一个模型轮次；队列最多容纳 20 条通知，第 21 条到来时先驱逐临时的监视器脉冲，否则驱逐最老的排队通知；智能体结果、工作流结果和定时提示在交互式 TUI 里从不被驱逐；被丢弃的通知会被报告而不是悄悄丢掉。对具名的常规子智能体，working_dir 把智能体固定到当前仓库已有的 git worktree（相对路径从当前目录解析，worktree 必须已作为本仓库的关联 worktree 在 git 里注册）；它不能与 subagent_type: "fork" 组合。

快速开始：用 /agents create 通过引导向导创建你的第一个子智能体；用 /agents manage 查看和管理已配置的子智能体；使用时直接让主 AI 执行与你子智能体专长匹配的任务，AI 会自动委派合适的工作（例如「Please write comprehensive tests for the authentication module」会被委派给你的测试专家子智能体，实时显示测试创建进度并返回完成的测试文件和执行摘要）。存放位置：子智能体以 Markdown 文件存放在多个位置：项目级 .qwen/agents/（优先级最高）、用户级 ~/.qwen/agents/（后备）、扩展级（由已安装的扩展提供，在 /agents manage 对话框的「Extension Agents」部分出现，不能直接编辑，要编辑扩展源码）。

文件格式：子智能体用带 YAML frontmatter 的 Markdown 文件配置：

---
name: agent-name
description: Brief description of when and how to use this agent
model: inherit # 可选：inherit、fast、modelId 或 authType:modelId
approvalMode: auto-edit # 可选：default、plan、auto-edit、yolo、bubble
tools:         # 可选：工具允许列表
  - tool1
  - tool2
disallowedTools: # 可选：工具阻止列表
  - tool3
---

System prompt content goes here.
Multiple paragraphs are supported.

模型选择：用可选的 model frontmatter 字段控制子智能体使用的模型：inherit（与主对话相同的模型，省略该字段同义）；fast（使用配置的 fastModel，没有有效的快速模型时回退到 inherit）；glm-5 这样的模型 ID（Qwen Code 先检查主对话的认证类型，该模型在那里不可用时可以从另一个已配置的提供商解析）；openai:gpt-4o 这样的显式提供商和模型 ID（当子智能体应该运行在主对话不同认证类型下注册的模型上时有用）。fast 选择器使用与 settings.json 或 /model --fast 配置的同一个 fastModel 设置。内置的 Explore 智能体默认继承主会话模型；要只为这个内置智能体选不同的模型，在 settings.json 里配置 agents.builtin.exploreModel 并重启（如 "agents": { "builtin": { "exploreModel": "fast" } }）。