第 9 课：Skills（下）— 编程 Skill 地图与编写实战

所属阶段：第二阶段「组件精讲」（第 4-14 课）前置条件：第 8 课本课收获：了解 85 个编程 Skill 的分布地图，能编写一个 Skill

一、本课概述

上节课我们学习了 Skill 的本质和结构。本课有两个目标：

建立全局视野 --- 了解 ECC 中 85 个编程/架构相关 Skill 的分布地图
动手编写 --- 从零编写一个符合标准的 Skill

ECC 总共有 286 个 Skill，但其中约 97 个属于业务/营销/医疗/金融等非编程领域（如 brand-voice、market-research、customer-billing-ops），不在本课程范围内。我们聚焦与软件开发直接相关的 85 个编程 Skill。

二、编程 Skill 分布地图

2.1 总览表

以下是 ECC 中与编程/架构直接相关的 Skill 分布：

类别	数量	代表性 Skill
核心开发	10	coding-standards, api-design, backend-patterns, frontend-patterns, frontend-design, design-system, database-migrations, architecture-decision-records, codebase-onboarding, blueprint
Python	2	python-patterns, python-testing
Go	2	golang-patterns, golang-testing
Java/Kotlin	8	jpa-patterns, springboot-patterns, springboot-security, springboot-tdd, springboot-verification, android-clean-architecture, compose-multiplatform-patterns, kotlin-multiplatform
PHP/Laravel	4	laravel-patterns, laravel-security, laravel-testing, php-patterns
C++/Rust	4	cpp-coding-standards, cpp-testing, rust-patterns, rust-testing
Swift/Dart	6	swift-concurrency-6-2, swift-actor-persistence, swift-protocol-di-testing, swiftui-patterns, dart-flutter-patterns, flutter-dart-code-review
C#/.NET	2	dotnet-patterns, csharp-testing
Django	4	django-patterns, django-security, django-tdd, django-verification
Spring Boot	4	（已计入 Java/Kotlin 类别）
数据库	4	database-migrations, clickhouse-io, supabase-patterns, prisma-patterns
前端	4	frontend-patterns, frontend-design, design-system, liquid-glass-design
测试	7	tdd-workflow, e2e-testing, verification-loop, ai-regression-testing, benchmark, browser-qa, eval-harness
DevOps	4	docker-patterns, deployment-patterns, github-actions-patterns, terraform-patterns
AI/Agent	11	agent-eval, agent-harness-construction, agent-introspection-debugging, agentic-engineering, ai-first-engineering, autonomous-agent-harness, autonomous-loops, claude-api, claude-devfleet, cost-aware-llm-pipeline, continuous-learning-v2
工具集成	3	documentation-lookup, exa-search, search-first

2.2 分类说明

核心开发（10 个） ：与语言无关的编程基础，适用于所有项目。coding-standards 是最基础的 Skill，几乎每个会话都会被加载。

语言特定（28 个） ：每种语言通常有 xxx-patterns（编码模式）和 xxx-testing（测试策略）两个 Skill。Java/Kotlin 生态最丰富，有 8 个。

框架特定（8 个）：Django 和 Spring Boot 各 4 个，覆盖模式、安全、TDD、验证。

测试（7 个）：从单元测试（tdd-workflow）到端到端测试（e2e-testing）到 AI 回归测试（ai-regression-testing）的完整覆盖。

AI/Agent（11 个）：这是 ECC 的特色领域 --- 如何构建、评估、调试 AI Agent。这些 Skill 在其他工具中找不到。

2.3 跳过的 Skill 说明

以下类别的 Skill 不在本课程范围内（但它们确实存在于 ECC 中）：

类别	数量	示例
业务运营	~20	customer-billing-ops, finance-billing-ops, automation-audit-ops
内容营销	~15	brand-voice, content-engine, article-writing, crosspost
行业垂直	~10	customs-trade-compliance, carrier-relationship-management, energy-procurement
签证/翻译	~5	visa-doc-translate
投资者关系	~5	investor-materials, market-research
其他非编程	~42	各类业务和领域 Skill

这些 Skill 的存在说明 ECC 的定位不仅仅是"代码工具"，而是一个通用的 AI 工作增强框架。但本课程聚焦编程部分。

三、Skill 之间的关系

3.1 层级关系

Skill 之间存在明确的层级和引用关系：

arduino 复制代码

