学习指南: 第14部分：通过Qwen Code技能掌握自有流程

模块「第14部分：通过Qwen Code技能掌握自有流程」中第 2 / 5 节课

您正在未登录状态下查看课程。请登录，以保存进度并参加测试。

主题: 第14部分通过 Qwen Code 技能实现自有流程

难度等级: 中级

预计学习时间: 4-6 小时（理论 + 实践）

前置要求: Qwen Code 基础知识及 CLI 代理操作

理解 Git 及分支管理

具备 Markdown 使用经验

了解 SDD（规范驱动开发）概念

已完成课程第 1-13 部分（特别是 QWEN.md 的使用）

学习目标: 在 Qwen Code 中创建和配置代理技能（skills），实现重复性流程的自动化

区分个人技能与项目技能，并能为团队协作合理选择技能类型

在 SKILL.md 的 YAML 头部中撰写有效的 description，确保技能能被正确自动识别

实施升级规则，防止代理执行不必要的自主操作

运用上下文卫生技术，维持长时间会话中代理的工作质量

概述: 本课程部分聚焦于通过 Qwen Code 的技能系统实现重复性工程流程的自动化。您将学习如何将频繁重复的请求转化为结构化、可复用的代理技能，创建项目级和个人级技能，实施升级规则以确保代理安全运行，并管理长时间会话的上下文。核心关注实际应用：SDD 格式的功能规格说明和变更日志维护作为典型技能示例，能够加速团队协作并标准化工程实践。

关键概念: 代理技能（skill）：包含 SKILL.md 文件的目录，描述特定流程的适用场景和执行方式。技能是 Qwen Code 中重复请求自动化的基本单元。与斜杠命令不同，技能由模型自动调用或通过 /skills 触发，描述的是一种能力而非固定接口。

个人技能：位于 ~/.qwen/skills/<name>/SKILL.md 的技能。仅对当前机器上的当前用户可用。适合个人偏好和实验，但不会被纳入版本控制系统。

项目技能：位于仓库内 .qwen/skills/<name>/SKILL.md 的技能。纳入 Git 管理，成为团队工程流程的一部分，确保所有开发者和处理该项目的代理之间的一致性。

SKILL.md 的 YAML 头部：文件开头位于 --- 标记之间的 YAML 格式元数据。包含必填字段 name（无空格）和 description（具体的适用条件描述）。正确的头部对代理识别技能至关重要。

升级规则：明确约定的契约，描述代理必须停止运行并向人类请求确认的情形，而非自行采取行动。防止代理在上下文不足时猜测，避免产生不必要的变更。

上下文退化（context rot）：长时间会话中因无关上下文累积导致代理工作质量下降的现象。相邻任务的旧决策随机混入当前工作，降低输出的准确性和相关性。

上下文卫生：管理代理上下文的一系列实践：角色切换时定期使用 /clear、限制会话时长、通过 @file 明确指定文件而非传递整个目录、怀疑混淆时重启并重新读取 QWEN.md。

技能辅助文件：技能目录中的额外资源（templates/、示例、代码片段），SKILL.md 可引用这些文件来扩展功能，同时避免主文件膨胀。模板中的注释不会被复制到最终规格说明中。

Agents.md：仓库根目录的跨代理标准规则，作为 QWEN.md 的补充。不仅 Qwen Code 可读，其他兼容工具也能读取。确保同一项目中多个不同代理并行使用时的一致性。

练习题: 名称: 创建基础功能规格说明技能

问题: 您的项目中经常根据路线图创建新功能的 SDD 规格说明。重复出现的请求是："为 roadmap.md 中的下一阶段创建规格说明"。需要通过代理技能将此流程自动化。创建一个项目技能 feature-spec，包含正确的 YAML 头部、8 步流程、三个输出文件（requirements.md、plan.md、validation.md）及约束条件。通过 /skills 验证识别情况。

解决方案: 1. 创建目录：mkdir -p .qwen/skills/feature-spec

创建文件 .qwen/skills/feature-spec/SKILL.md，内容如下：

