Skip to content
Skills Library
AI & agents · Planning

skill-evolution

/skill-evolution

Use when the same pitfall recurs three times, a major incident gets fixed, an action repeats, a workflow proves generally reusable, or the user corrects the assistant — decide update-versus-create with a five-axis overlap rubric, draft the change in chat only, and touch disk solely after explicit approval. 技能进化、纪律晋升、草案审批、重合度判定、rubric、准入、草案只读.

Licence
MIT
Last repository change
06.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 06.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when the same pitfall recurs three times, a major incident gets fixed, an action repeats, a workflow proves generally reusable, or the user corrects the assistant — decide update-versus-create with a five-axis overlap rubric, draft the change in chat only, and touch disk solely after explicit approval. 技能进化、纪律晋升、草案审批、重合度判定、rubric、准入、草案只读.

Original author description

Use when the same pitfall recurs three times, a major incident gets fixed, an action repeats, a workflow proves generally reusable, or the user corrects the assistant — decide update-versus-create with a five-axis overlap rubric, draft the change in chat only, and touch disk solely after explicit approval. 技能进化、纪律晋升、草案审批、重合度判定、rubric、准入、草案只读.

How it works

  1. 一、触发条件(五选一,必须附证据锚)
  2. 二、判定:改旧还是新建(5 轴 rubric)
  3. 三、草案格式(只在对话里出现)
  4. 四、准入后的写入流程(严格按序 · 改 → 提交 → 同步 → 核验)
  5. 五、纪律晋升(从技能到宪法)
  6. 六、回滚
  7. 七、硬性禁止项(违反即事故)
Original SKILL.md headings · 183 lines, 614 words
SKILL.md preview
---
name: skill-evolution
description: Use when the same pitfall recurs three times, a major incident gets fixed, an action repeats, a workflow proves generally reusable, or the user corrects the assistant — decide update-versus-create with a five-axis overlap rubric, draft the change in chat only, and touch disk solely after explicit approval. 技能进化、纪律晋升、草案审批、重合度判定、rubric、准入、草案只读.
---

# SKILL:半自动技能进化

**适用场景**:出现值得沉淀的重复经验;或用户纠正了我;或我刚完成一次重大事故修复。

**不适用**:一次性的偶发问题;用户没纠正、也没复发迹象的个人偏好。

**一句话原则**:**提议权自动,写盘权人工。** 我可以随时提议,但不许自己动手。

## 一、触发条件(五选一,必须附证据锚)

| 条件 | 可接受的证据锚 |
|---|---|
| 同一坑踩 ≥3 次 | ARCHIVE.md 里 ≥3 条同症状/同锚点的记录 ID |
| 重大事故修复 | 本次修复的前后对比(改前必红、改后必绿) |
| 重复动作 ≥3 次 | 本会话内的重复工具调用序列 |
| 通用工作流被长期复用 | ≥2 个不同项目/工作区在用 |
| 用户明确纠正 | 用户原话引用 |

**没有证据锚 ⇒ 不许提议。** 凭"感觉这个坑好像踩过"不算。

## 二、判定:改旧还是新建(5 轴 rubric)

| 轴 | 权重 | 命中标准 |
|---|---|---|
| 同触发症状 | 20% | 相同的报错类 / 相同的前置条件 |
| 同根因层 | 20% | 同属一个病根谱系(见 recurring-root-cause-atlas) |
| 同修法 | 20% | 规则条目可合并而不冲突 |
| 同操作步骤 | 20% | 复用 ≥60% 的命令/流程 |
| 同适用范围 | 20% | 适用场景重叠 ≥60% |

**≥3 轴命中(=60%)⇒ 改现有 skill;否则新建。**

这是**打勾判定,不是数值估算**——模型算不出真正的相似度,别假装能算。

新建时必须在草案里额外回答一句:**为什么不能并入现有能力簇?**

## 三、草案格式(只在对话里出现)

