Skill 技能包

Skill 是 Qoder 最核心的知识复用机制。它是可执行的指令包，将最佳实践沉淀为可重复使用的技能。你可以把 Skill 理解为「AI 的快捷键」——一条命令让 AI 完成复杂的多步骤任务。

本书将 Skill 的学习分为三个阶段：会用（使用篇）→ 用对（实践篇）→ 理解（知识篇）。你可以按顺序阅读，也可以直接用 / 试试手，再回来看原理。

---

使用篇 —— 从会用开始

1. 从使用开始

Qoder 附带了一套内置技能，通过 / 命令触发。在对话输入框中输入 /，Qoder 会自动提示所有可用的 Skill：

命令	功能
/code-review	审查代码变更，输出标准化报告
/create-proposal	创建需求分析设计文档
/create-skill	创建新的自定义 Skill
/create-subagent	创建自定义 SubAgent
/query-sqlite	查询 SQLite 数据库
/test-component	执行组件集成测试

新手期最好的学习方式就是多用这些内置命令。用多了自然就理解 Skill 是什么——它就是把你重复做的工作固化成 AI 可以执行的步骤。

在 Growth AIOS 产品中，Skill 中心集中管理所有已安装的技能包，每个 Skill 以卡片形式展示，包含名称、描述、文件结构和安装时间：

2. Skill 的分类与命名

六大分类

随着团队积累的 Skill 越来越多，需要一套清晰的分类来管理它们。按动词划分，每一类对应一类高频操作场景：

分类	动词	典型 Skill
创建类	create-	create-module、create-api、create-proposal
控制类	start-/stop-/restart-	start-server、deploy-project、run-test
检查类	review-/check-/audit-	code-review、check-style、audit-security
知识类	ask-	ask-architecture、ask-standard、ask-best-practice
生成类	generate-	generate-report、generate-doc、generate-changelog
优化类	optimize-/refactor-	optimize-performance、refactor-module

这六类覆盖了日常开发的全部场景。分类不是为了好看，而是为了降低记忆负担——你不需要记住几十个 Skill 的名字，只需要记住 6 个动词。

命名规范：动词 + 名词

Skill 的命令采用 动词 + 名词 的命名方式。动词在前，名词在后：

不好（模糊）	好（清晰）
database	query-database
module	create-module
security	audit-security

动词在前的好处是前缀自动补全——只要输入动词，Qoder 就会列出所有相关的 Skill：

• 输入 /create → 列出 create-module、create-api、create-proposal……
• 输入 /query → 列出 query-database……
• 输入 /review → 列出 code-review、review-proposal、review-ui……

你不用记住每个 Skill 的全名，只需要记住动词，就能通过自动补全找到需要的那个。发现成本从「记忆」降为了「浏览」。

动词统一表

团队协作时，统一动词能避免同义词造成的混乱（比如「检查」到底用 check 还是 review 还是 audit）：

动词	含义	适合场景
create-	创建新内容	模块、组件、文档、测试用例
query-	查询数据或状态	数据库、配置、日志
start-/stop-/restart-	控制服务启停	服务、Middleware、容器
review-	审查方案/设计	方案文档、UI 设计
check-	检查代码/规范	代码风格、数据库迁移
audit-	安全检查	权限、依赖、漏洞
ask-	查询知识	架构、规范、最佳实践
generate-	批量生成	报告、日志、文档
optimize-	优化改进	性能、体积、重构
deploy-	部署发布	项目、配置

---

实践篇 —— 从会用到用对

3. 创建自己的 Skill

当重复性工作出现三次以上，就值得封装成一个 Skill。

何时创建

不是每个自动化需求都值得创建 Skill。建之前问三个问题：

1. 这个任务每周至少出现一次吗？
2. 步骤是稳定可复现的吗？
3. 有没有现有的 Skill 能覆盖这个场景？

三个都答「是」才创建。

如何创建

Skill 不是手写的，而是让 AI 帮你写。

AI 比你更了解自己的工作方式。你遇到一个重复性任务，AI 已经在对话中帮你处理了多次，它知道完整的执行步骤、需要检查哪些事项、输出应该长什么样。这时候让 AI 自己抽象出自己的 Skill，比你手动写更准确。

