# 技能结构指南

## 什么是技能？

技能是专门的教学文档，指导AI助手（如Claude Code、Gemini、Cursor）如何完美执行特定任务。

每个技能都是一个自包含的markdown文件，包含AI理解上下文所需的所有必要信息、分步指导和相关代码示例。

---

## 技能文件结构

### 目录结构

```
skills/
├── skill-name/                    # 技能目录
│   ├── SKILL.md                  # 主要技能文件（必需）
│   ├── examples/                  # 示例目录（可选）
│   │   ├── basic-usage.md        # 基础使用示例
│   │   └── advanced-scenarios.md  # 高级场景示例
│   ├── resources/                 # 资源目录（可选）
│   │   ├── templates/            # 代码模板
│   │   ├── checklists/           # 检查清单
│   │   └── references/          # 参考资料
│   └── scripts/                  # 辅助脚本（可选）
│       ├── validate.py           # 验证脚本
│       └── helper.sh            # 辅助脚本
```

### 文件命名规则

- **目录名**：小写字母，连字符分隔（如：`react-patterns`）
- **主文件**：总是命名为 `SKILL.md`（大写）
- **示例文件**：使用有意义的名称，`.md` 扩展名
- **脚本文件**：使用适合文件扩展名（`.py`、`.sh`、`.js`）

---

## SKILL.md 文件格式

### 1. 前置内容（YAML Frontmatter）

```yaml
---
name: skill-name                    # 必需：技能名称
description: "简要技能描述"         # 必需：一句话描述，200字符以内
category: development               # 必需：技能分类
risk: safe                         # 必需：风险级别（safe/medium/high）
source: community                   # 必需：来源（community/official）
date_added: "2024-01-15"         # 必需：添加日期，YYYY-MM-DD格式
author: your-username              # 可选：作者
tags: [react, frontend, patterns]  # 可选：标签列表，最多5个
tools: [claude, cursor, gemini]   # 可选：支持工具列表
---
```

**字段说明：**

| 字段 | 必需 | 格式 | 说明 |
|------|------|------|------|
| `name` | ✅ | 小写+连字符 | 技能标识符，用于`@skill-name`调用 |
| `description` | ✅ | 引号字符串 | 简洁描述，说明技能用途 |
| `category` | ✅ | 小写字符串 | 技能分类（见分类列表） |
| `risk` | ✅ | safe/medium/high | 风险级别，影响使用警告 |
| `source` | ✅ | community/official | 来源标识，官方或社区 |
| `date_added` | ✅ | YYYY-MM-DD | 技能添加日期 |
| `author` | ❌ | 字符串 | 贡献者用户名 |
| `tags` | ❌ | 数组 | 搜索和分类标签 |
| `tools` | ❌ | 数组 | 支持的AI工具列表 |

### 2. 技能内容结构

```markdown
# 技能标题

## 概述
2-4句话解释这个技能的作用和为什么存在。

## 何时使用此技能
- 当您需要[具体场景1]时使用
- 在处理[具体场景2]时使用
- 当用户询问[具体场景3]时使用

## 工作原理

### 步骤1：[操作名称]
详细的操作说明...

### 步骤2：[操作名称]
更多的操作说明...

## 示例

### 示例1：[用例标题]
```javascript
// 代码示例或配置
```

### 示例2：[用例标题]
```python
# Python示例代码
```

## 最佳实践
- 实践建议1
- 实践建议2
- 避免的陷阱

## 相关技能
- `@related-skill-1` - 关系说明
- `@related-skill-2` - 关系说明

## 常见问题
**Q: 常见问题？**
A: 详细回答...

## 限制和注意事项
- 技能限制1
- 使用注意事项1
```

---

## 技能分类系统

### 开发类（Development）

**前端开发（Frontend）**
- `frontend` - 通用前端开发
- `react` - React框架
- `vue` - Vue框架
- `angular` - Angular框架
- `css` - CSS和样式
- `javascript` - JavaScript语言

**后端开发（Backend）**
- `backend` - 通用后端开发
- `api` - API设计和开发
- `database` - 数据库相关
- `microservices` - 微服务架构
- `nodejs` - Node.js开发
- `python` - Python后端

**移动开发（Mobile）**
- `mobile` - 通用移动开发
- `react-native` - React Native
- `flutter` - Flutter框架
- `ios` - iOS开发
- `android` - Android开发