固定**四段**,缺一段不算草案:

1. **第一段:前因后果与运作机制(人类可读,强制)** —— 用大白话回答三个问题,
   不许拿黑话、代号、缩写当答案:

   | # | 必须回答 | 不合格的写法 |
   |---|---|---|
   | ① | **刚才出了什么事?** 哪一天、哪个文件、什么数字、你怎么发现的 | 「存在一致性风险」 |
   | ② | **为什么需要这个 Skill?** 不加这条规矩,以后会在哪一步死掉 | 「提升健壮性」 |
   | ③ | **它怎么运作来规避?** 底层逻辑一句话说清,别人能复述 | 「建立闭环机制」 |

   **这一段的三个答案还必须同时写进 Skill 自己的正文开头**(或同目录 `README.md`),
   不能只活在对话里。理由:草案是给做决定的人看的,Skill 是给下一次的自己看的,
   两边都要求"读完就知道为什么",而不是"读完只知道有这么个规矩"。

2. **触发证据** —— 锚点 ID / 本次前后对比 / 用户原话;
3. **改动 diff** —— 改哪个文件、加哪几行、删哪几行(新建则给全文);
4. **风险与回滚** —— 最坏影响是什么、怎么退(`git revert <sha>`)。

草案只在对话里打印。**在用户给出明确的"准入 / 写入 / 批准"之前,一个字节都不许写盘。**

## 四、准入后的写入流程(严格按序 · **改 → 提交 → 同步 → 核验**)

> **为什么不是「提交时比对三端」了?**
> 2026-11-06 架构简化:全机只剩一个 Git 仓库,**技能进化只准写入 `<你的主库路径>\skills`**。
> 哪怕你在 某项目 之类的**别的项目**里触发进化,也**不许在那个项目里新建 `skills` 目录**。
> (技能同步进开源仓时,这条真路径由脱敏流程换成 `<你的主库路径>/skills`。)
> 运行环境 `~/.dsh/skills` 与 `~/.dsh/AGENTS.md` 是**纯文件产物**,由
> `tools/sync-to-runtime.py` 单向覆盖。**没有「三端」,也就没有跨端哈希比对。**
> pre-commit 只查本仓库自己的三件事:双胞胎护栏、CRLF/UTF-8、HANDOFF 门禁。

### 4.0 高危变更:先出《全链路影响面清单》,再动手

涉及**核心结构文件**(`AGENTS.repo.md`、SKILL 模板、目录搬迁)的路径或文件名变更,
落盘前**必须先产出影响面清单并经人过目**,逐项点名:

1. **同步脚本** —— `tools/sync-to-runtime.py` 的白名单里有没有漏掉新文件?
2. **pre-commit 钩子及其调用的门禁** —— 文件名常量被用在几处?
3. **同步校验逻辑** —— `tools/verify_sync.py` 里仓库内名与生效端名是否已经分离?
4. **Git 提交触发条件** —— 改名后"暂存区是否含该文件"的判定还成不成立?
5. **文档/注释里写死的路径** —— 会不会把后人带沟里?

⚠️ 改名还会改变语义:仓库内 `AGENTS.repo.md` → 生效端 `AGENTS.md`,是**改名**复制。

### 4.1 两类改动,路线相同

> **⚠️ 以下所有操作(包含 git 命令与 python 脚本),必须在主库根目录(即包含 `.git` 的 `skills/` 目录)下执行。**

**A. 纪律改动(`AGENTS.repo.md`)**

> 仓库内叫 `AGENTS.repo.md`,生效端叫 `~/.dsh/AGENTS.md`,**刻意不同名**:
> 若仓库里也叫 `AGENTS.md`,运行时那份会被宿主当指令注入,而同步又会覆盖它——两个来源打架。