有三种方式：

方式一：基于已有代码/规范创建

让 AI 扫描你的项目代码和现有规范，自动提取可复用的模式：

请你分析 src/ 目录下的 Controller 层代码，总结出创建新 Controller 的标准步骤，帮我生成一个 Skill。

AI 会读取实际的代码文件，分析命名模式、参数结构、异常处理方式，然后生成一个完全匹配你项目风格的 Skill 草案。

方式二：基于对话中的最佳实践创建

在多次对话后，AI 已经帮你解决了若干次同一个类型的任务。直接让它总结：

最近我们多次讨论了前端页面的创建流程，请根据之前几次的对话，帮我生成一个 create-page Skill。

AI 会回顾已执行的类似任务，提取共同步骤，生成 Skill。

方式三：提出新约束让 AI 创建

如果你对某个流程有新的想法或约束，直接告诉 AI，它会根据你的描述生成 Skill：

每次创建 API 都需要先写 Proposal 文档，等 Review 通过后再编码。请帮我创建一个 create-api-proposal Skill，包含 Proposal 模板和 Review 检查清单。

AI 会理解你的业务流程，生成完整的 Skill 指令。

---

三种方式的核心都是同一件事：用 AI 生成 → 你审阅 → 继续对话调整 → 满意后固化。不要试图一次写出完美的 Skill，那违反了「让 AI 比你聪明」的前提。

确认满意后，执行一次 /create-skill，AI 会自动填入你刚才审定好的内容。

Skill 目录结构

一个 Skill 存放在 .qoder/skills/ 目录下，每个 Skill 是一个独立目录，目录中必须包含一个 SKILL.md 作为主文件：

.qoder/skills/
├── code-review/          ← 每个 Skill 是一个目录
│   └── SKILL.md          ← 必需：主文件
├── create-proposal/
│   └── SKILL.md
├── qoder-content-write/
│   └── SKILL.md
└── design-ui/            ← 复杂 Skill 可以带数据和脚本
    ├── SKILL.md
    ├── data/
    │   ├── colors.csv
    │   ├── typography.csv
    │   └── stacks/
    │       ├── react.csv
    │       └── vue.csv
    └── scripts/
        ├── core.py
        └── design_system.py

SKILL.md 是唯一必须的文件，其他文件（数据、脚本、参考资料）都是可选的。Skill 的复杂程度取决于它的需求：

类型	结构	适合场景
简单	只有 SKILL.md	写作规范、检查清单
标准	SKILL.md + 详细指令	代码审查、模块创建
复杂	SKILL.md + data/ + scripts/	设计系统、数据分析

SKILL.md 的结构

SKILL.md 是 Skill 的核心，由 YAML 元数据 和 Markdown 指令 两部分组成：

---
name: qoder-content-write
description: 按 使用→实践→知识 三层结构组织 Qoder 入门到精通各章节内容
---
你需要按 Qoder 入门到精通书籍的写作规范，以 **使用 → 实践 → 知识** 三层结构组织章节内容。

## 使用篇 —— 从会用开始

内容清单：
1. **从使用开始** —— 开箱即用的内置功能、基础命令列表
2. **分类体系** —— 如果能力有多种形态，按维度分类展示
3. **命名/操作规范** —— 如果涉及命名约束，解释为什么这样命名

写作要点：
- 多用表格，少用长段落
- 不解释原理，先让人跑起来

元数据只有两个必填字段：

字段	要求	作用
name	小写字母 + 数字 + 连字符，最长 64 字符	Skill 的唯一标识，也是 / 命令的触发名
description	不超过 1024 字符	模型据此判断「何时加载这个 Skill」

name 决定了用户怎么调用它，description 决定了模型怎么找到它。

三个真实案例

案例一：简单 Skill——qoder-content-write

这是本书章节写作用的 Skill，只有一个 SKILL.md，126 行指令，没有外部数据：

qoder-content-write/
└── SKILL.md    ← 126 行指令：三层结构模板 + 配图规范

