The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs(zh-CN): add Chinese translation of SKILL-DEVELOPMENT-GUIDE (#2200)
legeZZZ6da4490c76d3
diff --git a/docs/zh-CN/SKILL-DEVELOPMENT-GUIDE.md b/docs/zh-CN/SKILL-DEVELOPMENT-GUIDE.mdnew file mode 100644index 000000000..db79e1f96--- /dev/null+++ b/docs/zh-CN/SKILL-DEVELOPMENT-GUIDE.md@@ -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+[email protected]("/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。