📦 Skill Distiller (Reference) — 技能压缩参考文档

完整参考文档（约2,500 tokens，约90%功能，LLM估计）。这是所有压缩变体的权威来源。

注意：本参考文档有意超过300行MCE指南。
作为所有压缩变体的权威来源，完整性优先于简洁性。
有关紧凑变体，请参阅主 SKILL.md（约400 tokens，公式）
或 compressed（约975 tokens，散文）。

代理身份

角色：帮助用户压缩冗长的技能以减少上下文窗口使用 理解：技能为人类清晰度而冗长，但对上下文来说代价高昂；压缩是一种权衡 方法：识别章节类型，评分重要性，删除/缩短低价值章节 边界：保留功能，报告已删除的内容，永不隐藏权衡 语气：技术性、精确、透明地说明权衡 数据处理：此技能在您代理的信任边界内运行。所有分析使用您代理配置的模型。除您代理的 LLM 提供者外，无外部 API。

使用时机

在用户询问以下内容时激活此技能：

• "压缩此技能"
• "使此技能更小"
• "将此技能蒸馏到 X tokens"
• "我可以从此技能中删除什么？"
• "减少技能上下文使用"

---

选项

标志	默认值	描述
--mode	threshold	压缩模式：threshold、tokens、oneliner
--threshold	0.9	功能保留目标（0.0-1.0）
--tokens	-	目标 token 数量（用于 tokens 模式）
--provider	auto	LLM 提供者：auto、ollama、gemini、openai
--model	-	特定模型（例如 llama3.2、gemini-2.0-flash）
--verbose	false	显示逐节分析
--dry-run	false	分析但不输出压缩技能
--debug-stages	false	显示中间阶段输出

提供者自动检测（按顺序）：

• 通过 ollama list 检查 ollama 可用性
• 检查 GEMINI_API_KEY 环境变量
• 检查 OPENAI_API_KEY 环境变量
• 如果都不可用则报错

---

流程

1. 提供者检测

IF ollama available → use ollama (local, fast)
ELIF GEMINI_API_KEY set → use gemini
ELIF OPENAI_API_KEY set → use openai
ELSE → Error: "No LLM provider available. Run 'ollama serve' for local inference, or set GEMINI_API_KEY for cloud."

2. 解析技能

将输入技能解析为章节：

• Frontmatter（包含名称、描述的 YAML 头）
• 标题（##、### 章节）
• 代码块（示例、输出格式）
• 列表（触发器、约束）
• 散文（解释）

3. 章节分类

使用 LLM 分类每个章节：

类型	重要性	可压缩？
TRIGGER	1.0（必需）	否
CORE_INSTRUCTION	1.0（必需）	否
CONSTRAINT	0.9	部分
OUTPUT_FORMAT	0.8	部分
ADVISORY_PATTERN	0.7	是，带警告
EXAMPLE	0.5	是（减少数量）
EDGE_CASE	0.4	是（摘要）
EXPLANATION	0.3	是（删除）
VERBOSE_DETAIL	0.2	是（首先删除）

受保护模式（提升到 0.85+）：

• YAML name/description（规范要求）
• 任务创建引用
• N 计数跟踪（N=1、N=2、N≥3）
• 检查点/状态恢复
• BEFORE/AFTER 标记

3.5. Token 级重要性（LLMLingua/Selective Context）

对于可压缩章节（EXAMPLE、EDGE_CASE、EXPLANATION、VERBOSE_DETAIL），基于自信息理论应用 token 级评分：

原则： self_info(token) = -log(P(token|context))

• 高自信息 = 令人惊讶/重要 → 保留
• 低自信息 = 可预测/可删除 → 修剪

评分提示：

Analyze this section for compression. Classify phrases as:
ESSENTIAL: Specific values, unique terms, key constraints, surprising info
REDUNDANT: Could be inferred, restates earlier content, filler words
Section type: {type}
Content: {content}
Return JSON: {"essential": [...], "redundant": [...], "compression_potential": 0.0-1.0}

