<div align="center">

# Skill-Alchemy · 技术文档

<br>
<em style="font-size: 16px;">我们不是在猜什么是好 Skill。我们量过。</em>
<br>
</div>

<br>

## 系统架构

<div align="center">
  <img src="SkillAlchemy-flow-brief.png" alt="Skill-Alchemy 系统架构图" width="800">
</div>

Skill-Alchemy 编排两个子引擎：Lens 认知镜片（纯认知展开，不交互）和 LEAP 落地引擎（A 分支蒸馏 + B 分支融合，不交互）。所有用户交互在 Skill-Alchemy 层。

---

## 核心创新

### 1. skill-grammar — 从 skills.sh 反向工程出的写作铁律

网上所有人都在教怎么写 prompt，没有人在教怎么写 Skill。为什么？因为没有数据。

我们解析了 skills.sh 上大量公开 Skill，建了一套评分系统，把每个 Skill 拆成触发模式、SOP 类型、操作类型、边界模式、领域、质量六个维度，逐项打分。然后做了全量 vs 高质量样本的加权对比统计。

**数据教会我们的事：**

- **精英 Skill 100% 用 chain-of-steps。** 没有一个例外。
- **纯参考文档型 Skill 在质量过滤后几乎消失。** 没有可执行步骤 = 判死刑。
- **太薄的 Skill 被大量排除。** 行数不够是硬伤。
- **混合触发（关键词 + 上下文）是好 Skill 的信号。**

编译阶段，LEAP 必须先读 skill-grammar。不读 → 禁止编译。读完 → 对照精英模板确认结构，对照反模式清单逐条检查，编译后自评并机械验证。

### 2. 机械评分 + 质量金字塔

对任何一个 SKILL.md，纯规则匹配毫秒级给出评分：frontmatter 完整性、description 是否含触发词、section 密度、步骤数量、边界声明、行数区间。全部是正则和计数——确定性的、不开玩笑的。

基于全量评分统计，好中差三级分明：

| 层级 | 特征 |
|------|------|
| **精英** | 100% chain-of-steps，94% 有边界声明，89% 诊断+验证兼备 |
| **中间** | chain-of-steps 为主，hybrid trigger 占比更高 |
| **底层** | 纯参考型全集中在此，平均行数仅为精英的 1/5 |

A-Stage 5 用这套评分从 find-skills 搜索结果中自动挑出精英 exemplar。B-Step 1 用它过滤融合源——垃圾进垃圾出。

### 3. find-skills + 运行时评分 — 面向全量 Skill 池的实时检索

不维护本地索引。skills.sh 上 Skill 天天在涨，静态快照就是限制上限。

**检索层 find-skills：** skills.sh 的语义搜索引擎，面向全部公开 Skill。**评分层 score_skill：** 搜出候选 → 并发下载 → 毫秒级评分 → 精英优先，draft 丢弃 → 自动注入编译。

离线索引时代结束了。别人靠本地快照，我们面向全量实时池。

---

## A 分支蒸馏

从 raw data 提取目标 OS，编译为 Persona 或 Tool Skill。七个 Stage，两个 Gate。

**动态 Agent Swarm：** Agent 数量不由模板决定，由 source 的证据密度决定。证据密集 → 更多 Agent 更深研究。Persona 目标加载 persona-os 交叉层，从七个 OS 维度（决策约束、失败处理、价值观冲突、注意力分配、影响力、学习更新、身份叙事）中按需选择研究透镜。

**Dilemma Decision Cases：** 每个研究 Agent 必须从公开资料中提取真实的困境决策案例——困境、约束、决策步骤、结果。这些案例是心智模型和决策启发式的唯一合法来源。

**Exemplar 注入：** find-skills 在线搜索 + score_skill 自动评分择优 → 取精英 Skill 的结构做 few-shot 参照。**编译铁律：** 必须先读 skill-grammar，对照精英模板和反模式清单，编译后自评，机械验证。

---

## B 分支融合

核心公式：`method（骨架） × subject（血肉） → 新 Skill`。不是拼接——看得出缝合痕迹就是失败。

四级检索（output/ → 本地 skills/ → find-skills → GitHub raw），score_skill 自动过滤。Parse 提取骨架和血肉，Weave 编织统一身份（「式/风格的/基于」——从不声称本人），合并约束，防拼接验证。

---

## 共享基础设施

| 组件 | 作用 |
|------|------|
| skill-grammar | Skill 写作铁律，编译必读 |
| score_skill | 13 分机械评分，运行时质量过滤 |
| quality_check | SKILL.md 结构机械验证 |
| find-skills（skills.sh） | 在线语义搜索，全量公开 Skill 池 |
| domains | 12 领域参考包 + persona-os 交叉层 |

---

<div align="center">
  <br>
  <em style="font-size: 16px;">这不是 prompt engineering，这是 Skill engineering。</em>
  <br>
</div>
