skill-evolution

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Evolution

技能进化

This skill makes the skills library evolve based on real development signals without auto-editing skills. The default output is a patch suggestion only.

本技能可基于真实开发信号推动技能库进化，且不会自动编辑技能。默认仅输出补丁建议。

Why it exists (solving "too passive")

设计初衷（解决“过于被动”的问题）

Default hooks can only "log events" without automatically consolidating experience into skills.

The goal of this skill is to turn retrospectives into a fixed closing action:

At the end of each "big task", spend 60 seconds on Q&A confirmation: whether to optimize skills and which areas to prioritize
When user chooses "yes to optimize", use
```
skill-improver
```
to generate minimal patch suggestions based on real run artifacts (still no auto-editing of skill library)

默认的Hooks仅能“记录事件”，无法自动将经验整合到技能中。

本技能的目标是将回顾总结转化为固定的收尾动作：

在每个“大型任务”结束时，用60秒进行问答确认：是否要优化技能，以及优先优化哪些领域
当用户选择“需要优化”时，基于真实运行工件（run artifacts），使用
```
skill-improver
```
生成最小化补丁建议（仍不会自动编辑技能库）

Default strategy

默认策略

Capture context and failures into run artifacts
Generate evolution candidates
Use
```
skill-improver
```
to propose a minimal patch
Human reviews and applies the patch

捕获上下文和失败信息并写入运行工件
生成进化候选方案
借助
```
skill-improver
```
提出最小化补丁建议
人工审核并应用补丁

Global hooks (recommended)

全局Hooks（推荐配置）

Hooks live in:

~/.claude/skills/skill-evolution/hooks/

Add to your global settings (or project settings) so hooks run automatically.

Example (merge into

~/.claude/settings.json

<project>/.claude/settings.json

Hooks存放路径：

~/.claude/skills/skill-evolution/hooks/

将其添加到全局设置（或项目设置）中，即可让Hooks自动运行。

示例（合并到

~/.claude/settings.json

或

<project>/.claude/settings.json

）：

Evolution settings

进化系统配置

Configure behavior via

~/.claude/skills/skill-evolution/hooks/settings.json

json

{
  "min_fail_count": 2,
  "ignore_tool_errors": true,
  "noise_filters": {
    "ignore_patterns": [
      "typescript: type.*already exists",
      "eslint:.*no-unused-vars.*react",
      "prettier:.*prettier-ignore"
    ],
    "max_failures_per_run": 20,
    "recent_only": true,
    "recent_window_minutes": 60
  },
  "output_format": {
    "summary_only": false,
    "include_context": true,
    "include_recent_failures": 20,
    "sort_by": "frequency"
  }
}

Settings explanation:

```
min_fail_count
```
: Minimum occurrences of a single error type before generating a candidate
```
ignore_tool_errors
```
: Whether to ignore tool-level errors (vs user code errors)
```
noise_filters.ignore_patterns
```
: List of regex patterns to ignore
```
max_failures_per_run
```
: Maximum failures to record per session (prevent explosion)
```
recent_only
```
: Only look at failures within recent time window
```
recent_window_minutes
```
: Only count failures within the last N minutes
```
output_format
```
: Controls evolution-candidates.md output format

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/skills/skill-evolution/hooks/pre-tool.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/skills/skill-evolution/hooks/post-bash.sh \"$TOOL_OUTPUT\" \"$EXIT_CODE\""
          }
        ]
      },
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/skills/skill-evolution/hooks/post-tool.sh \"$TOOL_OUTPUT\" \"$EXIT_CODE\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/skills/skill-evolution/hooks/session-end.sh"
          }
        ]
      }
    ]
  }
}

通过

~/.claude/skills/skill-evolution/hooks/settings.json

配置行为：

json

