所属阶段：第二阶段「组件精讲」（第 4-14 课） 前置条件：第 7 课 本课收获：掌握 Skill 标准结构，理解 Skill 与传统文档的本质差异
一、本课概述
Agent 是执行者，Skill 是知识库。Agent 告诉 AI "做什么"，Skill 告诉 AI "怎么做"。
本课回答三个问题：
- Skill 的本质是什么？ — 不是文档，是 AI 可执行的知识模块
- Skill 的标准结构是什么？ — 四段式：When to Use、How It Works、Examples、Anti-Patterns
- Skill 放在哪里？ — 仓库内精选 vs 用户目录生成，两个位置有本质区别
二、Skill 的本质：给 AI 执行的知识
2.1 传统文档 vs Skill
很多人第一次看 Skill 文件会觉得"这不就是文档吗？"。表面上看确实像文档，但设计目标完全不同。
| 对比维度 | 传统文档 | ECC Skill |
|---|---|---|
| 受众 | 人类开发者 | AI 编程助手 |
| 风格 | 解释性、循序渐进 | 指令性、条件触发 |
| 触发方式 | 人主动查阅 | 系统根据 description 自动匹配加载 |
| 效果 | 人读完后理解概念 | AI 加载后直接按流程执行 |
| 长度 | 可以很长（教程） | 严格控制（<500 行，800 行上限） |
| 示例 | 教学目的，可以简化 | 必须可复制粘贴，能直接使用 |
| 反模式 | 可选 | 必须有 — 防止 AI 犯已知错误 |
2.2 一个关键洞察
传统文档写给不知道答案的人，帮助他们理解。
Skill 写给已经有能力但缺少上下文的 AI，帮助它在特定场景下做出正确决策。
类比：
- 传统文档 = 教科书（从零教起）
- Skill = 飞行检查清单（飞行员已经会开飞机，清单确保不遗漏关键步骤）
2.3 为什么 AI 需要 Skill
大语言模型有训练数据，已经"知道"很多编程知识。但它有三个固有缺陷：
- 知识截止 — 训练数据有截止日期，不知道最新的最佳实践
- 无项目上下文 — 不知道你团队的编码规范和架构约定
- 无优先级 — 知道 100 种做法，但不知道在当前场景下哪种最合适
Skill 解决的就是这三个问题：提供最新实践、注入项目上下文、建立优先级。
三、Skill 标准四段式结构
3.1 结构总览
---
name: your-skill-name
description: 一句话描述，系统自动发现和加载的唯一依据
origin: ECC
---
# 标题
简短概述。
## When to Activate（触发条件）
描述何时应该使用此 Skill。
## Core Concepts / How It Works（工作原理）
核心概念和工作流。
## Code Examples（示例）
可直接使用的代码示例。
## Anti-Patterns（常见错误）
展示不应该怎么做。
3.2 各段详解
第一段：When to Activate（触发条件）
这是 Skill 与传统文档最大的区别。传统文档没有"触发条件"这个概念 — 人自己决定什么时候看。
Skill 的触发条件告诉系统在什么场景下自动加载这个 Skill。
## When to Activate
- Starting a new project or module
- Reviewing code for quality and maintainability
- Refactoring existing code to follow conventions
- Setting up linting, formatting, or type-checking rules
设计要点：
- 用动词开头（Starting、Reviewing、Refactoring）
- 描述场景，不是描述 Skill 内容
- 既不能太宽（所有场景都触发 = 噪音），也不能太窄（没有场景触发 = 废物）
第二段：How It Works（工作原理）
核心知识内容。与传统文档不同，这里不需要从基础概念讲起，直接给出可操作的指导。
## Code Quality Principles
### 1. Readability First
- Code is read more than written
- Clear variable and function names
- Self-documenting code preferred over comments
### 2. KISS (Keep It Simple, Stupid)
- Simplest solution that works
- Avoid over-engineering
第三段：Examples（示例）
示例必须满足两个条件：
- 可直接复制粘贴 — 不是教学用的伪代码
- 展示对比 — 同时给出好的和差的做法
## Code Examples
// BAD: Deep nesting + mutation
function processUsers(users) {
if (users) {
for (const user of users) {
if (user.active) {
user.verified = true; // mutation!
}
}
}
}
// GOOD: Early returns + immutability
function processUsers(users) {
if (!users) return [];
return users
.filter(user => user.active)
.map(user => ({ ...user, verified: true }));
}
第四段：Anti-Patterns（常见错误）
这是 Skill 的防御层。AI 模型会犯一些反复出现的错误，Anti-Patterns 段就是针对这些已知陷阱的"疫苗"。
## Anti-Patterns
- Testing implementation details instead of behavior
- Tests depending on each other (shared state)
- Asserting too little (passing tests that don't verify anything)
- Not mocking external dependencies
四、frontmatter 字段详解
4.1 三个字段
---
name: coding-standards
description: Baseline cross-project coding conventions for naming,
readability, immutability, and code-quality review.
origin: ECC
---
| 字段 | 作用 | 注意事项 |
|---|---|---|
| name | Skill 的唯一标识 | 小写加连字符，与目录名一致 |
| description | 系统自动发现和加载的唯一依据 | 最关键的一行 |
| origin | 来源标记 | ECC 表示官方精选 |
4.2 description 字段的重要性
description 是整个 Skill 中最关键的一行。 为什么？
系统加载 Skill 的流程：
用户发出请求
│
▼
系统扫描所有 Skill 的 description
│
▼
匹配度最高的 Skill 被加载到上下文
│
▼
AI 按照 Skill 内容执行
description 就是 Skill 的"搜索关键词"。如果 description 写得不好：
| 问题 | 表现 | 后果 |
|---|---|---|
| 太泛 | "帮助写出更好的代码" | 几乎所有场景都匹配 → 噪音 |
| 太窄 | "React 18 useEffect cleanup in StrictMode" | 极少场景匹配 → 被埋没 |
| 不精确 | "代码审查" | 和 code-reviewer Agent 冲突 |
好的 description 示例：
# 好：精确描述覆盖范围，包含关键词
description: Baseline cross-project coding conventions for naming,
readability, immutability, and code-quality review. Use detailed
frontend or backend skills for framework-specific patterns.
# 好：明确说明不做什么，减少误触发
description: Test-Driven Development workflow enforcing RED-GREEN-REFACTOR
cycle. Not for test debugging — use tdd-troubleshooting instead.
五、Skill 放置策略
5.1 两个放置位置
ECC 的 Skill 有两个放置位置，它们的性质完全不同：
| 位置 | 路径 | 性质 | 来源 |
|---|---|---|---|
| 仓库内精选 | skills/ | 经过审查的高质量 Skill | 社区贡献 + 维护者审核 |
| 用户目录 | ~/.claude/skills/ | 个人/团队 Skill | 自动生成或手动导入 |
5.2 两者的关系
skills/ ~/.claude/skills/
（仓库内，版本控制） （用户目录，个人使用）
┌──────────────┐ ┌──────────────┐
│ 精选 Skill │ 手动复制 │ 个人 Skill │
│ 社区审核 │ ──────────→ │ 项目特定 │
│ PR 合并流程 │ │ 自动生成 │
└──────────────┘ └──────────────┘
不自动同步！
关键点：两个目录不自动同步。如果你在 skills/ 中更新了一个 Skill，~/.claude/skills/ 中的旧版本不会自动更新。
5.3 什么放哪里
| 场景 | 放置位置 | 原因 |
|---|---|---|
| 通用最佳实践（如 TDD 工作流） | skills/ | 社区共享，需要审核质量 |
| 团队特定编码规范 | ~/.claude/skills/ | 项目相关，不需要社区审核 |
/learn 命令自动提取的模式 | ~/.claude/skills/ | 自动生成，个人使用 |
/skill-create 从 git 历史生成的 | ~/.claude/skills/ | 项目特定知识 |
六、质量清单
根据 CONTRIBUTING.md 的要求，一个合格的 Skill 必须满足以下条件：
6.1 必须满足
- 聚焦单一领域 — 一个 Skill 解决一类问题，不要大杂烩
- description 精确 — 能被正确触发，不误触发
- 有 "When to Activate" 段 — 明确触发场景
- 有实际可用的代码示例 — 可复制粘贴
- 有 Anti-Patterns — 展示不该怎么做
- <500 行（800 行绝对上限）
- 无敏感信息 — 没有 API Key、私有路径
6.2 加分项
- 引用相关 Skill（
Related Skills段） - 说明与哪些 Agent 配合使用
- 说明 Skill 的边界（什么不在范围内）
6.3 Skill 过长怎么办
如果一个 Skill 超过 500 行，通常说明它试图覆盖太多内容。正确做法：
# 差：一个 1200 行的 "fullstack-patterns" Skill
# 好：拆成三个独立 Skill
frontend-patterns/SKILL.md (300 行)
backend-patterns/SKILL.md (350 行)
api-design/SKILL.md (250 行)
七、本课练习
练习 1：阅读 3 个 Skill，提取共性（15 分钟）
分别打开以下三个 Skill，对比它们的结构：
cat skills/coding-standards/SKILL.md
cat skills/tdd-workflow/SKILL.md
cat skills/security-review/SKILL.md
回答问题：
- 三个 Skill 都有哪些共同段落？
- description 字段的写法有什么共同特点？
- Anti-Patterns 段的内容风格是什么？（提示：都是"不要做 X"的负面指令）
练习 2：评价 description 质量（10 分钟）
判断以下 description 的质量（好/差/需改进），并说明理由：
description: "帮助开发者写出更好的代码"description: "Django ORM query optimization patterns including select_related, prefetch_related, and annotate for N+1 prevention"description: "代码"description: "Baseline cross-project coding conventions for naming, readability, immutability, and code-quality review. Use detailed frontend or backend skills for framework-specific patterns."
练习 3：设计 Skill 的 description（10 分钟）
为以下假想 Skill 各写一个 description（1-2 句话）：
- 一个关于 PostgreSQL 索引优化的 Skill
- 一个关于 React Server Components 的 Skill
- 一个关于 Git rebase 工作流的 Skill
练习 4（选做）：Skill vs Agent 边界思考
假设你要提升团队的代码审查质量。应该写一个 Skill 还是创建一个 Agent？为什么？
提示：如果需要执行动作（读 git diff、搜索代码）→ Agent。如果只需要提供知识（审查清单、最佳实践）→ Skill。实际上 ECC 两者都有：code-reviewer Agent 加载 coding-standards Skill。
八、本课小结
| 你应该记住的 | 内容 |
|---|---|
| Skill 的本质 | 给 AI 执行的知识模块，不是给人看的文档 |
| 四段式结构 | When to Activate → How It Works → Examples → Anti-Patterns |
| description | 整个 Skill 最关键的一行，决定能否被正确触发 |
| 放置位置 | skills/（精选）vs ~/.claude/skills/（个人），不自动同步 |
| 质量标准 | 聚焦单一领域、<500 行、有示例、有反模式 |
九、下节预告
第 9 课：Skills（下）— 编程 Skill 地图与编写实战
下节课我们将纵览 ECC 全部 286 个 Skill 中与编程/架构相关的 85 个 Skill 的分布地图，然后动手编写一个完整的 Skill。你将了解从核心开发到前端、后端、测试、DevOps、AI/Agent 的完整技能覆盖。
预习建议：浏览 skills/ 目录，数一下有多少个子目录。随机打开 3-5 个 Skill 感受一下内容深度。
