meta_skills

meta_skills plugin for Cursor

9 skills

figma-implementation

# Figma 设计实现工作流 ## 第一步：功能分析 ### 1.1 获取设计信息 ``` 输入: Figma URL 示例: https://www.figma.com/design/{fileKey}/{fileName}?node-id={nodeId} 提取参数: - fileKey: URL 中 /design/ 后的字符串 - nodeId: node-id 参数值 (将 "

# Figma 设计实现工作流

## 第一步：功能分析

### 1.1 获取设计信息

```
输入: Figma URL
示例: https://www.figma.com/design/{fileKey}/{fileName}?node-id={nodeId}

提取参数:
- fileKey: URL 中 /design/ 后的字符串
- nodeId: node-id 参数值 (将 "-" 转换为 ":")
```

### 1.2 设计预览

| 工具调用 | 目的 | 输出 |
|----------|------|------|
| `get_screenshot(fileKey, nodeId)` | 查看整体视觉效果 | 截图 |
| `get_metadata(fileKey, nodeId)` | 获取图层结构 | XML 节点树 |

### 1.3 图层结构分析

从 metadata 识别节点类型:

| 节点类型 | Figma 标签 | 用途 |
|----------|------------|------|
| 布局容器 | `frame`, `group` | 对应 div 结构 |
| 背景/边框 | `rectangle`, `rounded-rectangle` | 背景图或 CSS |
| 图标/装饰 | `vector`, `boolean-operation` | 导出为图片 |
| 文本 | `text` | CSS 文字 |
| 蒙版 | `Mask group` | 裁切效果 |
| 图片 | 带图片填充的矩形 | 导出资源 |

### 1.4 功能点识别

分析设计稿中的交互元素:

```
- 按钮 → 点击事件
- 列表 → v-for 循环
- 状态指示 → 条件渲染 (v-if/v-show)
- 动态数据 → 绑定变量
- 动画效果 → CSS transition/animation
```

---

## 第二步：实现设计

### 2.1 矢量合并分析 ⭐

**目的**: 简化节点树，确定哪些图层需要合并导出

**合并规则**:

| 特征 | 处理方式 | 理由 |
|------|----------|------|
| 多个 `vector` 组成图标 | 导出父节点 | CSS 无法重现复杂路径 |
| `boolean-operation` | 导出该节点 | 布尔运算结果需整体导出 |
| 装饰性边框/花纹 | 导出父 frame | 多图层叠加效果 |
| 渐变/阴影叠加 | 导出合成图 | 复杂视觉效果 |
| 纯布局容器 | 保留结构 | 用 div 实现 |
| 文本层 | 不导出 | 用 CSS 实现 |
| 需要动态变化的元素 | 单独导出 | 运行时切换 |

**分析示例**:

```
原始图层树:
├── Frame "Card"
│   ├── Rectangle "bg-1"
│   ├── Rectangle "bg-2"
│   ├── Vector "decoration-1"
│   ├── Vector "decoration-2"
│   ├── Frame "icon-group"
│   │   ├── Vector "icon-part-1"
│   │   └── Vector "icon-part-2"
│   └── Text "title"

合并决策:
├── Frame "Card" → div.card
│   ├── [bg-1 + bg-2 + decoration-*] → 合并导出 card-bg.png
│   ├── Frame "icon-group" → 合并导出 icon.png
│   └── Text "title" → CSS 文字
```

### 2.2 资源导出

```
对每个需要导出的节点:

1. 调用 get_design_context(fileKey, nodeId)
2. 从返回的 assets 中提取 URL
3. 使用 curl 下载到 src/assets/{feature}/
4. 验证文件格式 (file *.png)
```

**命名规范**:

```
src/assets/{feature}/
├── {component}-bg.png      # 背景
├── {component}-icon.png    # 图标
├── {element}.png           # 独立元素
└── {state}-{element}.png   # 状态变体
```

### 2.3 简化节点树

基于合并分析，输出最终实现结构:

```
合并后节点树:
├── div.container
│   ├── img.background (或 background-image)
│   ├── div.content
│   │   ├── img.icon
│   │   └── span.text
│   └── div.overlay (可选)
```

### 2.4 代码结构设计

**Vue 组件模板**:

```vue
<template>
  <div class="component-name">
    <!-- 静态背景层 -->
    <div class="bg"></div>
    
    <!-- 内容层 -->
    <div class="content">
      <img :src="iconSrc" class="icon" />
      <span class="text">{{ text }}</span>
    </div>
    
    <!-- 交互/状态层 -->
    <div v-if="hasState" class="badge"></div>
  </div>
</template>
```

**样式实现**:

```scss
.component-name {
  // 1. 定位 (来自 metadata 的 x, y)
  position: absolute;
  left: {x}px;
  top: {y}px;
  
  // 2. 尺寸 (来自 metadata 的 width, height)
  width: {width}px;
  height: {height}px;
  
  // 3. 背景 (导出的资源)
  .bg {
    background-image: url('~@/assets/{feature}/{name}.png');
    background-size: cover;
  }
}
```

### 2.5 实现清单

| 步骤 | 操作 | 文件 |
|------|------|------|
| 1 | 创建资源目录 | `src/assets/{feature}/` |
| 2 | 下载图片资源 | `*.png` |
| 3 | 创建组件文件 | `src/components/{Name}.vue` |
| 4 | 编写模板结构 | `<template>` |
| 5 | 编写样式 | `<style>` |
| 6 | 编写逻辑 | `<script>` |
| 7 | 注册/引用组件 | 父组件 |
| 8 | 添加国际化文案 | `src/locale/lang/*.json` |

---

## 工具调用参考

### get_screenshot

```
用途: 获取节点截图
参数: fileKey, nodeId
返回: 图片
```

### get_metadata

```
用途: 获取图层结构
参数: fileKey, nodeId
返回: XML 格式的节点树 (id, name, x, y, width, height)
```

### get_design_context

```
用途: 获取代码提示和资源链接
参数: fileKey, nodeId
返回: 
  - 代码建议
  - assets: { [name]: downloadUrl }
```

---

## 注意事项

1. **矢量合并优先**: 先分析哪些需要合并，再导出资源
2. **父节点导出**: 请求父节点会自动合成所有子图层
3. **动态元素分离**: 需要运行时变化的元素要单独导出
4. **文本不导出**: 文字用 CSS 实现，便于国际化
5. **验证格式**: 下载后用 `file` 命令检查实际格式
6. **资源复用**: 检查是否有可复用的现有资源

log-analysis

标准化 Agent 执行日志分析报告模板。log-analyzer 分析 agent-transcripts 时使用本 Skill 产出结构化报告。

# 日志分析报告技能

log-analyzer 在分析 Agent 执行日志时，使用本模板产出结构化报告。与 `log-analyzer-enhanced` 规则配合使用。

## When to Use

- log-analyzer 被调用分析 agent-transcripts
- 需要产出技术维度或流程维度的分析报告
- 需要与进化 Agent（skill-miner）协作

---

## 依赖与协作关系

本 Skill **定义输出格式**，需要配合以下组件使用：

| 组件 | 路径 | 职责 | 必需 |
|------|------|------|------|
| `log-analyzer-enhanced` Rule | `cross-evolution/rules/log-analyzer-enhanced.md` | 定义**分析过程规则**（认知增强、证据引用、严重性判定、元认知协作） | 是 |
| `evolution-history` Skill | `cross-evolution/skills/evolution-history/SKILL.md` | 进化轨迹追踪（项目进化用本地文件，自身进化用 git 仓库） | 是 |
| `skill-mining` Skill | `cross-evolution/skills/skill-mining/SKILL.md` | 消费本 Skill 输出，提炼 Skill/Rule | 可选 |

