Skills compact-bensz-skills

当用户明确要求“压缩/瘦身/精简某个 Agent Skill 的 Markdown 文档”“在不改变功能前提下降低 skill 上下文开销”时使用。先理解目标 skill 的真实能力与安全边界，再在忽略 `tests/`、`plans/` 以及目标 skill 的 `README.md`、`CHANGELOG.md` 的前提下，压缩 `SKILL.md`、`references/*.md` 等工作型 Markdown，并把中间产物隔离到 `.compact-bensz-skills/`。⚠️ 不适用：用户主要想新增功能、修复脚本逻辑、批量改代码、或只想压缩非 skill 文档。

install

source · Clone the upstream repo

git clone https://github.com/huangwb8/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/huangwb8/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/compact-bensz-skills" ~/.claude/skills/huangwb8-skills-compact-bensz-skills && rm -rf "$T"

manifest: compact-bensz-skills/SKILL.md

source content

compact-bensz-skills

与 bensz-collect-bugs 的协作约定

因本 skill 设计缺陷导致的 bug，先用
```
bensz-collect-bugs
```
规范记录到
```
~/.bensz-skills/bugs/
```
，不要直接修改用户本地已安装的 skill 源码；若有 workaround，先记 bug，再继续完成任务。
只有用户明确要求“report bensz skills bugs”等公开上报时，才用本地
```
gh
```
上传新增 bug 到
```
huangwb8/bensz-bugs
```
；不要 pull / clone 整个仓库。

面向“压缩某个 Agent Skill 的工作型 Markdown 文档，但不破坏其原有功能”的维护型 skill。

输入

```
skill_root
```
（必需）
- 目标 Agent Skill 根目录
```
workspace_dir
```
（可选）
- 默认把本轮工作区建在
```
<skill_root>/.compact-bensz-skills/run-{timestamp}/
```
- 如果用户显式指定其它目录，则把它视为“run 容器根目录”，本轮仍落到其中的
```
run-{timestamp}/
```
```
run_id
```
（可选）
- 用于在
```
init -> measure -> validate
```
  间显式复用同一轮工作区

test_dir

（可选）

默认

<skill_root>/tests/compact-bensz-skills/

核心原则

先理解，再压缩：先读
```
SKILL.md
```
、
```
config.yaml
```
、
```
scripts/
```
和必要的
```
references/
```
，再判断哪些 Markdown 可以缩短。
不改行为，只改表达：压缩的是文档体积，不是功能边界；不得擅自新增、删除或扭曲目标 skill 的能力。
保护触发语义：
```
SKILL.md
```
frontmatter 的
```
name
```
必须保持不变；
```
description
```
只能等价压缩，不能丢失关键触发条件。
保护硬约束：输入、输出、默认路径、安全限制、必跑脚本、失败条件、与其它 skill 的协作约定都必须保留。
只动源工作文件：忽略目标 skill 的
```
tests/
```
、
```
plans/
```
及其内容，不把它们视为待压缩源文件。
默认不动说明文档：目标 skill 根目录下的
```
README.md
```
、
```
CHANGELOG.md
```
一般属于面向人类的说明或发布记录，不视为默认压缩目标。
中间文件隔离：分析、快照、统计、验证结果都写到隐藏目录
```
.compact-bensz-skills/
```
；除非用户另有指定，不向外泄露中间文件。
按轮次隔离：每次运行都应在
```
.compact-bensz-skills/run-{timestamp}/
```
内工作，避免多次压缩会话互相覆盖。
链接不能越界：压缩后保留的本地 Markdown 链接必须仍位于目标 skill 根目录内，不能借相对路径跳到 skill 外部。

标准工作流

1. 初始化隐藏工作区

优先使用确定性脚本创建工作区、快照和 Markdown 清单：

python3 compact-bensz-skills/scripts/init_workspace.py --skill-root /path/to/target-skill

脚本会：

创建

<skill_root>/.compact-bensz-skills/run-{timestamp}/