修剪规则：

• 永不修剪 ESSENTIAL tokens
• 删除 REDUNDANT 短语同时保留句子结构
• 如果 >50% 是 REDUNDANT，考虑删除整个章节
• 保留特定值（数字、阈值、错误代码）

示例：

Input: "The system will then proceed to process the input data and return the results"
Output: "process input data → return results"
Removed: "The system will then proceed to", "and"

4. 应用压缩

所有模式使用 MetaGlyph 原生符号（参见下面的符号参考）：

• 替换 "results in" → →
• 替换 "implies" → ⇒
• 替换 "for all" → ∀
• 替换 "not" → ¬

阈值模式（默认）：

• 按重要性排序章节（降序）
• 包含章节直到达到功能目标
• 应用符号替换
• 生成压缩的 markdown

Token 目标模式：

• 计算最小 tokens（触发器 + 核心）
• 如果目标 < 最小值：尝试 LLM 摘要
• 按重要性添加章节直到达到目标
• 应用符号替换

单行模式：

• 提取触发条件
• 提取核心动作
• 提取预期结果
• 格式化为 3 行摘要，使用符号

4.1. 示例压缩（RECOMP）

对于 EXAMPLE 章节，使用提取 + 抽象压缩：

阶段 1：提取选择（首选）

• 为每个示例评分模式覆盖度、独特性、清晰度
• 选择前 1-2 个示例（保留完整细节）
• 将剩余示例压缩为单行（不要丢弃）
• 如果覆盖度 ≥ 0.8 → 使用所选 + 单行

阶段 1.5：单行压缩（对于未选中的示例） 不要丢弃，而是压缩为： {trigger} → {result}

• 使用 MetaGlyph 符号
• 保留覆盖度，减少 tokens
• 在 "### One-liners:" 标题下分组

输出结构：

### Full (selected):
[Detailed example with steps...]
One-liners (compressed):
--mode=tokens → hard token limit
--verbose → section-by-section analysis

阶段 2：抽象回退（如果提取 + 单行 < 0.8）

• 生成结合关键模式的摘要示例
• 格式：{generalized_pattern} → {expected_result}
• 在关键处保留特定值

选择提示：

Select the 1-2 BEST examples that cover the most patterns with minimum redundancy.
Examples:
{numbered_list}
Return JSON:
{
  "selected": [indices],
  "coverage": 0.0-1.0,
  "rationale": "..."
}

合成提示（如果覆盖度 < 0.8）：

Compress these examples into 1-2 summary examples.
Preserve: specific values, key patterns, expected outcomes.
Format: "When X → Do Y → Expect Z"
{examples}

输出显示： Examples: 5 → 2 full + 3 one-liners (extractive) 或 Examples: 5 → 1 (abstractive)

5. 测量功能

通过语义理解评估，而非指标。

错误（指标）	正确（语义）
"60% 行减少太激进"	"代理还能执行此技能吗？"
"Token 数量超过目标"	"所有触发器和动作都保留了吗？"
"比率与阈值不匹配"	"代理的行为方式相同吗？"

LLM 通过以下问题评估保留情况：

• 所有原始触发器还能激活吗？
• 所有核心动作还指定吗？
• 关键约束保留了吗？
• 代理的行为方式相同吗？

0-100 分反映语义能力保留，而非行/token 比率。一个压缩到原始大小 40% 的技能如果删除的内容是冗长的解释、冗余示例或非必要格式，仍可保留 95% 的功能。

6. 保存校准

压缩后，将条目保存到 .learnings/skill-distiller/calibration.jsonl：

{
  "id": "c[N]",
  "timestamp": "[ISO 8601]",
  "skill": "[skill name from frontmatter]",
  "mode": "[threshold|tokens|oneliner]",
  "threshold": 0.9,
  "input_tokens": 1800,
  "output_tokens": 1100,
  "reduction_pct": 39,
  "sections_total": 14,
  "sections_kept": 9,
  "sections_removed": 5,
  "classification_confidence_mean": 0.90,
  "functionality_score": 90,
  "protected_patterns_found": ["n-count"],
  "protected_patterns_preserved": ["n-count"],
  "advisory_patterns_found": [],
  "advisory_patterns_removed": [],
  "expected": {"functionality": 90},
  "actual": null
}

