创建自定义 Skills —— 从经验到可复用工作流、SKILL.md 格式规范、Frontmatter 与常见陷阱

经验沉淀流程：

个人经验 ──→ 记录整理 ──→ 结构化文档 ──→ 封装为 Skill ──→ 团队共享
  (隐性)       (文档化)     (知识库)        (SKILL.md)      (可复用)

✅ 适合：                              ❌ 不适合：
• React 组件性能审计流程                 • "帮我写首诗"（太主观）
• Python 异步代码审查                    • "翻译这段文字"（通用任务）
• 数据库慢查询诊断                       • "计算 2+2"（太简单）
• CI/CD 流水线调试                       • "推荐一本书"（无固定流程）
• Kubernetes 故障排查                    • "画个架构图"（输出不确定）

知识要素拆解模板：
  场景: React 组件性能优化
  输入:
    - 组件源码文件
    - 可选: 性能分析报告
  输出:
    - 性能问题清单
    - 修复建议
    - 修改后的代码（可选）
  需要知道:
    - React 渲染机制
    - 常见性能反模式
    - 优化手段及适用场景
    - 验证方法
  工具需要:
    - read_file (读代码)
    - patch (改代码)
    - terminal (跑测试/性能分析)
    - code_search (搜索特定模式)

React 性能审计工作流：

1. [检测] 扫描组件文件，识别潜在性能问题
2. [分析] 对每个问题判断严重程度和影响范围
3. [建议] 生成修复方案（含代码示例）
4. [实施] 应用修复（用户确认后）
5. [验证] 运行测试确保功能正常

---
name: react-performance-audit
version: 1.2.0
description: React 组件性能审计与优化技能
author: 张三 <zhangsan@example.com>
license: MIT
tags:
  - react
  - performance
  - frontend
  - audit
requires:
  - read_file
  - patch
  - terminal
  - code_search
inject:
  - knowledge/rendering-model.md
  - knowledge/anti-patterns.md
  - knowledge/optimization-strategies.md
---

# React 性能审计与优化

## 能力概述

本技能使 Agent 具备对 React 18+ 组件进行**系统化性能审计**的能力。

## 何时使用

当用户提到以下关键词或场景时，应主动建议使用此技能：
- 组件渲染慢 / 卡顿 / 掉帧
- "优化 React 性能"
- "为什么这个组件反复渲染"
- React DevTools Profiler 分析
- 列表滚动性能问题

## 能力范围

### 能做的
- ✅ 识别不必要的组件重渲染
- ✅ 检测 useMemo / useCallback 的误用和缺失
- ✅ 分析状态管理导致的全量更新
- ✅ 检查大列表未虚拟化问题
- ✅ 检测内存泄漏（未清理的 effect）
- ✅ 提供具体的代码修复方案

### 不能做的
- ❌ 无法分析 React Native 原生模块性能
- ❌ 无法优化 Webpack 打包体积（需配合 bundle-analysis 技能）
- ❌ 无法替代人工进行架构级性能规划

## 工作流程

### 审计流程

1. **扫描阶段**：使用 `code_search` 搜索目标文件中的性能反模式
2. **分析阶段**：读取相关文件，结合知识库判断问题严重性
3. **报告阶段**：生成结构化的性能审计报告
4. **修复阶段**：对每个问题提供修复代码（使用 `patch`）
5. **验证阶段**：运行测试确保功能未受损

### 交互模式

## 相关知识

- [React 渲染模型](knowledge/rendering-model.md)
- [常见性能反模式](knowledge/anti-patterns.md)
- [优化策略速查](knowledge/optimization-strategies.md)

---
name: react-performance-audit
version: 1.2.0
description: "React 组件性能审计与优化技能"
author: "张三 <zhangsan@example.com>"
license: MIT
homepage: "https://github.com/example/react-performance-audit"
repository: "https://github.com/example/react-performance-audit.git"
---

---
# ─── 基础信息 ───
name: my-skill-name              # 技能标识符（必需）
                                 # 规则：小写字母、数字、连字符
                                 # 长度：3-50 字符
                                 # 示例：react-perf, db-tuning, k8s-deploy

version: 1.2.0                   # 语义化版本号（必需）
                                 # 格式：MAJOR.MINOR.PATCH
                                 # MAJOR: 不兼容更新
                                 # MINOR: 向后兼容的功能新增
                                 # PATCH: 向后兼容的 bug 修复

description: "一句话描述"         # 技能描述（必需）
                                 # 长度：10-200 字符
                                 # 用途：搜索展示、列表预览