它的工作方式很简单：当你输入 /qoder-content-write 时，AI 读取这 126 行指令，然后按模板组织章节内容。没有外部依赖，没有脚本执行——纯粹的指令驱动。

案例二：标准 Skill——code-review

Components 项目中的代码审查 Skill，SKILL.md 有 427 行，包含详细的审查清单、输出格式规范和反馈分级策略：

code-review/
└── SKILL.md    ← 427 行：审查流程 + 检查清单 + 输出模板

它的指令更复杂——不只是告诉 AI「审查代码」，而是规定了审查的具体步骤、必须检查的安全项、反馈的格式分级（Critical / Suggestion / Nice to have）。指令越精确，输出越一致。

案例三：复杂 Skill——design-ui

设计系统 Skill，除了 SKILL.md 外，还带了 25 个数据文件和 3 个 Python 脚本：

design-ui/
├── SKILL.md           ← 293 行：设计系统规范 + 脚本调用说明
├── data/
│   ├── colors.csv     ← 颜色数据（97 条记录）
│   ├── typography.csv ← 字体规范（58 条记录）
│   ├── styles.csv     ← 样式系统（68 条记录）
│   └── stacks/        ← 按框架分类的技术栈数据
│       ├── react.csv
│       ├── vue.csv
│       └── ...
└── scripts/
    ├── core.py            ← 核心搜索逻辑
    ├── design_system.py   ← 设计系统数据库
    └── search.py          ← 组件搜索

这种 Skill 的工作方式不同：AI 不仅读取指令，还会执行脚本查询数据。比如当你要设计一个 React 页面时，AI 会运行 scripts/search.py 从 data/stacks/react.csv 中检索匹配的组件。

什么时候需要 data/ 和 scripts/

场景	只需 SKILL.md	需要 data/	需要 scripts/
写作规范/检查清单	✅
代码审查/模块创建	✅
设计系统（查颜色/字体）		✅
数据分析（查询数据库）			✅
自动化生成（批量操作）			✅

经验法则：如果指令中的数据量超过 50 行，考虑提取到 data/ 文件；如果需要查询或计算，考虑写脚本。SKILL.md 应该保持精炼，只写指令和流程。

4. 如何管理 Skill 资产

Skill 很好用，但凡事都有两面。当团队积累了太多 Skill，会遇到三个问题：

问题	表现
上下文膨胀	AGENTS.md 中索引过多，每次对话加载大量无关内容
发现困难	SKill 超过 30 个时，用户能记住的不超过 20 个，大部分无人使用
路由准确率下降	候选越多，模型选错或犹豫的概率越高

健康管理策略

1. 建立准入标准——创建前先问：频率够高吗？步骤稳定吗？有没有重复？

2. 定期健康检查——每季度审视一次：

• 过去三个月使用次数为 0 的 → 标记为废弃
• 步骤引用已过时路径的 → 更新或删除
• 两个 Skill 功能重叠的 → 合并

3. 分类分层索引——不要在 AGENTS.md 里罗列所有 Skill。按分类索引，只在 AGENTS.md 中列大类名：

## 可用 Skill
- 创建类：/create 开头，用于生成新代码和文档
- 控制类：/query /start /stop 开头，用于管理服务
- 检查类：/review /check /audit 开头，用于质量审查

用户通过 /create 自动补全看到具体列表，发现成本从「记忆」降为「浏览」。

---

知识篇 —— 从用对到理解

5. Skill 的运行原理

很多人觉得 Skill 很神奇——敲个命令，AI 就突然像换了一个人，精准地执行一套复杂流程。它背后到底是什么机制？

实际上，Skill 的工作原理可以拆解为四个步骤：

graph LR
    A[第一步：触发<br>输入 /create-module] --> B[第二步：加载<br>读取 Skill 文件到上下文]
    B --> C[第三步：解释<br>大模型理解指令<br>结合项目状态实例化]
    C --> D[第四步：执行<br>调用工具完成任务<br>输出结果]

第一步：触发

当你在输入框中输入 /create-module 并回车，Qoder 根据命令名找到对应的 Skill 文件。

第二步：加载