{
  "min_fail_count": 2,
  "ignore_tool_errors": true,
  "noise_filters": {
    "ignore_patterns": [
      "typescript: type.*already exists",
      "eslint:.*no-unused-vars.*react",
      "prettier:.*prettier-ignore"
    ],
    "max_failures_per_run": 20,
    "recent_only": true,
    "recent_window_minutes": 60
  },
  "output_format": {
    "summary_only": false,
    "include_context": true,
    "include_recent_failures": 20,
    "sort_by": "frequency"
  }
}

配置项说明：

```
min_fail_count
```
: 生成候选方案前，单一错误类型需出现的最小次数
```
ignore_tool_errors
```
: 是否忽略工具级错误（区别于用户代码错误）
```
noise_filters.ignore_patterns
```
: 需忽略的正则表达式列表
```
max_failures_per_run
```
: 每次会话记录的最大失败次数（防止数据爆炸）
```
recent_only
```
: 仅考虑最近时间窗口内的失败信息
```
recent_window_minutes
```
: 仅统计最近N分钟内的失败次数
```
output_format
```
: 控制
```
evolution-candidates.md
```
的输出格式

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/skills/skill-evolution/hooks/pre-tool.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/skills/skill-evolution/hooks/post-bash.sh \"$TOOL_OUTPUT\" \"$EXIT_CODE\""
          }
        ]
      },
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/skills/skill-evolution/hooks/post-tool.sh \"$TOOL_OUTPUT\" \"$EXIT_CODE\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/skills/skill-evolution/hooks/session-end.sh"
          }
        ]
      }
    ]
  }
}

Run artifacts

运行工件

Hooks write to project-local run folders:

<project-root>/runs/evolution/<run_id>/
  logs/
    events.jsonl
    failures.jsonl
    state.json
    context.json
  evolution-candidates.md
  evolution-review.md

run_id

is stored in

<project-root>/runs/evolution/.current

so all hooks in a session write to the same run.

Hooks会将数据写入项目本地的运行文件夹：

<project-root>/runs/evolution/<run_id>/
  logs/
    events.jsonl
    failures.jsonl
    state.json
    context.json
  evolution-candidates.md
  evolution-review.md

run_id

会存储在

<project-root>/runs/evolution/.current

中，以便同一会话中的所有Hooks写入到同一运行目录。

Evolution checkpoint (default action at end of big tasks)

进化检查点（大型任务结束时的默认操作）

When you have just completed a "deliverable big task" (e.g., you have already written

final.md

or filled the run’s

tasks.md

Delivery summary), you must do a brief retrospective when closing, and give the choice to the user.

In the conversation, ask only 3 questions (prefer multiple choice to reduce cost):

Do you want to optimize skills based on this run?
- A. Yes, propose a patch now (recommend using
```
skill-improver
```
  first to generate minimal patch)
- B. Record the issue first, optimize later
- C. Not needed
What was the biggest blocker this time?
- A. Missing input/context fields (need clearer I/O contracts)
- B. Unclear plan/granularity too large (need to split or clarify validation steps)
- C. Environment/dependency/command issues (need scripting or fixed commands)
- D. UI/design iterations (need clearer design-system or UI subtask splitting)
- E. External service/permissions/configuration (need clearer confirmation points and verification)
- F. Other (explain in one sentence)
Which direction do you want to prioritize for optimization?
- A. I/O contracts: Fix artifact names, fields, paths
- B. Index/summary: Less context, better resume navigation (proposal/tasks)
- C. Scripts/templates: Turn repetitive steps into deterministic scripts
- D. Confirmation points: Reduce risky actions, confirm earlier/more clearly

Execution rules:

If user chooses 1A: Immediately run
```
skill-improver
```
, only give
```
run_dir
```
path as input (don't paste logs into conversation)
If user chooses 1B: Write "blocker + desired optimization direction" to
```
evolution-review.md
```
(or corresponding workflow run's
```
final.md
```
/
```
tasks.md
```
), process collectively next time
If user chooses 1C: Don't interrupt, just end (but still keep run artifacts for future retrospectives)

当你刚完成一个“可交付的大型任务”（例如已编写

final.md

或填写了运行任务的

tasks.md

中的交付摘要），在收尾时必须进行简短的回顾总结，并将选择权交给用户。

在对话中，仅需询问以下3个问题（优先使用选择题以降低沟通成本）：

是否要基于本次运行优化技能？
- A. 是，现在生成补丁建议（推荐先使用
```
skill-improver
```
  生成最小化补丁）
- B. 先记录问题，后续再优化
- C. 无需优化
本次任务最大的阻碍是什么？
- A. 缺少输入/上下文字段（需要更清晰的I/O契约）
- B. 计划不明确/粒度太大（需要拆分或明确验证步骤）
- C. 环境/依赖/命令问题（需要脚本化或固定命令）
- D. UI/设计迭代（需要更清晰的设计系统或UI子任务拆分）
- E. 外部服务/权限/配置问题（需要更清晰的确认点和验证步骤）
- F. 其他（用一句话说明）
你希望优先优化哪个方向？
- A. I/O契约：修复工件名称、字段、路径
- B. 索引/摘要：减少冗余上下文，优化恢复导航（提案/任务）
- C. 脚本/模板：将重复步骤转化为确定性脚本
- D. 确认点：减少高风险操作，更早/更明确地进行确认

执行规则：

若用户选择1A：立即运行
```
skill-improver
```
，仅提供
```
run_dir
```
路径作为输入（不要将日志粘贴到对话中）
若用户选择1B：将“阻碍问题 + 期望优化方向”写入
```
evolution-review.md
```
（或对应工作流运行的
```
final.md
```
/
```
tasks.md
```
），后续统一处理
若用户选择1C：无需中断，直接结束会话（但仍保留运行工件供未来回顾使用）

When to evolve (Ship Faster focus)

进化触发场景（聚焦Ship-Faster目标）

Next.js upgrade or migration issue solved
Guardrails problem fixed (lint/typecheck/build)
Supabase error or migration pattern learned
Stripe setup or billing flow resolved
Vercel deploy or GitHub CI issue resolved
AI SEO setup or indexing issue solved

解决Next.js升级或迁移问题后
修复了防护机制问题（lint/类型检查/构建）
掌握了Supabase错误或迁移模式后
完成Stripe配置或计费流程后
解决Vercel部署或GitHub CI问题后
完成AI SEO配置或索引问题后

How to evolve

进化流程

Hooks create

evolution-candidates.md

evolution-review.md

with the latest signals.

At the end of a big task, ask the 3 checkpoint questions (above) and let the user decide.
If user chooses to evolve: run
```
skill-improver
```
with the best
```
run_dir
```
(the workflow run_dir is usually better than evolution run_dir).
Apply the patch manually and re-validate skills.

Hooks自动生成
```
evolution-candidates.md
```
和
```
evolution-review.md
```
，包含最新的运行信号
大型任务结束时，询问上述3个检查点问题，由用户决定是否优化
若用户选择进化：使用最优的
```
run_dir
```
（工作流的
```
run_dir
```
通常优于进化系统的
```
run_dir
```
）运行
```
skill-improver
```
手动应用补丁并重新验证技能

Example event

事件示例

json

{"ts":"2026-01-11T12:00:00Z","event":"post-bash","category":"build","exit_code":1,"summary":"next build failed: Module not found","artifacts":["logs/failures.jsonl"]}

json

{"ts":"2026-01-11T12:00:00Z","event":"post-bash","category":"build","exit_code":1,"summary":"next build failed: Module not found","artifacts":["logs/failures.jsonl"]}

Outputs

输出产物

```
evolution-candidates.md
```
(auto-generated)
```
evolution-review.md
```
(auto-generated, includes the 3 questions)
Suggested patch from
```
skill-improver
```
(manual apply)

No skills are edited automatically.

```
evolution-candidates.md
```
（自动生成）
```
evolution-review.md
```
（自动生成，包含上述3个问题）
由
```
skill-improver
```
生成的补丁建议（需手动应用）

本系统不会自动编辑任何技能。