--- name: feature-spec description: 从路线图中下一个未完成阶段创建新的 SDD 功能规格说明。在开始下一个功能、编写规格说明或准备新阶段实施前使用。 --- # 功能规格说明 ## 流程

读取 specs/roadmap.md
找到第一个未完成阶段
创建分支 phase-N-kebab-name
向用户提出三组问题：边界、决策、上下文
读取 specs/mission.md 和 specs/tech-stack.md
创建 specs/YYYY-MM-DD-feature-name/
写入 requirements.md、plan.md、validation.md
不实现代码

## 文件 requirements.md — 边界、边界外内容、决策、上下文、待解决问题 ## 文件 plan.md — 编号任务组，每组单独验证 ## 文件 validation.md — 自动检查、手动走查、偏差检查、完成标准 ## 约束：遵守 tech-stack.md，未经批准不添加依赖，保持阶段可交付，不编辑无关文件

重启 Qwen Code
执行 /skills — 确认 feature-spec 显示
验证调用："使用 feature-spec 技能开始路线图中的下一个功能。不要实现代码"
若技能未生效，检查：文件路径、YAML 头部正确性（开头和结尾的 ---）、name 无空格、description 具体、代理已重启

难度: 初级

名称: 使用辅助模板扩展技能

问题: 功能规格说明流程不断扩展，SKILL.md 文件变得臃肿。此外，不同规格需要统一的结构，但团队花费时间在格式调整上。需要将模板提取到独立文件中，并更新 SKILL.md 以使用这些模板。

解决方案: 1. 在技能内创建 templates 目录：mkdir -p .qwen/skills/feature-spec/templates

创建 .qwen/skills/feature-spec/templates/requirements.md，初始结构如下：

# 需求 ## 边界  ## 边界外内容  ## 决策  ## 上下文  ## 待解决问题

类似地创建 templates/plan.md 和 templates/validation.md
更新 SKILL.md，在流程中添加：

"使用 templates/requirements.md 作为初始结构。不要将模板中的注释复制到最终规格说明中。"

验证代理正确使用模板，且不将指导注释带入输出文件
提交变更：git add .qwen/skills/ && git commit -m "Add feature-spec skill with templates"

难度: 中级

名称: 实施升级规则

问题: 项目中的代理多次自行做出争议决策：未经协商添加依赖、修改规格边界外的文件、编辑 tech-stack.md。需要在 QWEN.md 或技能中形式化升级规则，确保代理必须停止并请求确认。

解决方案: 1. 打开或创建仓库根目录的 QWEN.md（或添加到现有 SKILL.md）

添加"升级规则"章节：

在以下情况中停止并询问用户，不要自行行动：

功能规格中的某需求存在不同解读；
准备修改当前规格边界外的文件；
准备添加 tech-stack.md 中未列出的新依赖；
准备修改 tech-stack.md、mission.md 或 roadmap.md；
需要执行影响范围非平凡的迁移、drop、delete 或 rm；
找不到用户引用的文件；
结果与 validation.md 中的事实不符，且该事实未标记为"延期"；
用户请求与 QWEN.md 中先前接受的规则冲突。

每种情况下输出简短说明，指出具体何处不明确，并提供 2-3 个具体选项供选择。不要替用户决定。

在场景中测试：请求代理添加 tech-stack.md 中不存在的库 — 确认其停止并提供选项
进阶：学习第 17 部分的 Stop 钩子，用于程序化验证规则遵守情况

难度: 中级

名称: 创建变更日志技能

问题: 团队在功能合并前手动更新 CHANGELOG.md 耗费时间。提交历史分散，格式不统一。创建一个基于 git log 和 git diff 自动处理流程的 changelog 技能。

解决方案: 1. 创建目录：mkdir -p .qwen/skills/changelog

创建 .qwen/skills/changelog/SKILL.md：

--- name: changelog description: 在功能分支合并前，根据 Git 历史和当前分支变更更新 CHANGELOG.md。 --- # 变更日志

查看相对于 main 的 git log 和 git diff
创建或更新 CHANGELOG.md
使用带日期的标题
撰写利益相关者易懂的简洁条目
不包含噪音般的内部细节
重启 Qwen Code，通过 /skills 验证
创建包含若干提交的测试分支，请求代理使用 changelog 技能
检查结果：标题含日期、无"重构函数 X"等内部细节、有面向用户的清晰描述
在实际合并到 main 前使用该技能