1. 查工作树:`git status --porcelain` 必须为空;脏就先 commit 或停下报告;
2. 改本仓库的 `AGENTS.repo.md`;
3. **提交**:`git commit`(消息带证据锚,如 `refs H-0042`)—— **先入库,再同步**;
4. **同步**:`python tools/sync-to-runtime.py`(把 `AGENTS.repo.md` 复制成 `~/.dsh/AGENTS.md`,
   并按白名单刷新 12 个技能;运行端不再保留 `AGENTS.repo.md`);
5. **核验**:`python tools/verify_sync.py` 必须输出「主库与运行环境完全一致」;
6. 报告:改了哪几行、哈希前后值、回滚命令。

**B. 技能改动(`<name>/SKILL.md`)**

1. 查工作树干净;
2. 改本仓库的 `SKILL.md`;
3. **提交**(先入库);
4. `python tools/sync-to-runtime.py`;
5. `python tools/verify_sync.py` 核验;
6. 报告。

> **三条铁律**
> - **顺序不可颠倒:改 → commit → sync → verify。** 绝不允许在 commit 之前先同步 ——
>   commit 一旦失败,主库和运行端就脱节了,而且这种脱节是**静默**的。
> - **同步方向永远 D 盘 → C 盘。** 直接改 `~/.dsh` 里的文件,下次同步会被覆盖,改动蒸发。
> - **C 盘 `~/.dsh/skills` 下不允许出现任何 `.md` 文件**:`AGENTS.repo.md` 只留在主库,
>   生效端只要 `~/.dsh/AGENTS.md` 一份。

**C. 强制记录发版待办(`../PENDING_RELEASE.md`)**

任何涉及技能或纪律的修改,**只要用户给出准入并落盘主库**,就必须立刻在工作区根目录(`../PENDING_RELEASE.md`)
追加一条记录:改了什么技能、具体改了什么内容。

这是强制动作,**不允许有任何"这个改动可能不需要发布"的侥幸心理**。判断"要不要发"不是我的工作,
登记才是;发布时由人统一在这里读取。

### 4.2 同步失败怎么办

`sync-to-runtime.py` 在建 staging、校验、替换任何一步失败都会**自动回滚**,
运行环境保持原样。失败时:

1. 保留完整错误原文(不要只说"失败了");
2. 常见原因:运行环境文件被宿主占用(先关掉会话再同步)、权限不足、盘符不可写;
3. **禁止**为了"先让版本入库"而用 `--no-verify` 跳过 pre-commit;HANDOFF 不过就先补 HANDOFF;
4. 报告里必须写:同步到哪一步失败、错误原文、当前运行环境是否仍是旧的一份。

### 4.3 报告格式(必须能自证)

```
主库 AGENTS.repo.md : <sha16>  <字节数>  CRLF=<n> 裸LF=<n>
生效端 AGENTS.md    : <sha16>  <字节数>  CRLF=<n> 裸LF=<n>
技能文件            : 12 个,逐个 sha16(verify_sync 输出)
同步核验            : verify_sync.py -> ✓ / ✗(✗ 必须附原因)
提交                : <sha> <消息>
```

### 4.4 门禁与工具自身的三个假绿(真实踩过)

| 陷阱 | 现象 | 已固化对策 |
|---|---|---|
| **cwd 不在仓库** | 手动跑校验脚本,cwd 不在仓库根 ⇒ 打印「跳过」并 **exit 0** | 校验脚本必须能从自身路径推导仓库根;"跳过"不得等于"通过" |
| **中文/符号乱码** | Windows 控制台默认 GBK:中文输出变乱码,容易被当成"正常输出"糊过去;更狠的是 `print("✓")` 直接抛 `UnicodeEncodeError` —— **操作其实已经成功,却以 exit 1 收场(假红)** | 脚本内 `sys.stdout.reconfigure(encoding="utf-8")` 钉死;或输出只用 ASCII 记号 |
| **编译缓存污染** | `python -m py_compile` 生成 `__pycache__/`,被 `git add -A` 带进提交 | 语法检查优先用 `compile()` 不落盘;提交前 `git status` 不许有 `??` |