coding-standards（基础层，通用编码规范）
    │
    ├── frontend-patterns（前端框架模式）
    │       └── design-system（UI 组件设计）
    │
    ├── backend-patterns（后端架构模式）
    │       ├── api-design（API 设计）
    │       └── database-migrations（数据库迁移）
    │
    └── tdd-workflow（测试驱动开发）
            ├── e2e-testing（端到端测试）
            └── verification-loop（验证循环）

好的 Skill 会在末尾标注相关 Skill，帮助系统建立关联：

markdown 复制代码

## Related Skills

Link to complementary skills:
- `frontend-patterns` for React and Next.js best practices
- `backend-patterns` for API and database patterns
- `security-review` for security checklist

3.3 Skill 与 Agent 的配合

一些 Agent 会在执行过程中参考特定 Skill：

Agent	参考的 Skill
code-reviewer	coding-standards, security-review
tdd-guide	tdd-workflow
planner	architecture-decision-records

这种 Agent + Skill 的组合模式是 ECC 的核心设计：Agent 提供执行能力，Skill 提供领域知识。

四、Skill 编写实战

4.1 编写步骤

vbnet 复制代码

Step 1: 确定领域和范围
    │ 这个 Skill 解决什么问题？边界在哪？
    │
Step 2: 编写 description
    │ 最关键的一行，决定触发时机
    │
Step 3: 编写 When to Activate
    │ 列出 5-8 个具体触发场景
    │
Step 4: 编写核心内容
    │ 原理、规则、工作流
    │
Step 5: 编写示例
    │ 好的做法 + 差的做法对比
    │
Step 6: 编写 Anti-Patterns
    │ 列出 AI 容易犯的错误
    │
Step 7: 质量检查
    │ 对照清单逐项确认

4.2 完整模板

markdown 复制代码

---
name: your-skill-name
description: 精确描述覆盖范围和关键词，1-2 句话
origin: ECC
---

# Skill 标题

一段话概述：这个 Skill 做什么、适用于什么场景、不适用于什么场景。

## When to Activate

- 场景 1（用动词开头）
- 场景 2
- 场景 3
- 场景 4
- 场景 5

## Scope Boundaries

Activate this skill for:
- 范围内的事项 1
- 范围内的事项 2

Do not use this skill for:
- 超出范围的事项 1（建议使用 xxx-skill）
- 超出范围的事项 2

## Core Concepts

### 1. 概念一
要点说明。

### 2. 概念二
要点说明。

## Code Examples

### Example: [场景名]

```language
// BAD: 说明为什么这样做是错的
badCode();

// GOOD: 说明为什么这样做是对的
goodCode();

Anti-Patterns

Anti-Pattern	问题	正确做法
做法 A	会导致 X	改为做法 B
做法 C	会导致 Y	改为做法 D

Best Practices

最佳实践 1
最佳实践 2
最佳实践 3

related-skill-1 for 补充内容 1
related-skill-2 for 补充内容 2

markdown 复制代码

### 4.3 编写示例：Git Rebase 工作流 Skill

下面展示一个从零开始的完整编写过程：

**Step 1：确定领域** --- Git rebase 工作流，包括交互式 rebase、冲突解决、团队协作规范。

**Step 2：编写 description**：

```yaml
description: Git rebase workflow patterns including interactive rebase,
  conflict resolution, and team branching conventions. Use git-workflow
  rules for commit message format.

Step 3-6：完整内容：

markdown 复制代码

---
name: git-rebase-workflow
description: Git rebase workflow patterns including interactive rebase,
  conflict resolution, and team branching conventions. Use git-workflow
  rules for commit message format.
origin: custom
---

# Git Rebase Workflow

Patterns for keeping a clean git history using rebase instead of merge.

## When to Activate

- Updating a feature branch with latest main changes
- Cleaning up commit history before PR review
- Squashing WIP commits into meaningful units
- Resolving merge conflicts during rebase
- Setting up team branching strategy

## Scope Boundaries

Do not use for:
- Commit message formatting (see rules/common/git-workflow.md)
- CI/CD pipeline configuration (see github-actions-patterns)

## Core Concepts

### 1. Rebase vs Merge
- Rebase: rewrites history for linear commits
- Merge: preserves branch structure with merge commits
- Rule: rebase for local cleanup, merge for shared branches

### 2. Golden Rule
NEVER rebase commits that have been pushed to a shared branch.