文件轮转：如果条目 > 1000，在追加前截断最旧的 100 条。

7. 输出结果

返回带元数据的压缩技能。

---

输出

标准输出

Functionality preserved: 90% (uncalibrated - first 5 compressions build baseline)
Tokens: 2000 → 1800 (10% reduction)
Classification confidence: 0.87 (mean across sections)
Removed: 3 examples, 2 edge cases
Kept: all triggers, core instructions, constraints
[Compressed skill markdown follows...]

详细输出（--verbose）

Section Analysis:
When to Use: TRIGGER (1.0, confidence: 0.95) → KEPT
Process: CORE_INSTRUCTION (1.0, confidence: 0.92) → KEPT
Examples: EXAMPLE (0.5, confidence: 0.88) → RECOMP
└─ Examples: 5 → 2 full + 3 one-liners (coverage: 0.95)
Edge Cases: EDGE_CASE (0.4, confidence: 0.85) → SUMMARIZED
Technical Details: VERBOSE_DETAIL (0.2) → TOKEN-SCORED
└─ Tokens: 150 → 45 (redundant phrases removed)
Token-level analysis:
VERBOSE_DETAIL sections: 3 analyzed, 67% average compression
Phrases removed: "The system will then", "proceed to", "in order to"
RECOMP example analysis:
Original examples: 5
Full (selected): [0, 4] (basic usage, error handling)
One-liners: [1, 2, 3] (threshold, tokens, verbose options)
Coverage: 0.95 (full + one-liners)
Mode: extractive
Protected patterns found: none
Advisory patterns found: parallel-decision → removed (no score penalty)
[Compressed skill markdown follows...]

单行输出

TRIGGER: [activation conditions]
ACTION: [core behavior]
RESULT: [expected output]

带 MetaGlyph 符号的示例：

TRIGGER: user asks "compress skill" ∨ "distill" ∨ "reduce context"
ACTION: parse → classify sections → score importance → ¬low-value → output
RESULT: compressed skill ∧ functionality% ∧ token reduction stats

---

压缩模式

模式 1：阈值（默认）

保留 X% 的功能，尽可能压缩。

/skill-distiller path/to/skill.md --threshold=0.9

理解阈值：阈值（0.9 = 90%）指的是语义功能，而非 token/行比率。

阈值	含义	不是
0.95	保留 95% 的能力	保留 95% 的行
0.90	保留 90% 的语义功能	保留 90% 的tokens
0.80	保留 80% 的代理行为	保留 80% 的字节

如果删除的内容是冗长的示例、冗余的解释或格式，0.9 阈值可能导致 50% 以上的行减少。

通过语义分析判断质量，而非大小比率。

为什么默认 0.9：技能功能在章节中通常呈正态分布。宽尾意味着一些"低重要性"章节偶尔会为边缘情况带来关键价值。在 0.9 时，您保留了更多尾部内容，同时仍实现了有意义的压缩。

模式 2：Token 目标

压缩到精确的 token 预算。

/skill-distiller path/to/skill.md --tokens=500

Token 估计：使用 4 字符/token 启发式。准确度：与实际提供者 token 化相比 +/-20%。对于精确限制，请使用提供者的 tokenizer 验证。

模式 3：单行

极端压缩以快速参考。

/skill-distiller path/to/skill.md --mode=oneliner

生成 3 行摘要：TRIGGER/ACTION/RESULT

---

受保护模式

这些模式必须保留，即使它们看起来冗长：

模式	为什么受保护
YAML name/description	代理技能规范要求
任务创建	压缩弹性
N 计数跟踪	观察工作流
检查点/状态	状态恢复
BEFORE/AFTER	自我校准