找到文件后，Qoder 将 Skill 文件的全部内容——包括 YAML 元数据和 markdown 指令——注入到当前对话的上下文窗口中。这是追加到模型已有的系统提示词之后，而非覆盖。

第三步：解释

大模型收到 Skill 指令后，像人类阅读操作手册一样理解这些指令。它会根据当前项目状态（已打开的文件、光标位置、项目结构）来"实例化"Skill 中的通用步骤。

第四步：执行

模型按照理解后的步骤逐一执行，调用工具、读写文件、运行命令，输出最终结果。

为什么这能工作？

关键在于大模型本质上是**「极强的指令跟随器」**。Skill 就是把「你每次都口头交代 AI 做的事」写成了一份结构化的执行手册：

传统的编程：代码 → 编译器 → 机器执行
Skill 的机制：指令文本 → 大模型理解 → 模型执行

Skill 和传统程序最大的区别在于：它不是精确的机器指令，而是带有理解和适应能力的操作指南。传统程序如果出现预期外的输入就会崩溃；但 Skill 中的步骤如果有歧义，大模型会结合上下文自动补全和适配。

举个例子，Skill 里写「创建 Controller 层」，模型会根据项目已有的 Controller 风格（命名空间、基类、路由约定）自动调整，而不会生搬硬套。这种模糊指令 + 智能适配的模式，正是 Skill 既有框架约束又不失灵活性的根本原因。

6. Skill 的触发方式与路由机制

理解了 Skill 的运行原理后，下一个关键问题是：Skill 是怎么被触发的？

两种触发方式

Skill 有两种触发方式：

手动触发（推荐）： 在对话中输入 / 开头加 Skill 名称。这是最直接、最可靠的方式。你输入什么 Skill，AI 就执行什么 Skill，没有歧义。

模型自动路由： AI 根据 AGENTS.md 中的 description 字段自行判断当前任务匹配哪个 Skill，然后主动加载执行。

为什么推荐手动触发

从实践来看，模型自动路由的效果远不如手动触发可靠。原因有几个：

• description 匹配不精确：模型需要通过 description 判断任务类型，但如果你的描述词和 AI 理解的"任务类型"之间存在细微偏差，路由就会失败
• 错别字不宽容：如果 description 中有错别字，或者模型理解任务时用词有细微差异，就无法匹配到正确的 Skill
• 候选越多越容易选错：当项目中有 20+ 个 Skill 时，模型从候选列表中选对的概率明显下降
• 没有反馈机制：路由错了 AI 不会告诉你"我找不到匹配的 Skill"，它可能就直接按通用能力执行了，你根本不知道 Skill 没被触发

我的实践建议

任何时候都优先使用手动触发。 /create-module 就是 /create-module，没有歧义，不需要模型去"猜"。

这不是 Skill 设计的问题，而是大模型工作方式的固有局限：让 AI 在开放候选集中做选择，永远比给它明确的指令更容易出错。

所以我的建议很简单：

记住你想要用的 Skill 的 / 命令，主动输入触发。不要等 AI 自己去"发现"它们。

手动触发还有一个额外的好处：你能清楚地知道 Skill 有没有被加载。输入 /create-module 后，AI 的行文风格会立刻切换——从"通用编码模式"变成"严格按照模块创建流程执行"。这种即时反馈让你对 Skill 的执行状态有完全的控制。

---

写在最后

Skill 是 Qoder 区别于普通 AI 助手的核心能力。它不是"让 AI 帮你写代码"那么简单——Skill 是把团队的工程经验、设计规范、架构约束全部代码化、可执行化。

当你看到一个新成员打开项目，输入 /create-module 就建出了一个完全符合团队标准的模块目录时，你就会理解 Skill 的真正价值：最好的标准，是让人不需要记住标准。

从使用到实践再到理解，你走过的三个阶段正是 Skill 设计的核心理念——渐进式深入。先用起来，再用好，最后理解它为什么这样设计。不必一步到位，慢慢来，每一次使用都会让你对 Skill 多一分理解。

---

Growth AIOS 产品参考

以下为 Growth AIOS 产品中对应的 Skill 管理界面截图：