Skill 深度解析：编写高质量 Skill 🟡

知道 Skill 是什么还不够，如何编写真正有效的 Skill 才是核心。本章通过拆解内置 Skill 案例，总结高质量 Skill 的编写模式。

本章目标

读完本章你将能够：

掌握 Skill 编写的 5 种最佳实践
理解 Skill 与 System Prompt 的关系
分析内置 Skill 的设计模式（以 coding-agent、taskflow 为例）
编写自己的第一个 Skill

一、Skill 的本质：System Prompt 的模块化组件

Skill 文件在 Bootstrap 时被追加到 System Prompt 的末尾。这意味着：

Skill 的优先级低于 Agent 的核心指令（核心指令在 System Prompt 开头）
多个 Skill 会被依次追加，后面的不会覆盖前面的（LLM 整合所有指令）
Skill 过大会消耗 Token 预算，影响其他内容的注入

二、高质量 Skill 的 5 种编写模式

模式 1：场景触发（When-Then 结构）

好的 Skill 明确定义"什么时候触发"，而不是笼统的"总是做 X"：

❌ 不好的写法：
"Always use conventional commits."

✅ 好的写法：
## Commit Messages
When creating a git commit:
- Use conventional commits format: `type(scope): description`
- Types: feat, fix, docs, chore, refactor, test, perf
- Scope is optional but helpful: feat(auth): add OAuth2 support

模式 2：分步骤指导（Numbered Steps）

复杂任务拆分为明确的步骤序列：

## Code Review Mode
When the user says "review this" or "do a code review":
1. Read all mentioned files using read_file
2. Identify issues by category:
   - Bugs (logic errors, null pointer risks)
   - Performance (O(n²) loops, unnecessary computations)
   - Style (naming conventions, line length)
3. Format output as:
   ### Findings
   **Critical**: [only real bugs]
   **Warnings**: [potential issues]
   **Suggestions**: [style & improvement]
4. Always end with "X issues found" summary

模式 3：格式规范（Output Format Specification）

明确指定 AI 输出的格式，保证可预期性：

## Task Status Updates
Always format status updates as:

STATUS: [IN PROGRESS / COMPLETED / BLOCKED] Progress: X/Y items done Current: [what you're doing now] Next: [what comes after]

Only deviate from this format if explicitly asked.

模式 4：防错条款（Guard Clauses）

列出明确不应该做的事，防止 AI 过度发散：

## Scope Limits
When fixing a bug:
- ONLY fix the reported bug
- DO NOT refactor surrounding code unless explicitly asked
- DO NOT add logging or comments unless the issue involves them
- DO NOT update dependencies unless the bug is caused by a dependency

模式 5：工具引导（Tool Usage Guide）

指导 AI 如何使用特定工具：

## File Operations
When reading multiple files:
- Use batch read (read_file multiple times in parallel) rather than one at a time
- Always check if the file exists before editing
- For large files, read the outline first (view_file_outline), then specific sections

When writing files:
- Prefer replace_in_file for small edits
- Only use write_to_file when creating new files or replacing entire content

三、内置 Skill 案例分析

案例 1：`skills/taskflow/SKILL.md`

TaskFlow 是一个任务流程管理 Skill，核心设计：

定义了一套"任务语言"：用户说"新任务"、"推进"、"完成"触发对应行为
规范了存储格式：任务保存到特定的 YAML 文件
指定了汇报格式：任务完成时按固定格式汇报

这类 Skill 实质上为 AI 定义了一个微型工作流引擎，全部用 Markdown 实现。

案例 2：`skills/summarize/SKILL.md`

Summarize Skill 指导 AI 如何生成摘要：

不同内容类型（会议记录、代码、文章）有不同的摘要模板
指定摘要长度（避免 AI 生成过长或过短的摘要）
定义摘要中必须包含的字段（如"关键决定"、"待办事项"）

案例 3：`skills/github/SKILL.md`

GitHub Skill 定义了 Git 和 GitHub 操作规范：

PR 标题和描述模板
Branch 命名约定
Issue 引用格式
CI 失败时的调试步骤

四、Skill 与 Plugin 的比较

维度	Skill（Markdown）	Plugin（TypeScript）
复杂度	低，任何人都能写	高，需要编程知识
能力边界	只能影响 AI 推理行为	可以调用 API、管理状态、修改系统
维护成本	极低	中高
适用场景	工作流规范、输出格式、行为约束	新工具、新渠道、新 Provider

原则：能用 Skill 解决的问题，优先用 Skill，不要过度工程化。

五、实战：编写你的第一个 Skill

假设你想给 AI 添加"使用中文回复"的规范：

<!-- skills/chinese-reply/SKILL.md -->

# 中文回复规范

## 语言规则
始终用中文回复用户消息，除非：
- 用户明确用英文提问
- 用户要求英文回复
- 问题涉及代码示例（代码本身用英文，注释可以中文）

## 格式规范
- 使用中文标点（不是英文逗号和句号）
- 专业术语保留英文原词并附中文解释：如 "Dependency Injection（依赖注入）"
- 代码相关词汇（函数名、变量名）保持英文

## 长度规范
- 简单问题：2-3 句话内回答
- 复杂问题：用标题分组，每节不超过 5 行
- 避免过度解释

将此文件放入 skills/chinese-reply/SKILL.md 并在 Agent 配置中启用：

# config.yaml
agents:
  list:
    - id: main
      skills:
        enabled:
          - chinese-reply
          - coding-agent

关键源码索引

文件	大小	作用
`skills/taskflow/SKILL.md`	-	任务流管理 Skill（设计参考）
`skills/summarize/SKILL.md`	-	摘要生成 Skill
`skills/coding-agent/SKILL.md`	-	编程 Agent Skill
`skills/github/SKILL.md`	-	GitHub 工作流 Skill
`skills/sag/SKILL.md`	-	Skill 创建助手（SAG）

小结

When-Then 结构：明确触发条件，避免 AI 在不适当时刻应用 Skill。
分步骤指导：复杂任务拆为有序步骤，减少 AI 遗漏。
格式规范：明确输出格式，让 AI 行为可预期。
防错条款：列出明确禁止行为，防止 AI 过度发散。
Skill 优先于 Plugin：能用 Markdown 解决的问题，不要用代码。

← Skill 系统 | → 多 Agent 协作