在隐藏根目录写入
```
latest-run.txt
```
扫描待压缩 Markdown（忽略
```
tests/
```
、
```
plans/
```
、
```
README.md
```
、
```
CHANGELOG.md
```
）
生成
```
analysis/file-inventory.json
```
备份原文到
```
snapshots/before/
```
生成
```
analysis/compaction-plan.md
```
记录压缩前统计到
```
reports/size-before.json
```

2. 理解目标 skill 的真实功能

最低阅读范围：

```
SKILL.md
```
```
config.yaml
```
（如存在）
```
scripts/
```
（如存在）
```
references/
```
中与核心流程直接相关的文档
仅当
```
README.md
```
、
```
CHANGELOG.md
```
与核心行为边界强相关时才辅助阅读；默认不把它们纳入压缩目标

理解时重点确认：

技能触发条件与不适用范围
输入输出契约
默认工作区 / 测试区 / 中间文件路径
安全边界与只读/只写限制
任何“必须执行”“不得省略”的步骤

3. 执行 Markdown 压缩

优先顺序：

删重复：移除跨文件、跨章节重复解释
缩长句：把啰嗦描述改成短句、表格或清单
主从分离：
```
SKILL.md
```
只保留触发逻辑、主流程、硬约束；细节下沉到
```
references/
```
压示例：保留最小可用命令和最关键示例，删除低价值变体

默认优先处理：

```
SKILL.md
```
```
references/
```
中真正承载执行细则的 Markdown

默认不处理：

目标 skill 根目录下的
```
README.md
```
目标 skill 根目录下的
```
CHANGELOG.md
```

压缩时必须保留：

```
SKILL.md
```
frontmatter 与关键词可发现性
关键命令、路径、文件名、配置键
输入/输出、默认目录、安全限制
会改变行为的条件分支
与
```
bensz-collect-bugs
```
等跨 skill 约定

压缩时禁止：

把“必需”改成“可选”
删除失败条件、边界条件、路径约束
删除唯一的命令示例或唯一的输出说明
只为了省字而制造歧义

4. 复测压缩收益

完成文档修改后重新统计：

python3 compact-bensz-skills/scripts/measure_markdown.py --skill-root /path/to/target-skill --phase after

如需显式复用某一轮：

python3 compact-bensz-skills/scripts/measure_markdown.py \
  --skill-root /path/to/target-skill \
  --run-id run-20260328155205915498 \
  --phase after

该脚本会输出：

```
reports/size-after.json
```
```
reports/size-delta.md
```

5. 校验压缩后仍可用

python3 compact-bensz-skills/scripts/validate_compaction.py --skill-root /path/to/target-skill

默认会复用

latest-run.txt

指向的最近一轮；如果你在多个 run 之间切换，显式传

--run-id

更稳妥。

至少检查：

```
SKILL.md
```
frontmatter 是否完整
```
metadata.author
```
是否保留
```
metadata.keywords
```
是否仍包含 skill 名
本地 Markdown 相对链接是否仍有效且没有越出目标 skill 根目录
压缩后的总字数是否低于压缩前
若
```
description
```
有改动，确认只是等价压缩而非改坏触发语义

何时读取参考文档

需要决定“哪些内容必须保留”时，读
```
references/preservation-checklist.md
```
需要具体压缩手法时，读
```
references/compaction-playbook.md
```
做收尾校验时，读
```
references/validation-checklist.md
```

输出

对用户的主要交付：

更新后的目标 skill 工作型 Markdown 源文件

隐藏工作区产物：

```
.compact-bensz-skills/latest-run.txt
```

.compact-bensz-skills/run-{timestamp}/analysis/file-inventory.json

.compact-bensz-skills/run-{timestamp}/analysis/compaction-plan.md

.compact-bensz-skills/run-{timestamp}/reports/size-before.json

.compact-bensz-skills/run-{timestamp}/reports/size-after.json

.compact-bensz-skills/run-{timestamp}/reports/size-delta.md

.compact-bensz-skills/run-{timestamp}/reports/validation.json