## Anti-Patterns

| Anti-Pattern | Problem | Correct Approach |
|-------------|---------|-----------------|
| Rebase after push to shared branch | Rewrites shared history | Only rebase local commits |
| Force push to main | Destroys team history | Use --force-with-lease on feature branches only |
| Rebase with 50+ commits | Hard to resolve conflicts | Rebase frequently in smaller batches |

## Related Skills

- `coding-standards` for code quality during conflict resolution
- `tdd-workflow` for ensuring tests pass after rebase

五、description 调优技巧

5.1 三个层次

arduino 复制代码

差：  "代码质量"
      → 太泛，几乎匹配所有场景

中：  "TypeScript 代码质量最佳实践"
      → 还是偏泛，没有具体关键词

好：  "Baseline cross-project coding conventions for naming,
       readability, immutability, and code-quality review.
       Use detailed frontend or backend skills for
       framework-specific patterns."
      → 包含关键词、说明范围、指向相关 Skill

5.2 description 检查清单

包含领域关键词（让系统能匹配）
说明覆盖范围（让系统知道适用场景）
如有必要，排除不覆盖的场景（减少误触发）
1-2 句话（太长系统难以快速匹配）
英文优先（系统匹配基于英文）

六、本课练习

练习 1：浏览 Skill 地图（10 分钟）

浏览 skills/ 目录，回答以下问题：

bash 复制代码

ls skills/ | head -30

你的主要编程语言对应的 Skill 有哪些？
有没有你意想不到的 Skill 类别？
AI/Agent 类 Skill 有哪些？

练习 2：分析一个 Skill 的质量（15 分钟）

选择一个与你工作相关的 Skill（如 python-patterns、golang-patterns、springboot-patterns），对照第八课的质量清单逐项检查：

description 是否精确？
有没有 When to Activate？
示例是否可直接使用？
有没有 Anti-Patterns？
行数是否 <500？

练习 3：编写一个 Skill 草稿（30 分钟）

这是本课最重要的练习。

为你团队的编码规范或常用架构模式编写一个 Skill 草稿。要求：

使用第四节中的完整模板
description 精确（参考 5.2 检查清单）
至少 3 个触发场景
至少 1 个代码示例（好/差对比）
至少 3 个 Anti-Patterns
控制在 200-400 行

建议选题：

团队的 API 设计规范
团队的状态管理模式（Redux/Zustand/Pinia）
团队的错误处理规范
团队的数据库查询规范

练习 4（选做）：Skill 放置决策

你写好的 Skill 应该放在 skills/ 还是 ~/.claude/skills/？判断依据是什么？

七、本课小结

你应该记住的	内容
编程 Skill 分布	85 个编程相关，核心开发 10、语言特定 28、框架 8、测试 7、AI/Agent 11
跳过的 Skill	~97 个业务/营销/行业 Skill 不在课程范围
Skill 之间的关系	有层级（基础 → 具体），Agent + Skill 组合使用
编写步骤	确定领域 → description → When to Activate → 核心内容 → 示例 → Anti-Patterns
description 调优	包含关键词、说明范围、排除非覆盖场景

八、下节预告

第 10 课：Hooks --- 事件驱动自动化

下节课我们进入 ECC 最"魔法"的组件 --- Hooks。你将学到 7 种 Hook 事件类型，理解为什么只有 PreToolUse 能拦截操作（这是最常见的误区），并学会配置自定义 Hook。

预习建议 ：打开 hooks/hooks.json，大致浏览一下配置格式，不需要理解每一行，感受一下 Hook 的规模。

第 9 课：Skills（下）— 编程 Skill 地图与编写实战

一、本课概述

二、编程 Skill 分布地图

2.1 总览表

2.2 分类说明

2.3 跳过的 Skill 说明

三、Skill 之间的关系

3.1 层级关系

3.2 Related Skills 引用

3.3 Skill 与 Agent 的配合

四、Skill 编写实战

4.1 编写步骤

4.2 完整模板

Anti-Patterns

Best Practices

Related Skills

五、description 调优技巧

5.1 三个层次

5.2 description 检查清单

六、本课练习

练习 1：浏览 Skill 地图（10 分钟）

练习 2：分析一个 Skill 的质量（15 分钟）

练习 3：编写一个 Skill 草稿（30 分钟）

练习 4（选做）：Skill 放置决策

七、本课小结

八、下节预告