### 独立使用时的最小要求

若未加载 `log-analyzer-enhanced` Rule，分析时需自行确保：
- 区分**表面症状**与**深层根因**（Rule 1.2）
- 低置信结论标注**「需验证」**并附验证步骤（Rule 1.3）
- 证据引用统一使用 `文件名:行号` 格式（Rule 2.1）
- 报告末尾包含**「分析局限」**小节（Rule 2.3）

---

## 标准化报告模板

### 历史咨询（前置步骤）

分析开始前，根据进化场景读取历史（详见 `evolution-history` Skill 的双模式设计）：

**项目进化模式**（改进目标项目的 Rule/Skill）：
1. 检查项目根目录 `evolution-history/` 是否存在
   - 不存在 → 首轮，跳过历史咨询，所有发现视为新发现
   - 存在 → 读取 `pattern-registry.md`（热区），执行循环检测
2. 分析时将本轮发现与已有模式指纹比对
3. 对已知模式标注「复现 PAT-{NNN}」

**自身进化模式**（改进 Agent 基础设施本身）：
1. 检查 `.cursor/evolution-store.json` 是否存在
   - 不存在 → 向用户询问 git 地址（不预设默认值）
   - `disabled: true` → 跳过
   - 存在 → `git pull`，继续
2. 读取 `shared/universal-patterns.md`（跨项目通用知识）
3. 读取本项目 `projects/{project_id}/pattern-registry.md`（热区）
4. 分析时将本轮发现与已有模式指纹（项目级 + 通用级）比对
5. 对已知模式标注「复现 PAT-{project_id}-{NNN}」

### 必填元数据

| 字段 | 说明 | 示例 |
|------|------|------|
| 来源日志 | 分析的日志文件路径 | `abc12345.txt` |
| 会话主题 | 用户要求完成的任务 | 项目搭建 + 功能实现 |
| 分析视角 | 技术 / 流程 / 联合 | 技术维度归纳 |
| 分析日期 | 报告生成日期 | 2025-02-10 |
| 进化轮次 | 所属轮次编号（若在进化流程中） | Round 003 |

### 报告命名规范

- **默认路径**：`evolution-history/log-analysis-round-{NNN}.md`，其中 `{NNN}` 为三位数字轮次编号（如 001、002）
- **多实例场景**：若主流程并行启动多个 log-analyzer 实例，使用 `log-analysis-round-{NNN}-instance{1|2}.md` 或由主 Agent 在启动 prompt 中明确指定
- **一致性**：同一轮次内，所有实例的输出文件名应遵循同一命名规范，便于主流程发现与合并

### 概要表格

概要表必须在**所有问题条目完成后**、根据条目的严重性分类统计生成，不得提前填写或凭记忆估算。

**产出前核对**（必须执行）：完成所有问题条目后，逐条核对并统计：
1. P（含 P-已缓释）数量 → 填入「严重问题」
2. W 数量 → 填入「警告」
3. 建议数量 → 填入「优化建议」
4. 核对数值与条目数一致后，再写入概要表

```markdown
## 概要

| 指标 | 数值 |
|------|------|
| 分析日志数量 | N |
| 严重问题 | N |
| 警告 | N |
| 优化建议 | N |
| 跨会话模式（若有） | N 个 |
```

### 问题条目必填字段

| 字段 | 格式 | 说明 |
|------|------|------|
| 表面症状 | 一句话 | 用户可见的现象 |
| 深层根因 | 一段话 | 导致症状的根本原因 |
| 日志位置 | `文件名:行号` | 精确引用 |
| 证据 | 表格或列表 | 证据 + 位置 |
| 严重性 | P / P-已缓释 / W / 建议 | 分级 |
| 置信度 | 高 / 中 / 低 | 低置信需附验证步骤 |
| 建议修复 | 1–3 项 | 含次生风险检查 |
| 模式指纹 | 见下方「模式指纹格式约定」 | 标准化描述，用于跨轮次比对 |
| 注册表关联 | `PAT-{XXX}` 或「新发现」 | 与 pattern-registry 的映射 |

### 模式指纹格式约定

- **格式**：`[类型] 动词+对象+条件`，可选使用 `→` 表示因果（如 `[输出质量] 概要表指标与条目数不匹配`）
- **纯文本**：不使用 markdown 代码块（反引号）包裹整条指纹
- **类型标签**：使用 `[协作]`、`[输出质量]`、`[技术]`、`[流程]`、`[认知能力]`、`[元认知]` 等，与问题维度对应
- **一致性**：多实例产出时，各实例的指纹格式（是否使用 `→`、标签集）应保持一致，便于主流程合并去重

### 多实例场景与去重责任

当主流程并行启动多个 log-analyzer 实例时：

- **log-analyzer 职责**：产出「模式指纹 + 置信度」供合并使用；不负责跨实例去重
- **主流程职责**：Round 1 结束后，由主 Agent 或专用合并步骤对重复指纹进行合并去重
- **合并建议**：可在 cross-evolution 协议中定义「Round 1 结束后合并去重」流程；log-analyzer 可产出交叉引用表格供 skill-miner 直接消费

### 分析局限小节（必填）

对单文件 **>100KB** 的日志，必须在分析局限中声明：

- **大型日志策略声明**：采用 Grep 关键词 + 抽样 Read 策略
- **覆盖范围**：列出实际使用的关键词列表或抽样方法
- **示例**：「采用 Grep 关键词 + 抽样 Read 策略，覆盖范围：[base64, saveImage, playwright, 报错, ERROR]」

```markdown
## 分析局限

- **大型日志策略（>100KB 时必填）**：声明 Grep 策略与覆盖范围
- **低置信结论**：[列出标注「需验证」的结论及验证方式]
- **未覆盖**：[如单一会话、无跨会话对比]
- **建议人工复核**：[具体条目]
```

### 交叉引用格式

```markdown
### 建议进化 Agent 关注

| 发现 | 预期落地形式 | 优先级 |
|------|--------------|--------|
| 某配置方案 | 写入 Skill 的配置章节 | P0 |
| 某调试步骤 | 写入 Skill 的 Troubleshooting | P1 |
```

---

## 证据引用规范

- **强制**：所有证据引用必须包含行号，格式为 `文件名:行号` 或 `文件名:起始行-结束行`
- **技术类**：精确到单行或行范围
- **流程类**：可保留行范围，但必须注明「基于行号估算」
- **跨多处证据**：至少给出一个精确 `文件名:行号` 作为锚点，便于快速定位验证
- **禁止**：仅给出文件名无行号；「约」「大概」等模糊表述

---

## 严重性分级规范

| 等级 | 定义 | 适用场景 |
|------|------|----------|
| P | 必须修复 | 无有效修复，影响核心功能 |
| P-已缓释 | 已有修复，需纳入流程 | 问题已有临时解决 |
| W | 应该修复 | 有替代方案 |
| 建议 | 可以改进 | 优化类 |

---

## 与 log-analyzer-enhanced 的配合

- 本 Skill 定义 **输出格式**（报告模板、字段要求、严重性等级）
- log-analyzer-enhanced 定义 **分析过程规则**（认知增强、次生风险检查、跨会话扫描、冲突仲裁）
- 两者共同生效时，log-analyzer 应同时遵循分析规则和输出模板
- 若仅加载本 Skill，参照上方"独立使用时的最小要求"自行补充分析规则

migrate-to-skills

