zsp/everything-claude-code
1
0
Fork 0
mirror of https://github.com/affaan-m/everything-claude-code.git synced 2026-06-12 11:13:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(zh-CN): add Chinese translation of SKILL-DEVELOPMENT-GUIDE (#2200)

Browse Source 
* docs(zh-CN): add Chinese translation of SKILL-DEVELOPMENT-GUIDE

Translate the comprehensive Skill Development Guide to Chinese,
enabling Chinese-speaking contributors to learn how to create
effective ECC skills.

* fix(docs): correct all relative links in zh-CN translation

Fix CONTRIBUTING.md link to zh-CN local copy, and skills links
to point to repo-root skills/ directory instead of non-existent
docs/skills/.

---------

Co-authored-by: lege962 <1515808962@qq.com>
Co-authored-by: legeZZZ <277193585+legeZZZ@users.noreply.github.com>
This commit is contained in:
legeZZZ
2026-06-11 13:00:57 +08:00
committed by GitHub
parent 6626e804f9
commit 6da4490c76
1 changed files with 919 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

919
docs/zh-CN/SKILL-DEVELOPMENT-GUIDE.md Normal file
View File

@@ -0,0 +1,919 @@
# Skill 开发指南
一份为 Everything Claude Code (ECC) 创建有效 Skill 的全面指南。
## 目录
- [什么是 Skill？](#什么是-skill)
- [Skill 架构](#skill-架构)
- [创建你的第一个 Skill](#创建你的第一个-skill)
- [Skill 分类](#skill-分类)
- [编写有效的 Skill 内容](#编写有效的-skill-内容)
- [最佳实践](#最佳实践)
- [常见模式](#常见模式)
- [测试你的 Skill](#测试你的-skill)
- [提交你的 Skill](#提交你的-skill)
- [示例集锦](#示例集锦)
---
## 什么是 Skill？
Skill 是 **知识模块**，Claude Code 根据上下文自动加载。它们提供：
- **领域专业知识**：框架模式、语言习惯用法、最佳实践
- **工作流定义**：常见任务的分步流程
- **参考资料**：代码片段、检查清单、决策树
- **上下文注入**：当特定条件满足时激活
与 **Agent**（专业子助手）或 **Command**（用户触发的操作）不同，Skill 是被动知识，Claude Code 在相关时自动引用。
### Skill 何时激活
Skill 在以下情况激活：
- 用户任务与 Skill 的领域匹配
- Claude Code 检测到相关上下文
- 某个命令引用了该 Skill
- 某个 Agent 需要领域知识
### Skill vs Agent vs Command
| 组件 | 用途 | 激活方式 |
|-----------|---------|------------|
| **Skill** | 知识库 | 基于上下文（自动） |
| **Agent** | 任务执行器 | 显式委派 |
| **Command** | 用户操作 | 用户调用（`/command`） |
| **Hook** | 自动化 | 事件触发 |
| **Rule** | 始终生效的指南 | 始终激活 |
---
## Skill 架构
### 文件结构
```
skills/
└── your-skill-name/
├── SKILL.md # 必需：Skill 主定义文件
├── examples/ # 可选：代码示例
│ ├── basic.ts
│ └── advanced.ts
└── references/ # 可选：外部参考
└── links.md
```
### SKILL.md 格式
```markdown
---
name: skill-name
description: 在 Skill 列表中显示的简要描述，用于自动激活匹配
origin: ECC
---
# Skill 标题
简要概述此 Skill 涵盖的内容。
## 何时激活
描述 Claude 应在什么场景下使用此 Skill。
## 核心概念
主要模式和指南。
## 代码示例
\`\`\`typescript
// 实用、经过测试的示例
\`\`\`
## 反模式
用具体示例展示不应该做的事。
## 最佳实践
- 可操作的指南
- 该做的和不该做的
## 相关 Skill
链接到互补的 Skill。
```
### YAML Frontmatter 字段
| 字段 | 必需 | 描述 |
|-------|----------|-------------|
| `name` | 是 | 小写、连字符连接的标识符（如 `react-patterns`） |
| `description` | 是 | 单行描述，用于 Skill 列表和自动激活 |
| `origin` | 否 | 来源标识符（如 `ECC`、`community`、项目名） |
| `tags` | 否 | 分类标签数组 |
| `version` | 否 | Skill 版本号，用于跟踪更新 |
---
## 创建你的第一个 Skill
### 第1步：选择焦点
好的 Skill 是 **聚焦且可操作的**：
| 通过：好的焦点 | 不通过：太宽泛 |
|---------------|--------------|
| `react-hook-patterns` | `react` |
| `postgresql-indexing` | `databases` |
| `pytest-fixtures` | `python-testing` |
| `nextjs-app-router` | `nextjs` |
### 第2步：创建目录
```bash
mkdir -p skills/your-skill-name
```
### 第3步：编写 SKILL.md
以下是一个最小模板：
```markdown
---
name: your-skill-name
description: 简要描述何时使用此 Skill
---
# 你的 Skill 标题
简要概述（1-2句话）。
## 何时激活
- 场景1
- 场景2
- 场景3
## 核心概念
### 概念1
带示例的解释。
### 概念2
带代码的另一种模式。
## 代码示例
\`\`\`typescript
// 实用示例
\`\`\`
## 最佳实践
- 做这个
- 避免那个
## 相关 Skill
- `related-skill-1`
- `related-skill-2`
```
### 第4步：添加内容
编写 Claude 可以 **立即使用** 的内容：
- 通过：可直接复制粘贴的代码示例
- 通过：清晰的决策树
- 通过：用于验证的检查清单
- 不通过：没有示例的模糊解释
- 不通过：没有可操作指导的长篇叙述
---
## Skill 分类
### 语言标准
聚焦于习惯用法、命名约定和语言特定模式。
**示例：** `python-patterns`、`golang-patterns`、`typescript-standards`
```markdown
---
name: python-patterns
description: Python 习惯用法、最佳实践和模式，用于编写清晰、地道的代码。
---
# Python 模式
## 何时激活
- 编写 Python 代码
- 重构 Python 模块
- Python 代码审查
## 核心概念
### 上下文管理器
\`\`\`python
# 始终使用上下文管理器管理资源
with open('file.txt') as f:
content = f.read()
\`\`\`
```
### 框架模式
聚焦于框架特定约定、常见模式和反模式。
**示例：** `django-patterns`、`nextjs-patterns`、`springboot-patterns`
```markdown
---
name: django-patterns
description: Django 模型、视图、URL 和模板的最佳实践。
---
# Django 模式
## 何时激活
- 构建 Django 应用
- 创建模型和视图
- Django URL 配置
```
### 工作流 Skill
定义常见开发任务的分步流程。
**示例：** `tdd-workflow`、`code-review-workflow`、`deployment-checklist`
```markdown
---
name: code-review-workflow
description: 确保质量和安全的系统化代码审查流程。
---
# 代码审查工作流
## 步骤
1. **理解上下文** - 阅读 PR 描述和关联 Issue
2. **检查测试** - 验证测试覆盖率和质量
3. **审查逻辑** - 分析实现的正确性
4. **检查安全** - 查找漏洞
5. **验证风格** - 确保代码遵循约定
```
### 领域知识
特定领域的专业知识（安全、性能等）。
**示例：** `security-review`、`performance-optimization`、`api-design`
```markdown
---
name: api-design
description: REST 和 GraphQL API 设计模式、版本控制和最佳实践。
---
# API 设计模式
## RESTful 约定
| 方法 | 端点 | 用途 |
|--------|----------|---------|
| GET | /resources | 列表全部 |
| GET | /resources/:id | 获取单个 |
| POST | /resources | 创建 |
```
### 工具集成
使用特定工具、库或服务的指导。
**示例：** `supabase-patterns`、`docker-patterns`、`mcp-server-patterns`
---
## 编写有效的 Skill 内容
### 1. 从"何时激活"开始
这一节对于自动激活 **至关重要**。要具体：
```markdown
## 何时激活
- 创建新的 React 组件
- 重构现有组件
- 调试 React 状态问题
- 审查 React 代码的最佳实践
```
### 2. 使用"展示，而非说教"
差：
```markdown
## 错误处理
在异步函数中始终正确处理错误。
```
好：
```markdown
## 错误处理
\`\`\`typescript
async function fetchData(url: string) {
try {
const response = await fetch(url)
if (!response.ok) {
throw new Error(\`HTTP \${response.status}: \${response.statusText}\`)
}
return await response.json()
} catch (error) {
console.error('获取失败:', error)
throw new Error('获取数据失败')
}
}
\`\`\`
### 要点
- 解析前先检查 \`response.ok\`
- 记录错误以便调试
- 重新抛出错时使用用户友好的消息
```
### 3. 包含反模式
展示不应该做什么：
```markdown
## 反模式
### 失败：直接修改状态
\`\`\`typescript
// 绝不要这样做
user.name = 'New Name'
items.push(newItem)
\`\`\`
### 通过：不可变更新
\`\`\`typescript
// 始终这样做
const updatedUser = { ...user, name: 'New Name' }
const updatedItems = [...items, newItem]
\`\`\`
```
### 4. 提供检查清单
检查清单具有可操作性，易于遵循：
```markdown
## 部署前检查清单
- [ ] 所有测试通过
- [ ] 生产代码中无 console.log
- [ ] 环境变量已文档化
- [ ] 无硬编码的密钥
- [ ] 错误处理完整
- [ ] 输入验证到位
```
### 5. 使用决策树
用于复杂决策：
```markdown
## 选择正确方案
\`\`\`
需要获取数据？
├── 单次请求 → 直接使用 fetch
├── 多个独立请求 → Promise.all()
├── 多个依赖请求 → 依次 await
└── 带缓存 → 使用 SWR 或 React Query
\`\`\`
```
---
## 最佳实践
### 应该做
| 实践 | 示例 |
|----------|---------|
| **具体明确** | "对传递给子组件的事件处理函数使用 `useCallback`" |
| **展示示例** | 包含可复制粘贴的代码 |
| **解释为什么** | "不可变性防止了 React 状态中的意外副作用" |
| **链接相关 Skill** | "另见：`react-performance`" |
| **保持聚焦** | 一个 Skill = 一个领域/概念 |
| **使用章节** | 清晰的标题便于快速浏览 |
### 不应该做
| 实践 | 为什么不好 |
|----------|--------------|
| **模糊不清** | "写好代码"——不可操作 |
| **长篇叙述** | 难以解析，代码更好 |
| **覆盖过广** | "Python、Django 和 Flask 模式"——太宽泛 |
| **跳过示例** | 没有实践的理论用处不大 |
| **忽略反模式** | 学会不该做什么也很有价值 |
### 内容指南
1. **长度**：通常 200-500 行，最多 800 行
2. **代码块**：包含语言标识符
3. **标题**：使用 `##` 和 `###` 层级结构
4. **列表**：无序用 `-`，有序用 `1.`
5. **表格**：用于对比和参考
---
## 常见模式
### 模式1：标准 Skill
```markdown
---
name: language-standards
description: [语言]的编码标准和最佳实践。
---
# [语言] 编码标准
## 何时激活
- 编写 [语言] 代码
- 代码审查
- 设置代码检查工具
## 命名约定
| 元素 | 约定 | 示例 |
|---------|------------|---------|
| 变量 | camelCase | userName |
| 常量 | SCREAMING_SNAKE | MAX_RETRY |
| 函数 | camelCase | fetchUser |
| 类 | PascalCase | UserService |
## 代码示例
[包含实用示例]
## 代码检查设置
[包含配置]
## 相关 Skill
- `language-testing`
- `language-security`
```
### 模式2：工作流 Skill
```markdown
---
name: task-workflow
description: [任务]的分步工作流。
---
# [任务] 工作流
## 何时激活
- [触发条件1]
- [触发条件2]
## 前置条件
- [要求1]
- [要求2]
## 步骤
### 步骤1：[名称]
[描述]
\`\`\`bash
[命令]
\`\`\`
### 步骤2：[名称]
[描述]
## 验证
- [ ] [检查1]
- [ ] [检查2]
## 故障排除
| 问题 | 解决方案 |
|---------|----------|
| [问题] | [修复] |
```
### 模式3：参考 Skill
```markdown
---
name: api-reference
description: [API/库]的快速参考。
---
# [API/库] 参考
## 何时激活
- 使用 [API/库]
- 查阅 [API/库] 语法
## 常见操作
### 操作1
\`\`\`typescript
// 基本用法
\`\`\`
### 操作2
\`\`\`typescript
// 高级用法
\`\`\`
## 配置
[包含配置示例]
## 错误处理
[包含错误模式]
```
---
## 测试你的 Skill
### 本地测试
1. **复制到 Claude Code skills 目录**：
```bash
cp -r skills/your-skill-name ~/.claude/skills/
```
2. **用 Claude Code 测试**：
```
你："我需要 [应该触发你的 Skill 的任务]"
Claude 应该引用你的 Skill 的模式。
```
3. **验证激活**：
- 让 Claude 解释你的 Skill 中的一个概念
- 检查它是否使用了你的示例和模式
- 确保它遵循了你的指南
### 验证检查清单
- [ ] **YAML frontmatter 有效** - 无语法错误
- [ ] **名称遵循约定** - 小写字母加连字符
- [ ] **描述清晰** - 告诉何时使用
- [ ] **示例有效** - 代码可以编译和运行
- [ ] **链接有效** - 相关 Skill 存在
- [ ] **无敏感数据** - 无 API 密钥、令牌、路径
### 代码示例测试
测试所有代码示例：
```bash
# 从仓库根目录
npx tsc --noEmit skills/your-skill-name/examples/*.ts
# 或从 Skill 目录内部
npx tsc --noEmit examples/*.ts
# 从仓库根目录
python -m py_compile skills/your-skill-name/examples/*.py
# 或从 Skill 目录内部
python -m py_compile examples/*.py
# 从仓库根目录
go build ./skills/your-skill-name/examples/...
# 或从 Skill 目录内部
go build ./examples/...
```
---
## 提交你的 Skill
### 1. Fork 并 Clone
```bash
gh repo fork affaan-m/everything-claude-code --clone
cd everything-claude-code
```
### 2. 创建分支
```bash
git checkout -b feat/skill-your-skill-name
```
### 3. 添加你的 Skill
```bash
mkdir -p skills/your-skill-name
# 创建 SKILL.md
```
### 4. 验证
```bash
# 检查 YAML frontmatter
head -10 skills/your-skill-name/SKILL.md
# 验证结构
ls -la skills/your-skill-name/
# 如果有测试，运行测试
npm test
```
### 5. 提交并推送
```bash
git add skills/your-skill-name/
git commit -m "feat(skills): add your-skill-name skill"
git push -u origin feat/skill-your-skill-name
```
### 6. 创建 Pull Request
使用此 PR 模板：
```markdown
## Summary
简要描述 Skill 及其价值。
## Skill Type
- [ ] 语言标准
- [ ] 框架模式
- [ ] 工作流
- [ ] 领域知识
- [ ] 工具集成
## Testing
我是如何在本地测试此 Skill 的。
## Checklist
- [ ] YAML frontmatter 有效
- [ ] 代码示例已测试
- [ ] 遵循 Skill 编写指南
- [ ] 无敏感数据
- [ ] 激活触发器清晰
```
---
## 示例集锦
### 示例1：语言标准
**文件：** `skills/rust-patterns/SKILL.md`
```markdown
---
name: rust-patterns
description: Rust 习惯用法、所有权模式和最佳实践，用于编写安全、地道的代码。
origin: ECC
---
# Rust 模式
## 何时激活
- 编写 Rust 代码
- 处理所有权和借用
- 使用 Result/Option 进行错误处理
- 实现 trait
## 所有权模式
### 借用规则
\`\`\`rust
// 通过：正确：当不需要所有权时使用借用
fn process_data(data: &str) -> usize {
data.len()
}
// 通过：正确：当需要修改或消耗时获取所有权
fn consume_data(data: Vec<u8>) -> String {
String::from_utf8(data).unwrap()
}
\`\`\`
## 错误处理
### Result 模式
\`\`\`rust
use thiserror::Error;
#[derive(Error, Debug)]
pub enum AppError {
#[error("IO 错误: {0}")]
Io(#[from] std::io::Error),
#[error("解析错误: {0}")]
Parse(#[from] std::num::ParseIntError),
}
pub type AppResult<T> = Result<T, AppError>;
\`\`\`
## 相关 Skill
- `rust-testing`
- `rust-security`
```
### 示例2：框架模式
**文件：** `skills/fastapi-patterns/SKILL.md`
```markdown
---
name: fastapi-patterns
description: FastAPI 路由、依赖注入、验证和异步操作的模式。
origin: ECC
---
# FastAPI 模式
## 何时激活
- 构建 FastAPI 应用
- 创建 API 端点
- 实现依赖注入
- 处理异步数据库操作
## 项目结构
\`\`\`
app/
├── main.py # FastAPI 应用入口
├── routers/ # 路由处理器
│ ├── users.py
│ └── items.py
├── models/ # Pydantic 模型
│ ├── user.py
│ └── item.py
├── services/ # 业务逻辑
│ └── user_service.py
└── dependencies.py # 共享依赖
\`\`\`
## 依赖注入
\`\`\`python
from fastapi import Depends
from sqlalchemy.ext.asyncio import AsyncSession
async def get_db() -> AsyncSession:
async with AsyncSessionLocal() as session:
yield session
@router.get("/users/{user_id}")
async def get_user(
user_id: int,
db: AsyncSession = Depends(get_db)
):
# 使用 db session
pass
\`\`\`
## 相关 Skill
- `python-patterns`
- `pydantic-validation`
```
### 示例3：工作流 Skill
**文件：** `skills/refactoring-workflow/SKILL.md`
```markdown
---
name: refactoring-workflow
description: 在不改变行为的前提下改善代码质量的系统化重构工作流。
origin: ECC
---
# 重构工作流
## 何时激活
- 改善代码结构
- 减少技术债务
- 简化复杂代码
- 提取可复用组件
## 前置条件
- 所有测试通过
- Git 工作目录干净
- 已创建功能分支
## 工作流步骤
### 步骤1：确定重构目标
- 查找代码坏味道（长方法、重复代码、大类）
- 检查目标区域的测试覆盖率
- 记录当前行为
### 步骤2：确保测试存在
\`\`\`bash
# 运行测试验证当前行为
npm test
# 检查目标文件的覆盖率
npm run test:coverage
\`\`\`
### 步骤3：小步修改
- 一次只做一项重构
- 每次修改后运行测试
- 频繁提交
### 步骤4：验证行为未变
\`\`\`bash
# 运行完整测试套件
npm test
# 运行 E2E 测试
npm run test:e2e
\`\`\`
## 常见重构
| 坏味道 | 重构方法 |
|-------|-------------|
| 长方法 | 提取方法 |
| 重复代码 | 提取为共享函数 |
| 大类 | 提取类 |
| 长参数列表 | 引入参数对象 |
## 检查清单
- [ ] 目标代码有测试覆盖
- [ ] 进行了小步、聚焦的修改
- [ ] 每次修改后测试通过
- [ ] 行为未改变
- [ ] 使用清晰的消息提交
```
---
## 其他资源
- [CONTRIBUTING.md](CONTRIBUTING.md) - 通用贡献指南
- [project-guidelines-template](../examples/project-guidelines-template.md) - 项目专属 Skill 模板
- [coding-standards](../../skills/coding-standards/SKILL.md) - 标准 Skill 示例
- [tdd-workflow](../../skills/tdd-workflow/SKILL.md) - 工作流 Skill 示例
- [security-review](../../skills/security-review/SKILL.md) - 领域知识 Skill 示例
---
**记住**：好的 Skill 是聚焦的、可操作的、立即可用的。写你自己也想用的 Skill。