判据:**「这个绿能证明被测对象真的跑了吗?」答不上来,就不算数。**

## 五、纪律晋升(从技能到宪法)

如果提炼出的经验**跨项目成立**(不依赖某个项目的目录结构/命令/约定),它就是纪律:

- 提议写进 `AGENTS.repo.md` 的对应章节,格式固定:**一句话可执行规则 + `(详见 skill: xxx)`**;
- 纪律区只放纪律。**技能索引、目录、清单、说明性文字一律不得进 AGENTS**;
- 同样需要用户"准入"才能落盘,且必须走第四节的同步流程。

## 六、回滚

- 单次改动 ⇒ `git revert <sha>`(保留历史,不 force push);
- 同步出错 ⇒ 重跑 `python tools/sync-to-runtime.py`(自带回滚;失败则运行环境保持旧版);
- 生效端 `~/.dsh/AGENTS.md` 被改坏 ⇒ 直接重跑同步脚本即可覆盖回来(它是产物,不是权威)。

## 七、硬性禁止项(违反即事故)

- ❌ **未经"准入"就把草案写盘**——这是本机制的第一红线;
- ❌ **直接编辑 `~/.dsh/AGENTS.md` 或 `~/.dsh/skills/*/SKILL.md`** —— 它们是运行环境产物,下次同步必被覆盖;
- ❌ **在运行环境里做任何 Git 操作** —— `~/.dsh` 已彻底脱管 Git;
- ❌ 两个地方同时改(主库 + 运行环境)—— 只改主库,再同步;
- ❌ **往 `AGENTS` 添加任何非纪律内容**(技能索引/目录/清单)——2026-11-02 已被用户明确否决过一次;
- ❌ 工作树脏时改文件;
- ❌ 把"我提议了"说成"我已记录";
- ❌ 用模糊的相似度估算代替 5 轴 rubric 打勾;
- ❌ 在没跑过触发证据的情况下声称"这是第 3 次";
- ❌ 把「跳过」的 exit 0 当成通过(门禁自己也要自证前提,见 4.4);
- ❌ 让 `py_compile` 产物(`__pycache__/`)混进提交。
- ❌ **修改了技能并落盘主库,但未在 `../PENDING_RELEASE.md` 中强制登记** —— 漏登记等于让改动在下一次发版时凭空消失。

Versions

RepositoryScoreLicence
This page · Sirius-Ji/dsh-disciplinary-skills-for-greenhands100MIT
coco-research/coco100MIT
Lin-Yu-kuan/mySkill100MIT
beita6969/scienceclaw100MIT
echoleesong/claude-skills-plugin100MIT

Database snapshot: 13.11.2026 · package version 0b13ef1e1089 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100skill-creator
    Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
  • 100skill-development
    This skill should be used when the user asks to create a new skill, repair an existing skill, improve trigger descriptions, reorganize skill structure, or make a Claude skill more reusable and internally consistent.
  • 100skill-crafting
    Decide whether a recurring workflow needs a reusable agent skill, and design, evaluate, improve, split, merge or retire skills. Use when working on trigger boundaries, architecture, behavior contracts or effectiveness evaluation. Not for agent instruction files…
  • 100skill-evaluation
    Writing a new Claude Code skill or changing an existing one, with evidence that it changes behavior. Use when creating a skill, editing a skill's body or description, deciding whether a skill earns its place, or when someone asks whether a skill improves results.
  • 100method-evolution
    Use when the same rubric violation, the same kind of symptom-patch, or the same escalation happens across 3+ distinct tasks — meaning the problem is in the method (skill, prompt, rubric), not in the tasks. Forces a disciplined outer-loop step: name the pattern, propose a…
  • 100skill-creator
    Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends an AI agent's capabilities with specialized knowledge, workflows, or tool integrations.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.