author: "你的名字 <邮箱>"          # 作者信息（推荐）

license: MIT                     # 许可证（推荐）
                                 # 常用：MIT, Apache-2.0, GPL-3.0

# ─── 分类与标签 ───
tags:                            # 标签数组（推荐）
  - react
  - performance
  - frontend
category: frontend               # 主分类（可选）
                                 # 内置分类：
                                 #   frontend, backend, devops, database,
                                 #   testing, security, ai-ml, data-science,
                                 #   mobile, documentation

# ─── 工具依赖 ───
requires:                        # 需要的工具列表（必需）
  - read_file
  - write_file
  - patch
  - terminal
  - code_search

optional_tools:                  # 可选工具（可选）
  - lint_check
  - test_run

# ─── 知识库注入 ───
inject:                          # 要注入到上下文的知识文件（推荐）
  - knowledge/overview.md
  - knowledge/patterns/*.md      # 支持 glob 模式
  - knowledge/anti-patterns.md

inject_mode: system_prompt       # 注入模式（可选，默认 system_prompt）
                                 # system_prompt: 注入到系统提示词（优先级高）
                                 # context: 注入到对话上下文
                                 # both: 同时注入

# ─── 运行约束 ───
min_hermes_version: 0.8.0        # 最低 Hermes 版本（可选）

platforms:                       # 支持的平台（可选，默认全部）
  - linux
  - macos

languages:                       # 适用的编程语言（推荐）
  - typescript
  - javascript

project_types:                   # 适用的项目类型（可选）
  - react
  - nextjs

# ─── 依赖声明 ───
dependencies:                    # 外部依赖（可选）
  node: ">=18.0.0"
  npm_packages:
    - react@">=18.0.0"

conflicts:                       # 冲突的技能（可选）
  - react-old-perf-checker       # 与旧版本技能互斥

# ─── 工作流定义 ───
workflows:                       # 内置工作流（可选）
  audit:
    name: "性能审计"
    description: "对 React 组件进行性能审计"
    trigger_words:
      - "性能审计"
      - "渲染慢"
      - "优化性能"
    steps:
      - scan
      - analyze
      - report
      - fix

# ─── 自定义变量 ───
variables:                       # 技能内部变量（可选）
  max_severity: P0               # 最大严重级别
  auto_fix: false                # 是否自动修复

# ─── 元数据 ───
created: 2025-05-20              # 创建日期
updated: 2025-06-15              # 最后更新日期
changelog: |                     # 更新日志
  1.2.0 - 新增 React 19 支持
  1.1.0 - 优化检测算法
  1.0.0 - 初始版本
---

# 验证 SKILL.md 格式
hermes skills validate ./my-skill/SKILL.md

# 输出：
# ═══════════════════════════════════════════════════
#  SKILL.md 验证结果
# ═══════════════════════════════════════════════════
#
#  ✅ Frontmatter 格式正确
#  ✅ 必需字段完整 (name, version, description)
#  ✅ 版本号符合语义化规范 (1.2.0)
#  ✅ 标签有效 (3 个)
#  ✅ 工具列表有效 (5 个工具)
#  ✅ 知识库文件存在 (3/3)
#  ⚠️  建议添加 license 字段
#  ⚠️  建议添加 author 字段
#  ⚠️  描述长度偏短 (15 字符)，建议 30+ 字符
#
#  总计: 4 个通过, 0 个错误, 3 个建议

# ❌ 错误 1：name 包含大写字母
---
name: ReactPerformance    # 错误！必须全小写
---

# ✅ 正确
---
name: react-performance
---

# ❌ 错误 2：版本号不规范
---
version: 1.2              # 错误！缺少 PATCH 版本
version: v1.2.0           # 错误！不要带 v 前缀
version: "1.0"            # 错误！
---

# ✅ 正确
---
version: 1.2.0
---

# ❌ 错误 3：描述为空或过长
---
description: ""           # 错误！描述不能为空
description: "这是一个非常非常非常长的描述，超过了200个字符的限制，会导致解析失败并且在 Skills Hub 上显示不完整，影响用户的阅读体验。"  # 错误！
---

# ✅ 正确
---
description: "React 组件性能审计与优化技能，自动检测反渲染、状态管理等问题"
---

# ❌ 错误 4：requires 中包含不存在的工具
---
requires:
  - read_file
  - magic_fix             # 错误！不存在这个工具
---

# ❌ 错误 5：inject 指向不存在的文件
---
inject:
  - knowledge/nonexistent.md   # 错误！文件不存在
---

my-skill/
├── SKILL.md                    # 技能入口文件
├── knowledge/                   # 知识库根目录
│   ├── overview.md              # 概述（总是第一个加载）
│   ├── concepts/                # 核心概念
│   │   ├── rendering-model.md
│   │   └── state-management.md
│   ├── patterns/                # 最佳实践模式
│   │   ├── memoization.md
│   │   ├── virtualization.md
│   │   └── lazy-loading.md
│   ├── anti-patterns/           # 反模式/常见错误
│   │   ├── excessive-re-render.md
│   │   ├── misuse-of-memo.md
│   │   └── memory-leaks.md
│   ├── examples/                # 示例代码
│   │   ├── before-after.md      # 修复前后对比
│   │   └── templates.md         # 代码模板
│   └── reference/               # 参考资料
│       ├── react-docs-links.md
│       └── tools-guide.md
├── workflows/                   # 工作流定义
│   ├── audit.yaml
│   └── fix.yaml
└── assets/                      # 附加资源
    └── templates/
        └── component-template.tsx

<!-- ❌ 为人写作：太笼统 -->
# React 性能优化
React 性能优化很重要，有很多方法可以做。

<!-- ✅ 为 Agent 写作：结构化、可执行 -->
# React 性能优化

## 识别不必要的重渲染

### 判断标准
当以下任一条件满足时，组件发生了不必要的重渲染：
1. props 值未变化，但组件重新执行了 render
2. context 值未变化，但消费该 context 的组件重新渲染
3. state 值通过 Object.is 比较相等，但触发了重新渲染

### 检测方法
```bash
# 使用 React DevTools Profiler
# 1. 打开 DevTools → Profiler
# 2. 点击 "Record" 开始录制
# 3. 执行触发渲染的操作
# 4. 点击 "Stop" 查看火焰图
# 5. 关注 "Why did this render?" 面板
```

### 常见原因
| 原因 | 症状 | 解决方案 |
|------|------|----------|
| 父组件重渲染传递新对象引用 | props 看起来一样但组件重新渲染 | 提升状态 / 使用 useMemo |
| Context 值频繁变化 | 大量无关组件重新渲染 | 拆分 Context / 使用 selector |
| 内联函数/对象作为 props | 子组件每次都是新引用 | useCallback / useMemo |

## 何时使用 useMemo

### 应该使用 ✅
- [ ] 计算成本 > 5ms 的纯函数
- [ ] 引用稳定性的场景（作为其他 hook 的依赖）
- [ ] 传递给 React.memo 包裹的组件的 props

### 不应该使用 ❌
- [ ] 简单的值计算（如 `a + b`）
- [ ] 仅渲染一次的组件
- [ ] 没有传递给子组件的局部变量
- [ ] 期望缓存副作用（useMemo 不保证执行次数）

### 决策树
计算成本高？── 是 ──→ 是纯函数？── 是 ──→ 使用 useMemo
    │                      │
    否                     否
    │                      │
    ▼                      ▼
不使用                  考虑重构为纯函数

## 虚拟列表实现模板

### 问题场景
当列表数据量 > 100 条时，直接渲染所有 DOM 节点会导致严重卡顿。

### 解决方案：react-window 虚拟列表

```tsx
import { FixedSizeList } from 'react-window';

// ❌ 错误：直接渲染所有数据
function BadList({ items }: { items: Item[] }) {
  return (
    <div>
      {items.map((item) => (
        <div key={item.id}>{item.name}</div>
      ))}
    </div>
  );
}

// ✅ 正确：使用虚拟列表
function GoodList({ items }: { items: Item[] }) {
  const Row = ({ index, style }: ListChildComponentProps) => {
    const item = items[index];
    return (
      <div style={style}>
        {item.name}
      </div>
    );
  };

  return (
    <FixedSizeList
      height={600}
      itemCount={items.length}
      itemSize={40}
      width="100%"
    >
      {Row}
    </FixedSizeList>
  );
}
```

# workflows/audit.yaml
name: performance-audit
description: "对 React 组件进行系统化性能审计"
version: 1.0.0

# 触发词：当用户输入包含这些词时，Agent 会考虑使用此工作流
trigger_words:
  - "性能审计"
  - "渲染慢"
  - "卡顿"
  - "优化"
  - "重渲染"

# 输入参数
inputs:
  - name: target_files
    type: file_paths
    description: "需要审计的组件文件路径"
    required: true
  - name: severity_threshold
    type: enum
    description: "最低报告严重级别"
    default: P2
    options: [P0, P1, P2, P3]

# 步骤定义
steps:
  - name: scan
    description: "扫描文件中的性能反模式"
    tool: code_search
    args:
      patterns:
        - pattern: "\\.map\\(.*=>.*<[^>]+>"
          description: "检查 .map 渲染是否使用了 key"
        - pattern: "useMemo\\(\\(\\) =>"
          description: "检查 useMemo 是否缺少依赖数组"
        - pattern: "style=\\{\\{"
          description: "检查是否使用内联样式对象"
      files: "{{ inputs.target_files }}"

  - name: analyze
    description: "分析问题严重性"
    tool: read_file
    args:
      # Agent 根据 scan 结果，读取相关源文件深入分析
      context: "结合知识库中的反模式文档，判断每个问题的严重级别"

  - name: report
    description: "生成审计报告"
    tool: write_file
    args:
      path: "./performance-audit-report.md"
      content_template: |
        # 性能审计报告

        审计时间: {{ now }}
        目标文件: {{ inputs.target_files }}
        严重级别阈值: {{ inputs.severity_threshold }}

        ## 问题清单

        {{ scan_results | format_report }}

  - name: suggest_fixes
    description: "提供修复建议"
    args:
      # 这一步主要依赖知识库，不需要特定工具
      instruction: |
        根据发现的问题，从知识库中匹配对应的修复方案。
        对每个问题提供：
        1. 问题描述
        2. 严重程度 (P0/P1/P2/P3)
        3. 修复代码（修改前 vs 修改后）
        4. 修复后的预期效果

  - name: apply_fixes
    description: "应用修复（需用户确认）"
    tool: patch
    args:
      # Agent 展示修改建议，等待用户确认后再执行
      require_confirmation: true

# 步骤类型参考

# 1. 工具执行步骤
- name: step_name
  tool: terminal
  args:
    command: "npm run lint"

# 2. 知识驱动步骤（不依赖特定工具）
- name: step_name
  args:
    instruction: "根据知识库中的规则 X 进行分析"

# 3. 条件分支步骤
- name: check_severity
  condition: "{{ scan_results | length > 0 }}"
  then:
    - name: report_critical
      args:
        instruction: "报告严重问题"
  else:
    - name: all_clear
      args:
        instruction: "报告未发现严重问题"

# 4. 循环步骤
- name: check_each_file
  loop: "{{ inputs.target_files }}"
  args:
    instruction: "对 {{ loop_item }} 执行性能检查"

# 5. 并行步骤
- name: parallel_check
  parallel:
    - name: check_js
      args:
        instruction: "检查 JS 文件性能模式"
    - name: check_css
      args:
        instruction: "检查 CSS 文件性能模式"

# 变量引用语法
variables:
  max_issues: 50
  report_format: markdown

# 在步骤中引用变量
- name: generate_report
  args:
    instruction: |
      生成最多 {{ variables.max_issues }} 个问题的报告
      使用 {{ variables.report_format }} 格式
      审计时间: {{ now }}
      工作目录: {{ workspace_root }}
      技能版本: {{ skill.version }}

# 管道过滤器
- name: format_results
  args:
    instruction: |
      按严重级别排序: {{ results | sort_by("severity") }}
      只显示 P0/P1: {{ results | filter("severity", ["P0", "P1"]) }}
      去重: {{ results | unique_by("pattern") }}
      取前 N 个: {{ results | limit(10) }}

$ tree react-performance-audit/
react-performance-audit/
├── SKILL.md
├── knowledge/
│   ├── overview.md
│   ├── concepts/
│   │   ├── rendering-model.md
│   │   └── react-memo.md
│   ├── anti-patterns/
│   │   ├── excessive-re-render.md
│   │   ├── misuse-of-memo.md
│   │   └── inline-objects.md
│   ├── patterns/
│   │   ├── virtualization.md
│   │   └── code-splitting.md
│   └── examples/
│       └── before-after.md
└── workflows/
    └── audit.yaml

---
name: react-performance-audit
version: 1.0.0
description: "React 组件性能审计与优化，自动检测重渲染、memo 误用、虚拟列表等问题"
author: "Hermes Community"
license: MIT
tags:
  - react
  - performance
  - frontend
  - audit
category: frontend
requires:
  - read_file
  - patch
  - terminal
  - code_search
optional_tools:
  - lint_check
inject:
  - knowledge/overview.md
  - knowledge/concepts/*.md
  - knowledge/anti-patterns/*.md
  - knowledge/patterns/*.md
inject_mode: system_prompt
languages:
  - typescript
  - javascript
project_types:
  - react
  - nextjs
dependencies:
  node: ">=18.0.0"
workflows:
  audit:
    name: "性能审计"
    description: "对 React 组件进行系统化性能审计"
    trigger_words:
      - "性能审计"
      - "渲染慢"
      - "优化性能"
---

# React 性能审计与优化

## 能力概述

本技能使 Agent 具备对 React 18+ 组件进行**系统化性能审计**和**自动优化建议**的能力。

## 何时使用

当用户提到以下关键词或场景时主动建议：
- 组件渲染慢 / 卡顿 / 掉帧
- "优化 React 性能" / "性能审计"
- "为什么反复渲染"
- 大列表滚动问题

## 能力范围

### 能做的
- ✅ 识别不必要的组件重渲染
- ✅ 检测 useMemo/useCallback 误用
- ✅ 分析状态管理导致的全量更新
- ✅ 检查大列表未虚拟化
- ✅ 检测内存泄漏
- ✅ 提供具体修复代码

### 不能做的
- ❌ React Native 原生模块性能
- ❌ Webpack 打包体积优化
- ❌ 架构级性能规划

# ❌ 错误：一次性注入太多文件
---
inject:
  - knowledge/*.md              # 可能注入 50+ 文件
  - docs/*.md
  - examples/*.md
---

# 正确：按需注入核心文件
---
inject:
  - knowledge/overview.md       # 概览总是需要
  - knowledge/anti-patterns/*.md # 核心反模式
inject_mode: system_prompt
---

# 补充知识通过工作流按需加载
workflows:
  audit:
    steps:
      - name: load_additional
        args:
          instruction: |
            如果发现问题类型 X，加载 knowledge/patterns/X.md
            如果发现问题类型 Y，加载 knowledge/patterns/Y.md

# ❌ 错误：触发词太宽泛
---
workflows:
  audit:
    trigger_words:
      - "优化"          # 太宽泛！数据库、网络、CSS 都要优化
      - "检查"          # 太宽泛！任何检查都会触发
      - "问题"          # 太宽泛！
---

# 正确：精准触发词
---
workflows:
  audit:
    trigger_words:
      - "React 性能"
      - "渲染慢"
      - "重渲染"
      - "组件卡顿"
      - "性能审计"
---

# ❌ 错误：一个技能做太多事
---
name: react-everything
description: "React 全能技能：性能、测试、安全、部署..."
---

# 正确：拆分为多个专注的技能
# react-performance-audit    - 性能审计
# react-testing-guide        - 测试指南
# react-security-check       - 安全检查
# react-deploy-helper        - 部署辅助

# ❌ 错误：没声明与其他技能的冲突
---
name: react-perf-v2
description: "React 性能优化 V2"
# 没有 conflicts 字段
---

# 正确：明确声明冲突
---
name: react-perf-v2
description: "React 性能优化 V2"
conflicts:
  - react-perf-v1            # 与旧版本互斥
  - react-simple-perf        # 与简化版互斥
---

# ❌ 错误：路径不存在或拼写错误
---
inject:
  - knowledge/anti-pattern.md    # 实际文件名是 anti-patterns.md（复数）
  - knowledge/pattern/*.md       # 实际目录是 patterns/（复数）
---

# 正确：使用 validate 命令检查
# hermes skills validate ./my-skill/SKILL.md

# ❌ 错误：模糊描述
---
description: "React 相关的技能"    # 太模糊
description: "性能优化"              # 没有说明是什么的性能优化
---

# 正确：精确描述
---
description: "React 18+ 组件性能审计与优化，自动检测重渲染、memo 误用等问题"
---

# ❌ 错误：不声明版本约束
---
name: nextjs-helper
description: "Next.js 开发辅助"
# 没有声明依赖的 Next.js 版本
---

# 正确：声明版本约束
---
name: nextjs-helper
version: 2.0.0
description: "Next.js 14+ App Router 开发辅助"
project_types:
  - nextjs
dependencies:
  npm_packages:
    - next@">=14.0.0"
---

<!-- ❌ 错误：只有冷冰冰的文档 -->
# 我的技能
这个技能可以做 X、Y、Z。

<!-- ✅ 正确：提供交互示例 -->
# 我的技能

## 使用示例


用户: 帮我看看这个组件为什么这么慢
Agent: [加载技能]
Agent: 我来帮你做性能审计。请先告诉我：
       1. 哪个组件文件？
       2. 有什么具体的表现？（如：输入时卡顿 / 滚动时掉帧）