Convert 'Applied intelligently' Cursor rules (.cursor/rules/*.mdc) and slash commands (.cursor/commands/*.md) to Agent Skills format (.cursor/skills/). Use when the user wants to migrate rules or commands to skills, convert .mdc rules to SKILL.md format, or consolidate commands into the skills directory.

# Migrate Rules and Slash Commands to Skills

Convert Cursor rules ("Applied intelligently") and slash commands to Agent Skills format.

**CRITICAL: Preserve the exact body content. Do not modify, reformat, or "improve" it - copy verbatim.**

## Locations

| Level | Source | Destination |
|-------|--------|-------------|
| Project | `{workspaceFolder}/**/.cursor/rules/*.mdc`, `{workspaceFolder}/.cursor/commands/*.md` |
| User | `~/.cursor/commands/*.md` |

Notes:
- Cursor rules inside the project can live in nested directories. Be thorough in your search and use glob patterns to find them.
- Ignore anything in ~/.cursor/worktrees
- Ignore anything in ~/.cursor/skills-cursor. This is reserved for Cursor's internal built-in skills and is managed automatically by the system.

## Finding Files to Migrate

**Rules**: Migrate if rule has a `description` but NO `globs` and NO `alwaysApply: true`.

**Commands**: Migrate all - they're plain markdown without frontmatter.

## Conversion Format

### Rules: .mdc → SKILL.md

```markdown
# Before: .cursor/rules/my-rule.mdc
---
description: What this rule does
globs:
alwaysApply: false
---
# Title
Body content...
```

```markdown
# After: .cursor/skills/my-rule/SKILL.md
---
name: my-rule
description: What this rule does
---
# Title
Body content...
```

Changes: Add `name` field, remove `globs`/`alwaysApply`, keep body exactly.

### Commands: .md → SKILL.md

```markdown
# Before: .cursor/commands/commit.md
# Commit current work
Instructions here...
```

```markdown
# After: .cursor/skills/commit/SKILL.md
---
name: commit
description: Commit current work with standardized message format
disable-model-invocation: true
---
# Commit current work
Instructions here...
```

Changes: Add frontmatter with `name` (from filename), `description` (infer from content), and `disable-model-invocation: true`, keep body exactly.

**Note:** The `disable-model-invocation: true` field prevents the model from automatically invoking this skill. Slash commands are designed to be explicitly triggered by the user via the `/` menu, not automatically suggested by the model.

## Notes

- `name` must be lowercase with hyphens only
- `description` is critical for skill discovery
- Optionally delete originals after verifying migration works

### Migrate a Rule (.mdc → SKILL.md)

1. Read the rule file
2. Extract the `description` from the frontmatter
3. Extract the body content (everything after the closing `---` of the frontmatter)
4. Create the skill directory: `.cursor/skills/{skill-name}/` (skill name = filename without .mdc)
5. Write `SKILL.md` with new frontmatter (`name` and `description`) + the EXACT original body content (preserve all whitespace, formatting, code blocks verbatim)
6. Delete the original rule file

### Migrate a Command (.md → SKILL.md)

1. Read the command file
2. Extract description from the first heading (remove `#` prefix)
3. Create the skill directory: `.cursor/skills/{skill-name}/` (skill name = filename without .md)
4. Write `SKILL.md` with new frontmatter (`name`, `description`, and `disable-model-invocation: true`) + blank line + the EXACT original file content (preserve all whitespace, formatting, code blocks verbatim)
5. Delete the original command file

**CRITICAL: Copy the body content character-for-character. Do not reformat, fix typos, or "improve" anything.**

## Workflow

If you have the Task tool available:
DO NOT start to read all of the files yourself. That function should be delegated to the subagents. Your job is to dispatch the subagents for each category of files and wait for the results.

1. [ ] Create the skills directories if they don't exist (`.cursor/skills/` for project, `~/.cursor/skills/` for user)
2. Dispatch three fast general purpose subagents (NOT explore) in parallel to do the following steps for project rules (pattern: `{workspaceFolder}/**/.cursor/rules/*.mdc`), user commands (pattern: `~/.cursor/commands/*.md`), and project commands (pattern: `{workspaceFolder}/**/.cursor/commands/*.md`):
  I. [ ] Find files to migrate in the given pattern
  II. [ ] For rules, check if it's an "applied intelligently" rule (has `description`, no `globs`, no `alwaysApply: true`). Commands are always migrated. DO NOT use the terminal to read files. Use the read tool.
  III. [ ] Make a list of files to migrate. If empty, done.
  IV. [ ] For each file, read it, then write the new skill file preserving the body content EXACTLY. DO NOT use the terminal to write these files. Use the edit tool.
  V. [ ] Delete the original file. DO NOT use the terminal to delete these files. Use the delete tool.
  VI. [ ] Return a list of all the skill files that were migrated along with the original file paths.
3. [ ] Wait for all subagents to complete and summarize the results to the user. IMPORTANT: Make sure to let them know if they want to undo the migration, to ask you to.
4. [ ] If the user asks you to undo the migration, do the opposite of the above steps to restore the original files.


If you don't have the Task tool available:
1. [ ] Create the skills directories if they don't exist (`.cursor/skills/` for project, `~/.cursor/skills/` for user)
2. [ ] Find files to migrate in both project (`.cursor/`) and user (`~/.cursor/`) directories
3. [ ] For rules, check if it's an "applied intelligently" rule (has `description`, no `globs`, no `alwaysApply: true`). Commands are always migrated. DO NOT use the terminal to read files. Use the read tool.
4. [ ] Make a list of files to migrate. If empty, done.
5. [ ] For each file, read it, then write the new skill file preserving the body content EXACTLY. DO NOT use the terminal to write these files. Use the edit tool.
6. [ ] Delete the original file. DO NOT use the terminal to delete these files. Use the delete tool.
7. [ ] Summarize the results to the user. IMPORTANT: Make sure to let them know if they want to undo the migration, to ask you to.
8. [ ] If the user asks you to undo the migration, do the opposite of the above steps to restore the original files.

skill-mining

Skill/Rule 生成的标准流程与质量规范。skill-miner 执行日志模式挖掘、创建 Skill/Rule 时使用。

# Skill 挖掘输出规范

定义从 Agent 执行日志中提炼 Skill/Rule 的标准流程、质量检查清单和协作工作流。

## When to Use

- skill-miner 执行日志模式挖掘任务
- 需要创建或更新 Skill、Rule、Subagent
- 输入包含 log-analyzer 分析报告
- 需要确保输出与现有配置一致、可追溯

---

## 依赖与协作关系

本 Skill **定义标准流程与质量规范**，需要配合以下组件使用：

| 组件 | 路径 | 职责 | 必需 |
|------|------|------|------|
| `skill-miner-enhanced` Rule | `cross-evolution/rules/skill-miner-enhanced.md` | 定义**实施增强指引**（置信度标注、抽象层次、一致性检查、引用验证） | 是 |
| `evolution-history` Skill | `cross-evolution/skills/evolution-history/SKILL.md` | 进化轨迹追踪（项目进化用本地文件，自身进化用 git 仓库） | 是 |
| `log-analysis` Skill | `cross-evolution/skills/log-analysis/SKILL.md` | 上游输入：归纳 Agent 的标准化分析报告 | 可选 |

### 独立使用时的最小要求

若未加载 `skill-miner-enhanced` Rule，实施时需自行确保：
- 单日志来源标注 `待多项目验证`，多日志标注 `基于 N 次会话提炼`（Rule §1）
- 区分**领域特定**（→ Skill）与**可抽象通用**（→ Rule）的边界（Rule §2.2）
- 创建/更新前检查与已有 Rule/Skill 是否矛盾或重复（Rule §4）
- 引用现有组件前先搜索确认其存在（Rule §7）

---

## 标准流程

### Phase 0：历史咨询（前置步骤）

**必须**在正式分析前根据进化场景读取历史（详见 `evolution-history` Skill 的双模式设计）：

**项目进化模式**（改进目标项目的 Rule/Skill）：
1. 检查项目根目录 `evolution-history/` 是否存在
   - 不存在 → 首轮，跳过，直接进入 Phase 1
   - 存在 → 读取 `manifest.md` 和 `pattern-registry.md`（热区）
2. 执行循环检测

**自身进化模式**（改进 Agent 基础设施本身）：
1. 检查 `.cursor/evolution-store.json` 是否存在
   - 不存在 → 向用户询问 git 地址（不预设默认值）
   - `disabled: true` → 跳过，直接进入 Phase 1
   - 存在 → `git pull`，继续
2. 读取 `shared/universal-patterns.md`（跨项目通用知识）
3. 读取本项目 `projects/{project_id}/manifest.md` + `pattern-registry.md`（热区）
4. 执行循环检测

### Phase 1：收集与索引

1. 搜索 `**/agent-transcripts/*.txt`
2. 建立索引：会话主题、工具序列、涉及文件、领域关键词、最终结果
3. 若输入含 log-analyzer 报告，提取问题编号和建议清单

### Phase 2：模式识别与提案

1. 按 5 类模式识别：

   | 模式类型 | 判定标准 | 落地形式 |
   |----------|----------|----------|
   | **重复工作流** | 同一步骤序列在 ≥2 次会话中出现 | Skill（Workflow 模式） |
   | **领域知识** | 特定技术栈/业务的非通用知识（如 API 特性、配置陷阱） | Skill（Knowledge 章节） |
   | **专业角色** | Agent 需要特定人格/视角才能完成任务（如 Code Reviewer、DBA） | Subagent |
   | **错误预防** | 相同错误在 ≥2 次会话中重复出现，且有明确的预防规则 | Rule（alwaysApply 或 globs） |
   | **工具编排** | 多工具固定组合调用序列（如 Read→Grep→StrReplace 链式操作） | Skill（Workflow 模式）或 Rule |
2. **注册表比对**：将每个识别到的模式与 `pattern-registry.md` 中已有指纹比对
   - 匹配已有指纹 → 标注 `PAT-{XXX}`，状态按注册表规则更新
   - 无匹配 → 分配新 `PAT-{XXX}` ID，标记为「新发现」
3. 生成结构化提案：类型、动机、来源日志、出现频率、注册表 ID、实现方案、优先级
4. 引用 log-analyzer 问题编号（若适用）

### Phase 3：实施前检查

1. **一致性检查**：对照 `skill-miner-enhanced` 的检查清单
2. **已有规则检索**：搜索 `.cursor/rules/`、`.cursor/skills/` 是否已有相关规则
3. **历史冲突检查**：对照注册表，若某模式曾被修复又复现，分析前次修复失效原因
4. **提案与实施映射**：建立提案 ID → 最终文件的对应表

### Phase 4：实施与验证

1. 创建 Skill/Rule/Subagent，遵循 Cursor 格式规范
2. **Agent 文件结构合规检查**：增量更新 `.cursor/agents/*.md` 前，先 `Read` 全文检查是否存在重复 frontmatter（多段 `---` YAML 块）；若存在，本次编辑须一并合并/去重
3. 添加置信度标注
4. **编辑后自校验**（必须）：对声称修改的每个文件执行 `Read`，验证关键内容是否已持久化；若未落地，在实施报告中明确标注「需主流程补全」
5. 输出实施报告（含提案映射表、自校验结果、需主流程补全项）

### Phase 5：交叉验证

1. 检查新文件与现有配置是否冲突
2. 验证 frontmatter 格式正确
3. 输出最终报告

### Phase 6：历史更新（收尾步骤）

**项目进化模式**：
1. 分配 `PAT-{NNN}` ID，更新 `evolution-history/pattern-registry.md`
2. 创建 `evolution-history/rounds/round-{NNN}.md`
3. 更新 `evolution-history/manifest.md`
4. 执行淘汰

**自身进化模式**：
1. 分配 `PAT-{project_id}-{NNN}` ID，更新 Store 中的 `projects/{project_id}/pattern-registry.md`
2. 创建 `projects/{project_id}/rounds/round-{NNN}.md`
3. 更新 `projects/{project_id}/manifest.md`
4. 执行淘汰
5. 扫描是否有模式可晋升为通用知识（写入 `shared/universal-patterns.md`）
6. `git commit -m "[{project_id}] Round NNN: {摘要}" && git push`

---

## 质量检查清单

### 置信度

- [ ] Reference 中含 `基于 N 次会话提炼`
- [ ] 单日志来源时含 `待多项目验证`
- [ ] 含 `来源日志：<session-id>` 追溯

### 一致性

- [ ] 提案优先级与实施阶段一致，或已说明调整理由
- [ ] 与已有 Rule 无矛盾
- [ ] 与已有 Rule 无重复

### 可追溯性

- [ ] 提案清单含 log-analyzer 问题编号引用
- [ ] 实施报告含提案 ID → 最终文件映射表
- [ ] 实施报告含**本实例负责的归纳报告条目 ID**映射表（多实例并行时，标注 P-1/W-1/建议-1 等）
- [ ] 合并/未实施决策有说明

### 抽象层次

- [ ] 领域特定 vs 通用边界已明确
- [ ] 领域知识 → Skill，通用流程 → Rule

### 历史一致性

- [ ] 所有模式已与 pattern-registry 比对，标注 PAT-ID
- [ ] 复现模式已分析前次修复失效原因
- [ ] 本轮 Round Record 收敛指标已填写
- [ ] Manifest 轮次索引已更新

### Agent 文件结构合规

- [ ] 增量更新 agent 文件前已检查是否含重复 frontmatter
- [ ] 若有重复，本次编辑已一并合并/去重

### 实施报告自校验

- [ ] 对每个声称修改的文件已执行 `Read` 校验
- [ ] 报告含「自校验结果」：每个文件通过/未通过
- [ ] 若有未落地项，报告含「需主流程补全项」清单

---

## 实施报告输出模板

实施报告**必须**包含以下结构：

### 必填结构

```markdown
# 实施报告 — Round {N} [实例 {A|B}]（多实例并行时标注）

## 本实例负责的归纳报告条目 ID

| 归纳报告条目 ID | 对应实施任务 | 落地文件 |
|----------------|--------------|----------|
| P-1 | 增加编辑后自校验 | skill-miner.md |
| W-1 | ... | ... |

## 修改文件列表及改动摘要

| 文件 | 改动摘要 |
|------|----------|
| ... | ... |

## 自校验结果

| 文件 | 通过/未通过 | 备注 |
|------|-------------|------|
| ... | ... | ... |

## 需主流程补全项

（若自校验发现某文件未实际持久化，在此列出）
- 文件路径：预期改动摘要

## 提案 ID → 最终文件映射表

| 提案 ID | 最终文件 |
|---------|----------|
| ... | ... |
```

### 多实例并行时的命名约定

主流程应明确告知：本轮为 Round N，实例标识为 A/B；实施记录建议写入 `rounds/self-R00N-implementation-{A|B}.md`，PAT 编号按实例或主题区分，避免与轮次混淆（详见 `evolution-history` Skill 的并行写入策略）。

---

## 与归纳 Agent 协作工作流

```
log-analyzer 输出                     skill-miner 输入/输出
─────────────────────────────────────────────────────────────
P1–P3 严重问题     ──→  提炼为 Skill Known Issues 或 Rule
W1–W5 警告         ──→  提炼为 Rule 行为准则或 Skill 注意事项
优化建议           ──→  评估是否补充到 Skill「可选优化」章节
建议修复           ──→  若对应可复用模式，标注「建议 skill-miner 提炼」

skill-miner 提案   ──→  引用「来源：log-analyzer [P1]」形成双向追溯
```

### 重叠模式处理

| 场景 | 处理方式 |
|------|----------|
| 双方均识别同一模式 | 由单一真相源主导，另一方引用 |
| 归纳发现 + 进化提炼 | 进化的 Skill/Rule 中引用归纳的问题编号 |

update-cursor-settings

Modify Cursor/VSCode user settings in settings.json. Use when the user wants to change editor settings, preferences, configuration, themes, font size, tab size, format on save, auto save, keybindings, or any settings.json values.

# Updating Cursor Settings

This skill guides you through modifying Cursor/VSCode user settings. Use this when the user wants to change editor settings, preferences, configuration, themes, keybindings, or any `settings.json` values.

## Settings File Location

| OS | Path |
|----|------|
| macOS | ~/Library/Application Support/Cursor/User/settings.json |
| Linux | ~/.config/Cursor/User/settings.json |
| Windows | %APPDATA%\Cursor\User\settings.json |

## Before Modifying Settings

1. **Read the existing settings file** to understand current configuration
2. **Preserve existing settings** - only add/modify what the user requested
3. **Validate JSON syntax** before writing to avoid breaking the editor

## Modifying Settings

### Step 1: Read Current Settings

```typescript
// Read the settings file first
const settingsPath = "~/Library/Application Support/Cursor/User/settings.json";
// Use the Read tool to get current contents
```

### Step 2: Identify the Setting to Change

Common setting categories:
- **Editor**: `editor.fontSize`, `editor.tabSize`, `editor.wordWrap`, `editor.formatOnSave`
- **Workbench**: `workbench.colorTheme`, `workbench.iconTheme`, `workbench.sideBar.location`
- **Files**: `files.autoSave`, `files.exclude`, `files.associations`
- **Terminal**: `terminal.integrated.fontSize`, `terminal.integrated.shell.*`
- **Cursor-specific**: Settings prefixed with `cursor.` or `aipopup.`

### Step 3: Update the Setting

When modifying settings.json:
1. Parse the existing JSON (handle comments - VSCode settings support JSON with comments)
2. Add or update the requested setting
3. Preserve all other existing settings
4. Write back with proper formatting (2-space indentation)

### Example: Changing Font Size

If user says "make the font bigger":

```json
{
  "editor.fontSize": 16
}
```

### Example: Enabling Format on Save

If user says "format my code when I save":

```json
{
  "editor.formatOnSave": true
}
```

### Example: Changing Theme

If user says "use dark theme" or "change my theme":

```json
{
  "workbench.colorTheme": "Default Dark Modern"
}
```

## Important Notes

1. **JSON with Comments**: VSCode/Cursor settings.json supports comments (`//` and `/* */`). When reading, be aware comments may exist. When writing, preserve comments if possible.

2. **Restart May Be Required**: Some settings take effect immediately, others require reloading the window or restarting Cursor. Inform the user if a restart is needed.

3. **Backup**: For significant changes, consider mentioning the user can undo via Ctrl/Cmd+Z in the settings file or by reverting git changes if tracked.

4. **Workspace vs User Settings**:
   - User settings (what this skill covers): Apply globally to all projects
   - Workspace settings (`.vscode/settings.json`): Apply only to the current project

5. **Commit Attribution**: When the user asks about commit attribution, clarify whether they want to edit the **CLI agent** or the **IDE agent**. For the CLI agent, modify `~/.cursor/cli-config.json`. For the IDE agent, it is controlled from the UI at **Cursor Settings > Agent > Attribution** (not settings.json).

## Common User Requests → Settings

| User Request | Setting |
|--------------|---------|
| "bigger/smaller font" | `editor.fontSize` |
| "change tab size" | `editor.tabSize` |
| "format on save" | `editor.formatOnSave` |
| "word wrap" | `editor.wordWrap` |
| "change theme" | `workbench.colorTheme` |
| "hide minimap" | `editor.minimap.enabled` |
| "auto save" | `files.autoSave` |
| "line numbers" | `editor.lineNumbers` |
| "bracket matching" | `editor.bracketPairColorization.enabled` |
| "cursor style" | `editor.cursorStyle` |
| "smooth scrolling" | `editor.smoothScrolling` |

## Workflow

1. Read ~/Library/Application Support/Cursor/User/settings.json
2. Parse the JSON content
3. Add/modify the requested setting(s)
4. Write the updated JSON back to the file
5. Inform the user the setting has been changed and whether a reload is needed

create-rule

Create Cursor rules for persistent AI guidance. Use when the user wants to create a rule, add coding standards, set up project conventions, configure file-specific patterns, create RULE.md files, or asks about .cursor/rules/ or AGENTS.md.

# Creating Cursor Rules

Create project rules in `.cursor/rules/` to provide persistent context for the AI agent.

## Gather Requirements

Before creating a rule, determine:

1. **Purpose**: What should this rule enforce or teach?
2. **Scope**: Should it always apply, or only for specific files?
3. **File patterns**: If file-specific, which glob patterns?

### Inferring from Context

If you have previous conversation context, infer rules from what was discussed. You can create multiple rules if the conversation covers distinct topics or patterns. Don't ask redundant questions if the context already provides the answers.

### Required Questions

If the user hasn't specified scope, ask:
- "Should this rule always apply, or only when working with specific files?"

If they mentioned specific files and haven't provided concrete patterns, ask:
- "Which file patterns should this rule apply to?" (e.g., `**/*.ts`, `backend/**/*.py`)

It's very important that we get clarity on the file patterns.

Use the AskQuestion tool when available to gather this efficiently.

---

## Rule File Format

Rules are `.mdc` files in `.cursor/rules/` with YAML frontmatter:

```
.cursor/rules/
  typescript-standards.mdc
  react-patterns.mdc
  api-conventions.mdc
```

### File Structure

```markdown
---
description: Brief description of what this rule does
globs: **/*.ts  # File pattern for file-specific rules
alwaysApply: false  # Set to true if rule should always apply
---

# Rule Title

Your rule content here...
```

### Frontmatter Fields

| Field | Type | Description |
|-------|------|-------------|
| `description` | string | What the rule does (shown in rule picker) |
| `globs` | string | File pattern - rule applies when matching files are open |
| `alwaysApply` | boolean | If true, applies to every session |

---

## Rule Configurations

### Always Apply

For universal standards that should apply to every conversation:

```yaml
---
description: Core coding standards for the project
alwaysApply: true
---
```

### Apply to Specific Files

For rules that apply when working with certain file types:

```yaml
---
description: TypeScript conventions for this project
globs: **/*.ts
alwaysApply: false
---
```

---

## Best Practices

### Keep Rules Concise

- **Under 50 lines**: Rules should be concise and to the point
- **One concern per rule**: Split large rules into focused pieces
- **Actionable**: Write like clear internal docs
- **Concrete examples**: Ideally provide concrete examples of how to fix issues

---

## Example Rules

### TypeScript Standards

```markdown
---
description: TypeScript coding standards
globs: **/*.ts
alwaysApply: false
---

# Error Handling

\`\`\`typescript
// ❌ BAD
try {
  await fetchData();
} catch (e) {}

// ✅ GOOD
try {
  await fetchData();
} catch (e) {
  logger.error('Failed to fetch', { error: e });
  throw new DataFetchError('Unable to retrieve data', { cause: e });
}
\`\`\`
```

### React Patterns

```markdown
---
description: React component patterns
globs: **/*.tsx
alwaysApply: false
---

# React Patterns

- Use functional components
- Extract custom hooks for reusable logic
- Colocate styles with components
```

---

## Checklist

- [ ] File is `.mdc` format in `.cursor/rules/`
- [ ] Frontmatter configured correctly
- [ ] Content under 500 lines
- [ ] Includes concrete examples

create-skill

Guides users through creating effective Agent Skills for Cursor. Use when the user wants to create, write, or author a new skill, or asks about skill structure, best practices, or SKILL.md format.

# Creating Skills in Cursor

This skill guides you through creating effective Agent Skills for Cursor. Skills are markdown files that teach the agent how to perform specific tasks: reviewing PRs using team standards, generating commit messages in a preferred format, querying database schemas, or any specialized workflow.

## Before You Begin: Gather Requirements

Before creating a skill, gather essential information from the user about:

1. **Purpose and scope**: What specific task or workflow should this skill help with?
2. **Target location**: Should this be a personal skill (~/.cursor/skills/) or project skill (.cursor/skills/)?
3. **Trigger scenarios**: When should the agent automatically apply this skill?
4. **Key domain knowledge**: What specialized information does the agent need that it wouldn't already know?
5. **Output format preferences**: Are there specific templates, formats, or styles required?
6. **Existing patterns**: Are there existing examples or conventions to follow?

### Inferring from Context

If you have previous conversation context, infer the skill from what was discussed. You can create skills based on workflows, patterns, or domain knowledge that emerged in the conversation.

### Gathering Additional Information

If you need clarification, use the AskQuestion tool when available:

```
Example AskQuestion usage:
- "Where should this skill be stored?" with options like ["Personal (~/.cursor/skills/)", "Project (.cursor/skills/)"]
- "Should this skill include executable scripts?" with options like ["Yes", "No"]
```

If the AskQuestion tool is not available, ask these questions conversationally.

---

## Skill File Structure

### Directory Layout

Skills are stored as directories containing a `SKILL.md` file:

```
skill-name/
├── SKILL.md              # Required - main instructions
├── reference.md          # Optional - detailed documentation
├── examples.md           # Optional - usage examples
└── scripts/              # Optional - utility scripts
    ├── validate.py
    └── helper.sh
```

### Storage Locations

| Type | Path | Scope |
|------|------|-------|
| Personal | ~/.cursor/skills/skill-name/ | Available across all your projects |
| Project | .cursor/skills/skill-name/ | Shared with anyone using the repository |

**IMPORTANT**: Never create skills in `~/.cursor/skills-cursor/`. This directory is reserved for Cursor's internal built-in skills and is managed automatically by the system.

### SKILL.md Structure

Every skill requires a `SKILL.md` file with YAML frontmatter and markdown body:

```markdown
---
name: your-skill-name
description: Brief description of what this skill does and when to use it
---

# Your Skill Name

## Instructions
Clear, step-by-step guidance for the agent.

## Examples
Concrete examples of using this skill.
```

### Required Metadata Fields

| Field | Requirements | Purpose |
|-------|--------------|---------|
| `name` | Max 64 chars, lowercase letters/numbers/hyphens only | Unique identifier for the skill |
| `description` | Max 1024 chars, non-empty | Helps agent decide when to apply the skill |

---

## Writing Effective Descriptions

The description is **critical** for skill discovery. The agent uses it to decide when to apply your skill.

### Description Best Practices

1. **Write in third person** (the description is injected into the system prompt):
   - ✅ Good: "Processes Excel files and generates reports"
   - ❌ Avoid: "I can help you process Excel files"
   - ❌ Avoid: "You can use this to process Excel files"

2. **Be specific and include trigger terms**:
   - ✅ Good: "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
   - ❌ Vague: "Helps with documents"

3. **Include both WHAT and WHEN**:
   - WHAT: What the skill does (specific capabilities)
   - WHEN: When the agent should use it (trigger scenarios)

### Description Examples

```yaml
# PDF Processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

# Excel Analysis
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

# Git Commit Helper
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

# Code Review
description: Review code for quality, security, and best practices following team standards. Use when reviewing pull requests, code changes, or when the user asks for a code review.
```

---

## Core Authoring Principles

### 1. Concise is Key

The context window is shared with conversation history, other skills, and requests. Every token competes for space.

**Default assumption**: The agent is already very smart. Only add context it doesn't already have.

Challenge each piece of information:
- "Does the agent really need this explanation?"
- "Can I assume the agent knows this?"
- "Does this paragraph justify its token cost?"

**Good (concise)**:
```markdown
## Extract PDF text

Use pdfplumber for text extraction:

\`\`\`python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
\`\`\`
```

**Bad (verbose)**:
```markdown
## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but we
recommend pdfplumber because it's easy to use and handles most cases well...
```

### 2. Keep SKILL.md Under 500 Lines

For optimal performance, the main SKILL.md file should be concise. Use progressive disclosure for detailed content.

### 3. Progressive Disclosure

Put essential information in SKILL.md; detailed reference material in separate files that the agent reads only when needed.

```markdown
# PDF Processing

## Quick start
[Essential instructions here]

## Additional resources
- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)
```

**Keep references one level deep** - link directly from SKILL.md to reference files. Deeply nested references may result in partial reads.

### 4. Set Appropriate Degrees of Freedom

Match specificity to the task's fragility:

| Freedom Level | When to Use | Example |
|---------------|-------------|---------|
| **High** (text instructions) | Multiple valid approaches, context-dependent | Code review guidelines |
| **Medium** (pseudocode/templates) | Preferred pattern with acceptable variation | Report generation |
| **Low** (specific scripts) | Fragile operations, consistency critical | Database migrations |

---

## Common Patterns

Skill 编写有 5 种常见设计模式，根据任务特征选择：

| 模式 | 适用场景 | 核心思路 |
|------|----------|----------|
| **Template** | 需要固定输出格式 | 提供 markdown 模板 |
| **Examples** | 输出质量依赖示例 | 给出 Input→Output 对 |
| **Workflow** | 多步骤操作 | Checklist + 分步指令 |
| **Conditional Workflow** | 有分支决策点 | 决策树 + 分支流程 |
| **Feedback Loop** | 质量关键型任务 | 操作→验证→修复循环 |

**Utility Scripts**: 预制脚本比生成代码更可靠、更省 token。明确标注脚本是用于 **execute** 还是 **read**。

详细示例和代码模板见 [patterns-reference.md](patterns-reference.md)

---

## Anti-Patterns to Avoid

| # | 反模式 | 正确做法 |
|---|--------|----------|
| 1 | Windows 风格路径 (`scripts\helper.py`) | 使用正斜杠 `scripts/helper.py` |
| 2 | 罗列过多选项让 Agent 困惑 | 给默认方案 + 一个 escape hatch |
| 3 | 包含时效性信息 | 用"当前方法"+"旧方法(deprecated)"分区 |
| 4 | 术语不一致 | 全文统一用一个术语 |
| 5 | 模糊的 Skill 名称 (`helper`, `utils`) | 用动作+对象命名 (`processing-pdfs`) |

详细示例见 [patterns-reference.md](patterns-reference.md)

---

## Skill Creation Workflow

When helping a user create a skill, follow this process:

### Phase 1: Discovery

Gather information about:
1. The skill's purpose and primary use case
2. Storage location (personal vs project)
3. Trigger scenarios
4. Any specific requirements or constraints
5. Existing examples or patterns to follow

If you have access to the AskQuestion tool, use it for efficient structured gathering. Otherwise, ask conversationally.

### Phase 2: Design

1. Draft the skill name (lowercase, hyphens, max 64 chars)
2. Write a specific, third-person description
3. Outline the main sections needed
4. Identify if supporting files or scripts are needed

### Phase 3: Implementation

1. Create the directory structure
2. Write the SKILL.md file with frontmatter
3. Create any supporting reference files
4. Create any utility scripts if needed

### Phase 4: Verification

1. Verify the SKILL.md is under 500 lines
2. Check that the description is specific and includes trigger terms
3. Ensure consistent terminology throughout
4. Verify all file references are one level deep
5. Test that the skill can be discovered and applied

---

## Complete Example

Here's a complete example of a well-structured skill:

**Directory structure:**
```
code-review/
├── SKILL.md
├── STANDARDS.md
└── examples.md
```

**SKILL.md:**
```markdown
---
name: code-review
description: Review code for quality, security, and maintainability following team standards. Use when reviewing pull requests, examining code changes, or when the user asks for a code review.
---

# Code Review

## Quick Start

When reviewing code:

1. Check for correctness and potential bugs
2. Verify security best practices
3. Assess code readability and maintainability
4. Ensure tests are adequate

## Review Checklist

- [ ] Logic is correct and handles edge cases
- [ ] No security vulnerabilities (SQL injection, XSS, etc.)
- [ ] Code follows project style conventions
- [ ] Functions are appropriately sized and focused
- [ ] Error handling is comprehensive
- [ ] Tests cover the changes

## Providing Feedback

Format feedback as:
- 🔴 **Critical**: Must fix before merge
- 🟡 **Suggestion**: Consider improving
- 🟢 **Nice to have**: Optional enhancement

## Additional Resources

- For detailed coding standards, see [STANDARDS.md](STANDARDS.md)
- For example reviews, see [examples.md](examples.md)
```

---

## Summary Checklist

Before finalizing a skill, verify:

### Core Quality
- [ ] Description is specific and includes key terms
- [ ] Description includes both WHAT and WHEN
- [ ] Written in third person
- [ ] SKILL.md body is under 500 lines
- [ ] Consistent terminology throughout
- [ ] Examples are concrete, not abstract

### Structure
- [ ] File references are one level deep
- [ ] Progressive disclosure used appropriately
- [ ] Workflows have clear steps
- [ ] No time-sensitive information

### If Including Scripts
- [ ] Scripts solve problems rather than punt
- [ ] Required packages are documented
- [ ] Error handling is explicit and helpful
- [ ] No Windows-style paths

create-subagent

Create custom subagents for specialized AI tasks. Use when the user wants to create a new type of subagent, set up task-specific agents, configure code reviewers, debuggers, or domain-specific assistants with custom prompts.

# Creating Custom Subagents

This skill guides you through creating custom subagents for Cursor. Subagents are specialized AI assistants that run in isolated contexts with custom system prompts.

## When to Use Subagents

Subagents help you:
- **Preserve context** by isolating exploration from your main conversation
- **Specialize behavior** with focused system prompts for specific domains
- **Reuse configurations** across projects with user-level subagents

### Inferring from Context

If you have previous conversation context, infer the subagent's purpose and behavior from what was discussed. Create the subagent based on specialized tasks or workflows that emerged in the conversation.

## Subagent Locations

| Location | Scope | Priority |
|----------|-------|----------|
| `.cursor/agents/` | Current project | Higher |
| `~/.cursor/agents/` | All your projects | Lower |

When multiple subagents share the same name, the higher-priority location wins.

**Project subagents** (`.cursor/agents/`): Ideal for codebase-specific agents. Check into version control to share with your team.

**User subagents** (`~/.cursor/agents/`): Personal agents available across all your projects.

## Subagent File Format

Create a `.md` file with YAML frontmatter and a markdown body (the system prompt):

```markdown
---
name: code-reviewer
description: Reviews code for quality and best practices
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
```

### Required Fields

| Field | Description |
|-------|-------------|
| `name` | Unique identifier (lowercase letters and hyphens only) |
| `description` | When to delegate to this subagent (be specific!) |

## Writing Effective Descriptions

The description is **critical** - the AI uses it to decide when to delegate.

```yaml
# ❌ Too vague
description: Helps with code

# ✅ Specific and actionable
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
```

Include "use proactively" to encourage automatic delegation.

## Example Subagents

### Code Reviewer

```markdown
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.
```

### Debugger

```markdown
---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.
```

### Data Scientist

```markdown
---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.
```

## Subagent Creation Workflow

### Step 1: Decide the Scope

- **Project-level** (`.cursor/agents/`): For codebase-specific agents shared with team
- **User-level** (`~/.cursor/agents/`): For personal agents across all projects

### Step 2: Create the File

```bash
# For project-level
mkdir -p .cursor/agents
touch .cursor/agents/my-agent.md

# For user-level
mkdir -p ~/.cursor/agents
touch ~/.cursor/agents/my-agent.md
```

### Step 3: Define Configuration

Write the frontmatter with the required fields (`name` and `description`).

### Step 4: Write the System Prompt

The body becomes the system prompt. Be specific about:
- What the agent should do when invoked
- The workflow or process to follow
- Output format and structure
- Any constraints or guidelines

### Step 5: Test the Agent

Ask the AI to use your new agent:

```
Use the my-agent subagent to [task description]
```

## Best Practices

1. **Design focused subagents**: Each should excel at one specific task
2. **Write detailed descriptions**: Include trigger terms so the AI knows when to delegate
3. **Check into version control**: Share project subagents with your team
4. **Use proactive language**: Include "use proactively" in descriptions

## Troubleshooting

### Subagent Not Found
- Ensure file is in `.cursor/agents/` or `~/.cursor/agents/`
- Check file has `.md` extension
- Verify YAML frontmatter syntax is valid

evolution-history

进化历史追踪与循环检测。cross-evolution 框架执行时使用，支持两种模式：项目进化（本地文件）和自身进化（独立 git 仓库 + 跨项目共享）。

# 进化历史追踪

## 核心问题

交叉检查解决了"谁来分析自己"的自指问题，但缺少**时间维度的记忆**。没有轨迹，系统会陷入重发现循环、振荡和浅层收敛。

## 两种进化场景

进化有两个本质不同的场景，**不能混为一谈**：

| | 项目进化 | 自身进化 |
|---|---|---|
| **目的** | 改进某个目标项目的 Rule/Skill | 改进 Agent 基础设施本身（meta skill/rule） |
| **分析对象** | 目标项目的 agent-transcripts | 多个项目中 Agent 的行为模式 |
| **受益范围** | 仅当前项目 | 所有使用该 Agent 的项目 |
| **历史存储** | **项目本地文件** | **独立 git 仓库** |
| **是否共享** | 不需要 | 需要，多项目/多用户贡献 |
| **Pattern ID** | `PAT-{NNN}` | `PAT-{project_id}-{NNN}` |

### 判定规则

Agent 根据当前任务性质自动判定模式：

- **项目进化**：用户要求"分析这个项目的日志并改进 Rule/Skill" → 本地模式
- **自身进化**：用户要求"对 Agent 自身进行交叉进化" / "启动 cross-evolution" → git 模式

---

## 模式 A：项目进化（本地文件）

### 存储结构

在目标项目**根目录**维护（与 `agent-transcripts/` 同级）：

```
{project-root}/
├── agent-transcripts/          # Agent 执行日志（已有）
├── evolution-history/          # 进化历史（本地文件，不需要 git）
│   ├── manifest.md             # 总览（热区，≤50 行）
│   ├── pattern-registry.md     # 活跃模式（热区，≤30 条）
│   ├── rounds/                 # 近期 5 轮记录（热区）
│   └── archive/                # 冷区
│       ├── rounds/
│       └── patterns-archived.md
└── .cursor/                    # 静态配置（不放状态数据）
```

### 执行协议

**每轮开始时**：
1. 检查 `evolution-history/` 是否存在
   - 不存在 → 首轮，创建目录结构，跳过历史咨询
   - 存在 → 读取 `manifest.md` 和 `pattern-registry.md`（热区），执行循环检测
2. 进入交叉分析

**每轮结束时**：
1. 分配 `PAT-{NNN}` ID，更新注册表
2. 写入本轮 Round Record
3. 更新 manifest 和收敛趋势
4. 执行淘汰（manifest 滚动 5 轮、归档模式、旧 round records 移入 `archive/`）

**无 git 操作，无用户交互，无共享。简单直接。**

---

## 模式 B：自身进化（独立 git 仓库）

### 何时使用

当 Agent 对**自身基础设施**（meta skill、meta rule、cross-evolution 框架本身）进行进化迭代时：
- 进化产物是跨项目通用的（所有使用该 Agent 的项目受益）
- 需要多个项目的日志作为输入来提炼通用模式
- 需要多用户协作贡献进化知识

### 存储结构（Evolution Store）

独立 git 仓库，不嵌入任何业务项目：

```
evolution-store/                          # 独立 git 仓库
├── shared/                               # 跨项目共享知识
│   └── universal-patterns.md             # ≥2 项目验证的通用模式
└── projects/                             # 项目隔离区
    └── {project-id}/                     # 各项目的进化记录
        ├── manifest.md                   # 热区
        ├── pattern-registry.md           # 热区
        ├── rounds/                       # 热区
        └── archive/                      # 冷区
```

### Store 发现与用户交互

**当配置文件 `.cursor/evolution-store.json` 不存在时**，Agent 必须主动询问用户：

使用 AskQuestion 工具（若可用）或对话方式：

**问题 1**：是否启用 Evolution Store？

| 选项 | 后续动作 |
|------|----------|
| **已有仓库，提供 git 地址** | 问 git remote → 问 project_id → 克隆 → 写配置 |
| **没有，帮我新建一个** | 问 project_id → 本地 init → 写配置 → 提示用户自行 push |
| **本次跳过** | 不写配置，本轮不使用历史，下次再问 |
| **永久跳过** | 写 `{ "disabled": true }`，不再询问 |

**禁止**硬编码任何默认 git 地址。所有地址由用户提供。

### 配置文件

`.cursor/evolution-store.json`：

```json
{
  "remote": "<用户提供>",
  "local_path": "<用户指定>",
  "project_id": "<用户提供>"
}
```

### 执行协议

**每轮开始时**：
1. 检查 `.cursor/evolution-store.json`
   - 不存在 → 执行用户交互
   - `disabled: true` → 跳过，直接进入分析
   - 存在 → 继续
2. `git pull --rebase --autostash`
3. 读取 `shared/universal-patterns.md`（跨项目通用知识）
4. 读取本项目 `projects/{project_id}/manifest.md` + `pattern-registry.md`
5. 执行循环检测
6. 进入交叉分析

**每轮结束时**：
1. 分配 `PAT-{project_id}-{NNN}` ID，更新注册表
2. 写入 Round Record，更新 manifest
3. 执行淘汰
4. 扫描是否有模式可晋升为通用知识
5. `git commit -m "[{project_id}] Round NNN: {摘要}" && git push`

### 跨项目共享

详见 [sharing-protocol.md](sharing-protocol.md)。核心规则：
- 同一指纹在 ≥2 个 project_id 中独立出现 → 晋升至 `shared/universal-patterns.md`
- 每轮开始时读取 `shared/`，将通用模式纳入分析基线

---

## 共享协议（两种模式通用）

以下模板、规则和检测协议**两种模式完全共用**，仅 Pattern ID 格式和存储路径有差异。

### Manifest 模板

```markdown
# 进化总览

## 元信息

| 字段 | 值 |
|------|-----|
| 首轮日期 | {date} |
| 最近轮次 | Round {N}, {date} |
| 总轮次 | {N} |
| 活跃模式数 | {N} |

## 最近轮次（滚动窗口，保留 5 轮）

| 轮次 | 日期 | 新发现 | 已解决 | 复现 | 净变化 |
|------|------|--------|--------|------|--------|

> 更早轮次见 archive/

## 收敛趋势（基于最近 3 轮）

| 指标 | 最近 3 轮 | 趋势 |
|------|-----------|------|
```

### Pattern Registry 模板

热区文件，仅含 活跃/已缓释/复现/已解决 状态的模式：

```markdown
# 模式注册表（活跃）

> 已归档模式见 archive/patterns-archived.md

| ID | 指纹描述 | 类型 | 首现 | 末现 | 次数 | 状态 | 关联文件 |
|----|----------|------|------|------|------|------|----------|
```

### 状态生命周期

```
新发现 → 活跃 → 已缓释 → 已解决 → 归档
                    ↑          │
                    └── 复现 ←─┘
```

| 状态 | 转换条件 | 位置 |
|------|----------|------|
| **活跃** | 首次发现 | 热区 |
| **已缓释** | 有 workaround | 热区 |
| **已解决** | 修复后 1 轮未复现 | 热区 |
| **复现** | 已解决后再次出现 | 热区 |
| **归档** | 已解决 + 3 轮无复现 | 冷区 |

### 指纹编写规范

1. **格式**：`[类型] 动词 + 对象 + 条件`
2. **示例**：`[错误预防] ESM/CJS 混用导致模块加载失败`
3. **粒度**：一个指纹 = 一个可独立修复的问题

### 淘汰规则

| 规则 | 条件 | 动作 |
|------|------|------|
| Manifest 滚动 | >5 轮 | 最早行移入 `archive/` |
| 模式归档 | 已解决 + 3 轮无复现 | 从 registry 移入 `archive/patterns-archived.md` |
| Round Record 归档 | 超过 5 轮 | 从 `rounds/` 移入 `archive/rounds/` |

---

## 多实例并行约定

当主流程同时启动多个 skill-miner 实例（如 Round N 的实例 A、B）时：

### 轮次与实例编号约定

| 概念 | 约定 |
|------|------|
| **轮次** | Round 编号由主流程统一分配，所有并行实例同属同一轮（如 Round 001） |
| **实例标识** | 主流程在 prompt 中明确告知「本轮为 Round N，你为并行实例 N-A / N-B」 |
| **实施记录命名** | 建议 `rounds/self-R00N-implementation-A.md` / `-B.md`，避免两实例写入同名文件 |
| **PAT 编号** | 按实例或主题域区分（如实例 A 用 PAT-001～006，实例 B 用 PAT-007～014），在 pattern-registry 中注明所属实例，避免与「轮次」混淆 |

### 并行写入策略

共享文件（`manifest.md`、`pattern-registry.md`）由多实例并发更新时存在竞态风险。可选策略：

| 策略 | 适用场景 | 规则 |
|------|----------|------|
| **主流程统一写入** | 推荐 | 各 skill-miner 实例仅产出实施报告；主流程汇总后，由主流程统一写入 manifest 与 pattern-registry |
| **合并规则** | 若必须由实例写入 | 仅追加/合并，不覆盖：manifest 追加新轮次行、pattern-registry 追加新 PAT 行；禁止 `Write` 全文件覆盖；写入前 `Read` 当前内容，增量合并后 `Write` |

主流程应在分配任务时明确采用何种策略；若未明确，skill-miner 默认仅写入本实例的 round record，不直接修改 manifest/pattern-registry。

---

## 循环检测协议（两种模式通用）

每轮读取历史之后、分析之前执行：

### 1. 复现检测

扫描 registry：若某模式状态为「已解决」但本轮再次出现 → 改为「复现」，分析修复失效原因。

### 2. 振荡检测

对比最近 2 轮进化动作：若同一文件被连续做矛盾修改 → 标记「振荡」，冻结该文件。

### 3. 停滞检测

最近 3 轮收敛指标：净未解决连续不变 → 「停滞」。新发现连续 3 轮为 0 且净未解决为 0 → 「已收敛」。

### 4. 升级阈值

| 条件 | 动作 |
|------|------|
| 模式出现 ≥3 次未解决 | 升级 P0 |
| 振荡 ≥2 次 | 冻结文件，人工介入 |
| 停滞 ≥3 轮 | 暂停进化或重评估 |