tech-doc-writer Skill 评审报告¶

评估框架: skill-creator 评估日期: 2026-03-17 评估对象: tech-doc-writer

tech-doc-writer 是一个面向工程文档写作、审查与改进的 skill，适合处理 runbook、故障排查文档、API 文档以及 RFC/ADR 风格的设计文档。它最突出的三个亮点是：先做文档类型分类和受众分析，让结构与深度对齐读者目标；通过元数据、结论前置、回滚路径和 SPA 标题等质量门禁，提高文档的可维护性与可用性；同时提供 review/improve 模式下的 scorecard、anti-examples 和结构化输出，使文档反馈更具体、可执行，而不是停留在泛泛建议上。

一、评估概览¶

本次评估从实际任务表现和 Token 效费比两个维度对 tech-doc-writer skill 进行全面评审。设计 3 个覆盖不同文档类型和执行模式的场景（任务文档写作、故障排查文档写作、文档审查与改进），每个场景分别运行 with-skill 和 without-skill 配置，共 3 场景 × 2 配置 = 6 次独立 subagent 运行，对照 38 条 assertion 进行评分。

注：Eval 3 with-skill 因权限阻断仅产出 review-findings，缺失 improved-runbook，5 条 assertion 无法评分。通过率按可评分项计算（with-skill 31/33，without-skill 21/38）。

二、测试方法¶

2.1 场景设计¶

2.2 测试仓库¶

使用 /tmp/tech-doc-eval/repos/go-order-service（Go 1.24, Gin, GORM, MySQL 8.0, Redis 7, docker-compose）作为 Eval 1/2 的目标仓库。Eval 3 使用一份人工编写的缺陷 MySQL 升级 runbook（45 行，0 条 scorecard 通过）。

2.3 执行方式¶

• With-skill 运行先读取 SKILL.md 及其引用的参考资料（templates.md、writing-quality-guide.md）
• Without-skill 运行仅探索仓库后按模型默认行为生成文档
• 所有运行在独立 subagent 中并行执行
• 注意：subagent 受文件写入权限限制，实际文档内容从 agent transcript 中提取

2.4 Timing 数据¶

注：with-skill 的 token 和时间偏高，部分原因是 subagent 被文件写入权限反复阻断后重试（Eval 1 with-skill 有 29 次 tool use）。实际生产环境中权限通畅时，with-skill 的额外开销主要来自读取 SKILL.md + 参考资料（~4,000-6,000 tokens），预估 with-skill 运行总 token 约 36,000-42,000（较 without-skill 增加 ~20-30%）。

三、Assertion 通过率¶

3.1 总览¶

3.2 Eval 1 逐条对比¶

3.3 Eval 2 逐条对比¶

3.4 Eval 3 逐条对比¶

3.5 Without-Skill 失败的 17 条 Assertion 归类¶

四、逐维度对比分析¶

4.1 结构化元数据（YAML Frontmatter + applicable_versions）¶

这是最稳定的差异化维度，在所有 eval 中 with-skill 全部通过，without-skill 全部失败。

With Skill（Eval 2 示例）:

---
title: "MySQL: 高并发下 orders 表 Deadlock"
owner: order-service-team
status: active
last_updated: 2026-03-17
applicable_versions: Go 1.24+, MySQL 8.0, GORM 1.25+
---

Without Skill（Eval 2）: 无任何元数据。

实际价值: 元数据使文档可被自动化工具索引、过期检测、责任追溯。applicable_versions 防止读者在错误版本上执行操作。

4.2 结论前置（Conclusion First）¶

在 Eval 2（故障排查文档）中差异最显著。

With Skill 首段:

根因结论：多个事务以不同顺序对 orders 表的同一行或相邻索引区间加锁，导致循环等待死锁。 典型场景是 CreateOrder（INSERT）和 CancelOrder（UPDATE）并发执行时，InnoDB 的 gap lock 与 record lock 产生冲突。

Without Skill 首段:

服务在高并发场景下频繁输出以下错误... 什么是 Deadlock... Deadlock（死锁）是两个或多个事务互相持有对方需要的锁...

Without-skill 版本先解释背景知识再分析成因，读者需要读完 40% 的文档才能找到根因。Skill 的 Gate 4 Scorecard 明确要求 "Conclusion/core message appears in the first paragraph"。

4.3 文档类型分类与模板对齐¶

Skill 的 Gate 2（Document Type Classification）驱动 with-skill 选择正确的文档模板：

分析: Without-skill 的结构不差，但不一致 — 每次运行可能产生不同结构。Skill 通过模板确保了结构可预测性。

4.4 Review 模式的差异¶

Eval 3 中 with-skill 和 without-skill 的 review 质量对比：

分析: 两者的问题发现能力相当（都全面覆盖了关键缺陷），但 with-skill 的呈现方式更结构化（Scorecard 量化、before/after 修复）。Without-skill 的 review 更像 code review 风格（问题 + 影响描述），缺少可直接操作的修复建议。