**测试（Testing）**
- `testing` - 通用测试
- `unit-testing` - 单元测试
- `e2e-testing` - 端到端测试
- `performance-testing` - 性能测试
- `security-testing` - 安全测试

### DevOps和基础设施（DevOps & Infrastructure）

**部署（Deployment）**
- `deployment` - 通用部署
- `docker` - 容器化
- `kubernetes` - 容器编排
- `ci-cd` - 持续集成/部署
- `cloud` - 云服务

**监控（Monitoring）**
- `monitoring` - 系统监控
- `logging` - 日志管理
- `observability` - 可观测性
- `performance` - 性能优化

### 安全类（Security）

**安全审计（Security Audit）**
- `security` - 通用安全
- `pen-testing` - 渗透测试
- `vulnerability` - 漏洞扫描
- `compliance` - 合规检查

**安全实施（Security Implementation）**
- `authentication` - 身份认证
- `authorization` - 授权控制
- `encryption` - 加密技术
- `secure-coding` - 安全编码

### AI和机器学习（AI & Machine Learning）

**AI开发（AI Development）**
- `ai` - 通用AI开发
- `llm` - 大语言模型
- `prompt-engineering` - 提示工程
- `ai-safety` - AI安全和伦理

**机器学习（Machine Learning）**
- `machine-learning` - 机器学习
- `data-science` - 数据科学
- `ml-ops` - 机器学习运维
- `model-training` - 模型训练

### 业务和产品（Business & Product）

**产品管理（Product Management）**
- `product` - 产品管理
- `planning` - 项目规划
- `requirements` - 需求分析
- `user-research` - 用户研究

**商业分析（Business Analysis）**
- `analytics` - 数据分析
- `metrics` - 指标分析
- `reporting` - 报告生成
- `business-intelligence` - 商业智能

### 工具和效率（Tools & Productivity）

**开发工具（Dev Tools）**
- `git` - 版本控制
- `editor` - 编辑器配置
- `terminal` - 终端和CLI
- `productivity` - 生产力工具

**文档（Documentation）**
- `documentation` - 文档编写
- `technical-writing` - 技术写作
- `api-docs` - API文档
- `tutorials` - 教程编写

---

## 质量标准

### 内容质量

**✅ 必须满足：**
- 描述清晰准确，无歧义
- 示例可运行，代码正确
- 步骤完整，逻辑清晰
- 涵盖常见使用场景

**🎯 鼓励添加：**
- 高级用法示例
- 常见错误处理
- 性能优化建议
- 最佳实践总结

### 格式规范

**✅ 必须遵守：**
- 前置内容完整且有效
- 正确的分类和标签
- 一致的代码块格式
- 正确的技能引用（`@skill-name`）

**🎯 推荐实践：**
- 添加目录结构说明
- 包含相关技能链接
- 提供故障排除指南
- 添加性能指标

### 技术质量

**✅ 安全要求：**
- 代码安全，无已知漏洞
- 输入验证完整
- 错误处理适当
- 不包含敏感信息

**✅ 性能要求：**
- 算法高效，复杂度合理
- 资源使用优化
- 内存泄漏防护
- 扩展性考虑

---

## 技能示例

### 简单技能示例

```yaml
---
name: git-commit-check
description: "检查Git提交消息格式和内容质量"
category: git
risk: safe
source: community
date_added: "2024-01-15"
tags: [git, commit, quality]
tools: [claude, cursor, gemini]
---
```

```markdown
# Git提交检查

## 概述
此技能用于检查Git提交消息的格式规范和内容质量，确保提交历史清晰可读。

## 何时使用此技能
- 当您需要验证提交消息格式时使用
- 在提交前进行质量检查时使用
- 当团队需要统一提交标准时使用

## 工作原理

### 步骤1：格式检查
验证提交消息是否遵循规范格式：
- 类型标签（feat/fix/docs等）
- 空行分隔
- 简洁标题（50字符内）
- 详细描述（如需要）

### 步骤2：内容检查
检查提交内容的质量：
- 是否包含必要信息
- 语法是否正确
- 是否有拼写错误

## 示例

### 示例1：标准提交
```
feat: 添加用户认证功能

- 实现JWT认证
- 添加登录/登出页面
- 更新用户模型
```

### 示例2：修复提交
```
fix: 修复登录页面重定向问题