难度: 初级

名称: 诊断和解决技能识别问题

问题: 您创建了技能，但代理在 /skills 中看不到或明确请求时不应用。系统性地诊断并解决问题。

解决方案: 1. 检查路径：文件必须位于 .qwen/skills/<name>/SKILL.md（项目级）或 ~/.qwen/skills/<name>/SKILL.md（个人级）

检查 YAML 头部：

以精确的 --- 标记开始和结束（无空格、无 BOM）
name 字段无空格，仅使用拉丁字母、连字符、下划线
description 字段具体描述适用条件，避免"有用的技能"等泛泛之词

检查权限：文件必须可读
检查重启：Qwen Code 启动时缓存技能，变更需要重启
检查 Markdown 语法：损坏的标题或表格可能妨碍解析
检查名称冲突：两个同名技能不允许
若一切正确 — 检查 Qwen Code 版本，可能需要更新
临时解决方案：通过 /load 或您版本的等效命令显式导入

难度: 中级

名称: 使用上下文卫生优化长时间会话

问题: 您已与代理协作处理复杂任务 90 分钟。观察到上下文退化迹象：代理引用先前任务的决策、建议无关文件、混淆当前功能边界。应用上下文卫生技术恢复工作质量。

解决方案: 1. 执行 /clear 完全清除会话上下文

从零重新读取 QWEN.md："读取 QWEN.md 并遵循其规则"
重新读取活跃规格说明："读取 specs/YYYY-MM-DD-feature-name/requirements.md 及所有相关文件"
通过 @file 明确指定所需文件，避免"自己找"或传递整个目录
将剩余工作拆分为每段 15-20 分钟的子任务
子任务之间使用 /clear 并仅重新读取相关上下文
若启用自动上下文压缩 — 注意它会保留可能包含错误提示的摘要；角色切换时 /clean 更可取
将中间结果记录到项目文件中，不依赖会话记忆

难度: 高级

案例研究: 名称: 金融科技初创公司实施 SDD 技能：从混乱到标准化

场景: 拥有 12 名开发者和 3 个产品团队的金融科技初创公司。每个团队使用不同的功能规格格式：一些用 Google Docs，一些用 Notion，还有一些完全依赖口头约定。开发者在团队间轮换时需要 2-3 天适应新格式。引入 Qwen Code 未解决问题：代理按上下文中最近看到的格式生成规格，导致进一步碎片化。

挑战: 需要实现：(1) 所有团队统一的 SDD 规格格式，(2) 代理无需额外指令自动应用该格式，(3) 格式的版本控制和演进，(4) 最小化轮换适应时间。

解决方案: 技术负责人在公司根仓库（包含 40+ 服务的单体仓库）创建了项目技能 feature-spec。技能包含：严格的 8 步流程、三个输出文件及详细内容要求、templates/ 子目录中的模板、以及禁止代理偏离 tech-stack.md 的升级规则。此外创建了 changelog 技能用于统一维护变更日志。为跨团队一致性，在单体仓库根目录添加了 AGENTS.md，包含所有团队工具可读的基本规则。

结果: 实施 3 周后：规格创建时间从 4 小时缩短至 45 分钟（含代理澄清问题时间）；轮换适应时间缩短至 2 小时（只需阅读 SKILL.md）；94% 的规格在评审时无需修改（此前为 60%）；统一的 CHANGELOG 实现了发布说明自动生成；团队发现并纠正了 7 起代理试图添加未批准依赖的案例，得益于升级规则。

经验教训: 根仓库中的项目技能比单个开发者的个人技能更能有效扩展实践

升级规则并非冗余官僚程序，而是节省成本：预防的 7 起依赖事件节省了一周的回退工作

templates/ 中的模板加速代理工作并提升一致性，但需要明确"不复制注释"的规则

使用多个工具（Qwen Code、Cursor、自定义脚本）时 AGENTS.md 必不可少 — 防止规则分歧