第 8 课：Skills（上）— 结构与本质

所属阶段：第二阶段「组件精讲」（第 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 结构总览

markdown 复制代码

---
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。

markdown 复制代码

## 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（工作原理）

核心知识内容。与传统文档不同，这里不需要从基础概念讲起，直接给出可操作的指导。

markdown 复制代码

## 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（示例）

示例必须满足两个条件：

可直接复制粘贴 --- 不是教学用的伪代码
展示对比 --- 同时给出好的和差的做法

markdown 复制代码

## 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 段就是针对这些已知陷阱的"疫苗"。

markdown 复制代码

## 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 三个字段

yaml 复制代码

---
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 的流程：

markdown 复制代码

用户发出请求
    │
    ▼
系统扫描所有 Skill 的 description
    │
    ▼
匹配度最高的 Skill 被加载到上下文
    │
    ▼
AI 按照 Skill 内容执行

description 就是 Skill 的"搜索关键词"。如果 description 写得不好：

问题	表现	后果
太泛	"帮助写出更好的代码"	几乎所有场景都匹配 → 噪音
太窄	"React 18 useEffect cleanup in StrictMode"	极少场景匹配 → 被埋没
不精确	"代码审查"	和 code-reviewer Agent 冲突

好的 description 示例：

yaml 复制代码

# 好：精确描述覆盖范围，包含关键词
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 两者的关系

javascript 复制代码

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 行，通常说明它试图覆盖太多内容。正确做法：

objectivec 复制代码

# 差：一个 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，对比它们的结构：

bash 复制代码

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 感受一下内容深度。