解决用户登录后不能正确跳转到首页的bug
```

## 最佳实践
- 使用约定式提交格式
- 保持消息简洁明了
- 包含相关Issue编号
- 避免敏感信息泄露
```

### 复杂技能示例

```yaml
---
name: react-performance-optimization
description: "React应用性能优化和调试"
category: frontend
risk: medium
source: community
date_added: "2024-01-15"
tags: [react, performance, optimization]
tools: [claude, cursor, gemini]
---
```

```markdown
# React性能优化

## 概述
此技能提供React应用性能优化的系统性方法，包括识别瓶颈、应用优化策略和验证改进效果。

## 何时使用此技能
- 当React应用加载缓慢时使用
- 在用户体验需要优化时使用
- 当进行性能评估时使用
- 当准备生产部署时使用

## 工作原理

### 步骤1：性能评估
识别性能瓶颈：
- 使用React DevTools Profiler
- 分析组件渲染时间
- 检查内存使用情况
- 识别重渲染问题

### 步骤2：优化策略
应用优化技术：
- 组件懒加载
- React.memo优化
- 状态结构优化
- 副作用优化

### 步骤3：验证改进
确认优化效果：
- 重新运行性能测试
- 对比优化前后指标
- 确保功能完整性
- 监控生产表现

## 示例

### 示例1：组件优化
```javascript
// 优化前
function TodoList({ todos, onToggle }) {
  return (
    <div>
      {todos.map(todo => (
        <TodoItem 
          key={todo.id}
          todo={todo}
          onToggle={onToggle}
        />
      ))}
    </div>
  )
}

// 优化后
const TodoItem = React.memo(({ todo, onToggle }) => {
  return <div onClick={() => onToggle(todo.id)}>{todo.text}</div>
})

function TodoList({ todos, onToggle }) {
  const memoizedToggle = useCallback(onToggle, [])
  
  return (
    <div>
      {todos.map(todo => (
        <TodoItem 
          key={todo.id}
          todo={todo}
          onToggle={memoizedToggle}
        />
      ))}
    </div>
  )
}
```

### 示例2：路由懒加载
```javascript
// 优化前
import Home from './pages/Home'
import Profile from './pages/Profile'
import Settings from './pages/Settings'

// 优化后
const Home = lazy(() => import('./pages/Home'))
const Profile = lazy(() => import('./pages/Profile'))
const Settings = lazy(() => import('./pages/Settings'))

function App() {
  return (
    <Router>
      <Suspense fallback={<div>Loading...</div>}>
        <Route path="/" element={<Home />} />
        <Route path="/profile" element={<Profile />} />
        <Route path="/settings" element={<Settings />} />
      </Suspense>
    </Router>
  )
}
```

## 最佳实践
- 先测量，再优化
- 专注于用户感知的性能
- 避免过早优化
- 持续监控性能指标
- 平衡优化和代码可维护性
```

---

## 贡献指南

### 创建新技能

1. **选择分类**：参考分类系统确定合适分类
2. **创建目录**：遵循命名规范创建技能目录
3. **编写内容**：按照格式要求编写SKILL.md
4. **添加示例**：提供实际可运行的示例代码
5. **验证质量**：运行质量检查工具

### 验证命令

```bash
# 验证技能格式
npm run validate:skill skills/your-skill-name/

# 验证前置内容
npm run validate:frontmatter skills/your-skill-name/

# 生成技能索引
npm run index
```

### 提交流程

1. Fork仓库
2. 创建特性分支
3. 添加技能文件
4. 运行验证测试
5. 提交Pull Request

---

## 质量保证

### 自动化检查

- **格式验证**：确保前置内容格式正确
- **链接检查**：验证内部链接有效
- **分类验证**：检查分类和标签合规
- **重复检测**：避免技能重复

### 人工审核

- **内容准确性**：确保技术信息正确
- **实用性评估**：评估技能实用价值
- **用户体验**：确保易于理解和使用
- **社区价值**：评估对社区的贡献

### 持续改进

- **用户反馈**：收集使用反馈
- **性能监控**：监控技能使用效果
- **定期更新**：根据技术发展更新内容
- **质量提升**：持续改进技能质量

---

这个结构指南确保了技能的一致性、可维护性和高质量。遵循这些指导方针，您可以创建出对AI开发社区有价值的实用技能。

如果您有任何疑问或需要指导，请随时联系维护团队。🚀