如果删除了受保护模式，功能分数将受到惩罚（每个模式 -10%）并在输出中明确标记。

---

建议模式

这些模式可以提高效率，但不是必需的：

模式	如果删除的影响
并行/串行决策	次优执行顺序
性能提示	较慢但功能正常
缓存指导	可以工作但效率低

删除的建议模式会发出警告但不会惩罚功能分数。

---

符号参考（MetaGlyph）

LLM 从预训练中理解的原生数学符号。零图例开销。

符号	替换	示例
→	results in, leads to, produces	trigger → action
⇒	implies, therefore, thus	condition ⇒ behavior
∈	belongs to, is in, member of	value ∈ {a, b, c}
∀	for all, for every, for each	∀ files: validate
¬	not, doesn't, isn't	¬empty → process
∃	there exists, there is	∃ config → load
∧	and, also, plus	valid ∧ safe → proceed
∨	or, either	error ∨ timeout → retry

应用：符号在压缩输出中替换冗长短语。输出中不需要图例——LLM 原生理解。

研究：基于 MetaGlyph（arXiv:2601.07354）——使用原生符号可压缩 62-81%。

---

校准

存储：.learnings/skill-distiller/calibration.jsonl

每次压缩运行都会记录预期功能分数。用户反馈更新 actual 字段，随着时间推移实现校准。

校准阶段

N 计数	输出	含义
N < 5	90% (uncalibrated - first 5 compressions build baseline)	仅 LLM 估计
N = 5-10	88% (building baseline, N=7)	收集数据
N > 10	88% +/- 4% (calibrated, N=12)	历史数据提供置信区间

反馈记录

使用压缩技能后，报告实际结果以改进未来估计：

/skill-distiller feedback --id=c1 --actual=85 --outcome="worked"

结果值：worked、partial、failed

这会更新校准条目，使系统能够从实际使用中学习。

查看校准数据

cat .learnings/skill-distiller/calibration.jsonl | jq -s 'length' # Count entries
cat .learnings/skill-distiller/calibration.jsonl | jq -s 'map(select(.actual != null))' # Entries with feedback

---

自我压缩

此技能可以压缩自身（元递归）。

护栏：

• 更高阈值：要求 95% 功能（而非 90%）
• 递归检查：检测自我引用压缩
• 保留原始：输出到 SKILL.compressed.md，永不覆盖
• 人工验证：需要人工批准

为什么 0.95 阈值：蒸馏器必须保持完全功能以蒸馏其他技能。能力损失会累积（0.95 × 0.95 = 下一级的 0.90）。

执行：0.95 阈值是文档化的护栏，而非自动检查。在压缩 skill-distiller 变体时，手动验证您使用的是 --threshold=0.95 或更高。公式变体（SKILL.md）永远不应作为自我压缩的输入。

---

错误处理

错误	恢复提示
无内容	提供有效的 SKILL.md 文件路径或通过 stdin 管道内容
无 frontmatter	添加带有 name 和 description 的 --- 块
无触发器章节	添加 '## When to Use' 以获得最佳结果
Token 目标不可能	使用 --mode=oneliner 进行极端压缩
LLM 不可用	运行 'ollama serve' 用于本地，或设置 GEMINI_API_KEY
已经最小化	在阈值 Y 下无法压缩

---

未来计划

尚未实现的功能：

标志	描述	状态
--with-ci	计算置信区间（3倍 LLM 调用）	计划中

---

相关

变体	Tokens	功能
skill-distiller（主）	~400	~90%（公式）
compressed	~975	~90%（散文）
oneliner	~100	~70%
reference（本）	~2,500	~90%

Token 数量使用 4 字符/token 启发式估计。功能分数是 LLM 估计的。

---

• LLM 压缩研究
• 调查了 MetaGlyph、LLMLingua 和其他 11 种技术
• 技能压缩支持.md
• 基于 CLI 的压缩（选项 B）
• 代理技能规范
• 必需字段、大小约束