4.5 预防措施与监控告警¶

Eval 2 中的显著差异：

With Skill: | 指标 | 采集方式 | 告警阈值 | |------|---------|---------| | Innodb_deadlocks | Prometheus mysqld_exporter | 5 分钟内增量 > 3 | | 应用层重试次数 | 代码埋点 | 1 分钟内 > 10 | | 慢查询 | slow_query_log | 单条 > 1s |

Without Skill: 建议开启死锁日志和压测，但无具体告警阈值。

Skill 的 troubleshooting 模板要求 "Prevention must include at least one monitoring item"，with-skill 直接提供了可落地的监控配置。

4.6 代码示例质量¶

两者的 Go 代码示例质量差异不大 — 都提供了自包含的 RunInTxWithRetry 实现，包含 imports、错误处理、指数退避。

分析: 代码质量是基础模型已具备的能力。Skill 的增量贡献在于 <!-- UNVERIFIED: ... --> 标记（来自 Gate 0: Execution Integrity），这是一个小但有价值的差异 — 避免读者盲信未验证的代码。

五、Token 效费比分析¶

5.1 Skill 体积¶

tech-doc-writer 是一个多文件 skill，包含 SKILL.md + 3 份参考资料 + 回归测试脚本。

5.2 典型加载场景¶

Skill 设计了渐进式加载（Load References Selectively），实际 Token 消耗取决于文档类型：

5.3 Token 换取的质量提升¶

5.4 Token 分段效费比¶

5.5 高杠杆 vs 低杠杆指令¶

高杠杆（~940 tokens SKILL.md → 14 条 assertion 差值）: - Gate 2 文档类型分类（150 tok → 2 条） - Gate 4 Quality Scorecard（250 tok → 3 条） - Output Contract（200 tok → 3 条） - Phase 5 Metadata（80 tok → 3 条） - Conclusion First（60 tok → 1 条） - SPA 标题（100 tok → 2 条） - Gate 0 UNVERIFIED 标记（100 tok → 间接贡献）

中杠杆（~550 tokens → 间接贡献）: - Anti-Examples（350 tok）— 驱动了 Eval 3 的 before/after 修复模式 - Document Maintenance（200 tok）— 产出了维护触发条件

低杠杆（~280 tokens → 0 条差值）: - Degradation Strategy（200 tok）— 未测试 - Language 规则（80 tok）— 未测试

参考资料（~3,630 tokens → 间接贡献）: - templates.md 驱动了文档结构一致性 - writing-quality-guide.md 提供了 review 模式的 BAD/GOOD 示例 - docs-as-code.md 本次评估中未被使用

5.6 Token 效率评级¶

5.7 与 go-makefile-writer 的效费比对比¶

分析: 两者的 SKILL.md 效费比几乎一致（~62-63 tok/1%），但 tech-doc-writer 因覆盖更多文档类型和模式，参考资料的加载范围更大。渐进式加载设计使得简单场景（task doc）的总开销（~2,900 tokens）低于 go-makefile-writer，复杂场景（review + 全量参考）则更高（~5,250 tokens）。

六、与 Claude 基础模型能力的边界分析¶

6.1 基础模型已具备的能力（Skill 无增量）¶

6.2 基础模型的能力缺口（Skill 填补）¶

6.3 Skill 设计的精准度¶

Skill 的 4 个 Mandatory Gate 精准对应了基础模型的 6 个核心缺口：

关键发现: Gate 1 和 Gate 3 在当前评估中无增量贡献 — 基础模型在 repo 扫描和受众分析上已经做得很好。最大价值来自 Gate 4（Quality Scorecard），它编码了模型不会自发执行的质量检查规则。

七、综合评分¶

7.1 分维度评分¶

7.2 加权总分¶

八、Skill 设计优点¶

8.1 渐进式加载设计¶

"Load References Selectively" section 明确指定了每个参考文件的加载条件，避免不必要的 Token 消耗。Task doc 场景仅需 ~2,900 tokens（SKILL.md + templates 片段），与 go-makefile-writer 的最小加载（~2,490 tokens）在同一量级。

8.2 Gate 机制的串行设计¶

4 个 Gate 串行执行，每个 Gate 有明确的 STOP 条件（不确定时停下来问用户），避免了在错误假设上累积工作。

8.3 Degradation Strategy¶

Level 1/2/3 的降级机制优雅处理了信息不完整的场景（虽然本次评估未触发）。

8.4 Anti-Examples 的教学价值¶

12 条 Anti-Examples 涵盖了常见的技术文档写作错误，与 Quality Scorecard 互补 — Scorecard 告诉模型"检查什么"，Anti-Examples 告诉模型"避免什么"。

8.5 Output Contract¶

结构化的输出报告使文档写作过程可审计，读者可快速了解文档的分类、受众、质量评分和假设。

九、评估材料¶