xinetzone/SpecWeave / .agents/skills/knowledge-bundle-naming-audit
knowledge-bundle-naming-audit
Verified当用户认为知识包目录名、标题或副标题与内容不符,担心名称承诺过宽、中英不一致或暗含开发/代写/部署等未覆盖能力时,必须使用此技能。只读流程:盘点并全文读取 bundle → 映射实际主题与读者任务 → 对候选名做范围承诺、中英一致与误导含义检查 → 独立反向审查 → 输出中文标题、英文目录名与范围或日期限定;结论固定标记待确认,重命名与提交需另行授权。不用于生成知识包、交付门禁、方法论编排或通用研究报告。
知识包命名审计 Skill
用户说"这个名字不太准确"时,先把内容读全,再谈名字。
1. 这个技能解决什么
知识包(bundle)的目录名、标题与副标题,是读者和检索系统看到的第一句承诺。名字比内容宽,读者会按名字预期并不存在的能力;名字比内容窄,真实价值又检索不到;中英文名各说各话,同一份包在两个入口被描述成两件事。
本技能只做一件事:在不修改任何文件的前提下,用读到的内容判断一个名字是否准确,并给出可复核的替代建议。
适用信号:
- "这个 bundle 名字不太准确 / 范围不对 / 太宽 / 太窄"
- "目录名和内容对不上" "标题像在承诺开发、代写或部署,但包里没有"
- "中文名和英文目录名不一致" "研究快照该不该在标题里写日期"
不适用(换轨):
| 任务 | 交给 |
|---|---|
| 从文章生成新 bundle | wechat-public-okf |
交付前跑 toctree、UTF-8、索引门禁,写 log.md | okf-bundle-delivery-review |
| 方法论编排(复盘、洞察、萃取、提交) | seven-concepts-cmd |
| 通用研究报告与竞品分析 | research-guide |
| 真正执行重命名或提交 | 本技能不执行;需用户单独授权后按仓库提交规范处理 |
为什么? 命名审计最容易越界成"顺手把名字改了"。一旦改动文件,审计结论就与工作树状态绑在一起,别人无法判断是"名字变准了"还是"内容被改得迎合名字"。只读把判断与变更分开。
为什么? 名字的准确性只能由内容证明,不能由推荐 JSON、bundle 自述或历史结论证明。上游材料常把"看起来覆盖"写成"已经覆盖",所以必须回到文件本身建立证据。
2. 输入与前置
| 输入 | 必填 | 缺失时 |
|---|---|---|
| bundle 目录绝对路径 | 是 | 停止,请用户给出路径;不按名字猜目录 |
| 候选标题或目录名 | 否 | 从 S1 的主题映射结果提名 |
| 是否已有"已定名"结论 | 否 | 默认没有;把任何既有结论视为待验证候选 |
预检(只读):
lsbundle 目录,确认含index.md;不存在则停止。- 列出全部
.md文件(含子目录),得到总数 N。 - 记录
git status --short -- <bundle>,作为"本轮未改文件"的基线。 - 若用户提到其他会话或推荐给出的结论,只当线索,不当证据。
为什么? 先固定文件清单和 git 基线,后面才能证明审计没有改动内容,也才能在文件被并行修改时发现结论已过期。
3. 决策树
收到命名疑问
├─ 目录不存在或没有 index.md? → 停止:先确认路径,不猜内容
├─ 关键文件未读全? → 降级:结论限定为"基于已读 N/M 个文件",列出未读清单
├─ 用户给了候选名? → 直接进入 S2 逐项审查
└─ 没有候选名? → 先做 S1 主题映射,再从实际主题提名(S4)
4. 工作流(S0–S5,全程只读)
S0 盘点与覆盖台账
- 列出全部 Markdown 文件,逐个记录"已读/未读"和用途(索引、概念、参考、日志、示例)。
- 优先读
index.md、概念目录、事实台账与核验记录;这些决定"包实际承诺了什么"。 - 输出覆盖台账:
已读 X / 总数 N;未读文件逐条列出并说明是否影响结论。
S1 映射实际主题与读者任务
- 每个概念文档提炼一句"它实际讲什么",不抄标题。
- 汇总读者能完成的任务(读完能做什么),与文档实际提供的步骤一一对应。
- 单列"包明确不提供的能力":没有代码、没有部署步骤、没有代写服务、没有跨平台投稿流程等,按实际内容写。
- 核对内部口径:若文中已声明某类对象不宜合并称呼,后续命名不得把它们并成一个总称。
S2 候选名三项检查
对每个候选名逐项判定并留证:
| 检查 | 问题 | 不通过的表现 |
|---|---|---|
| 范围承诺 | 名字承诺的能力,内容是否真的覆盖? | 名字含"开发、代写、部署、多平台发布",正文只有选题、素材与提交流程 |
| 中英一致 | 中文标题与英文目录名是否表达同一范围? | 中文"参赛准备",英文 publishing;或中文很窄、英文很宽 |
| 误导含义 | 是否有歧义、同音、行业黑话或过度营销? | 把"提交材料"读成"代提交";把"研究快照"读成"官方指南" |
同时检查时效性:内容若是某一日期的研究快照,名字或副标题应注明范围与日期,避免读者把它当长期有效的权威结论。
S3 独立反向审查
- 用四个视角攻击入围候选:陌生人(只看名字会以为什么)、检索者(会用什么词找它)、内容维护者(名字是否逼着以后写不属于包的内容)、范围审查者(名字是否超出证据)。
- 每个被否掉的候选保留否决理由;只留最终答案会让下一轮无法复核。
- 若所有候选都不成立,允许结论是"证据不足,暂不改名"。
S4 产出命名建议
输出三件套,范围必须一致:
- 中文标题:面向读者,直接说明内容与读者任务。
- 英文目录名:kebab-case,与中文标题同范围,不用宽泛总称。
- 副标题或限定(按需):平台范围、内容边界、研究快照日期。
状态固定写"待确认";不得写成"最终名称"或"已批准"。
S5 只读收尾
- 不重命名目录、不改
index.md、不写log.md、不提交。 - 若用户要求执行改名:先给出改动面预览(旧路径到新路径、受影响的 toctree、索引与链接),等待单独授权;执行与门禁交给交付流程,不在本技能内完成。
- 复跑
git status --short -- <bundle>,确认与基线一致。
为什么? 把建议与执行分开,才能让用户在不承担改动风险的情况下比较多个名字;确认后再改,也只改一次。
5. 输出模板
结论:建议改名 / 保留原名 / 证据不足
覆盖:已读 X / 共 N 个文件;未读:...
实际主题:...
读者任务:...
明确不提供:...
候选名判定:
| 候选 | 承诺范围 | 内容覆盖 | 中英对齐 | 判定 | 理由 |
推荐:中文标题「...」|英文目录名 `...`|副标题「...」
状态:待确认(未获用户批准;未重命名、未改文件、未提交)
缺口:...
下一步:需单独授权的动作
6. 命名判定矩阵
| 观察 | 合理判定 | 错误判定 |
|---|---|---|
| 名字含"发布",正文只讲提交材料准备 | 范围过宽,收窄到实际覆盖的任务 | 名字没问题,反正读者会看正文 |
| 中文标题与英文目录名范围不同 | 中英不一致,必须统一 | 英文只是技术标识,无所谓 |
| 候选名来自推荐 JSON,未被用户确认 | 待验证候选 | 已定名,直接沿用 |
| 内容为单日研究快照 | 名字或副标题注明日期与范围 | 当作长期权威结论命名 |
| 包内已声明三类对象不宜统一称呼 | 名称不得合并为一个总称 | 用"三场××"概括 |
| 关键文件未读 | 结论限定范围并列缺口 | 按目录名推断内容 |
7. Gotchas(隐性陷阱)
| # | 陷阱 | 表现 | 正确做法 |
|---|---|---|---|
| 1 | 用 bundle 自述当事实 | 照抄 index 里的"覆盖全流程" | 回到概念与参考文档核对实际步骤 |
| 2 | 把文件数当内容 | 用"15 篇文档"支撑一个宽名字 | 名字描述内容与任务,不描述文件数量 |
| 3 | 名字比内容宽 | 正文没有开发或部署,名字却写"开发与发布" | 删掉未被覆盖的能力词 |
| 4 | 中英各说各话 | 中文"参赛准备",英文 publishing | 两侧表达同一范围,必要时加限定 |
| 5 | 用状态给名字背书 | "因为包是 draft,所以名字可以宽" | 状态与命名无关,按内容判定 |
| 6 | 复用被内部否定的统称 | 文中说三类对象不宜合并,名字仍用总称 | 采用文中已确认的称呼粒度 |
| 7 | 把建议写成已批准 | 报告写"最终名称已确定" | 固定写"待确认",并列出授权缺口 |
| 8 | 审计顺手改文件 | 边审边改 index 或重命名目录 | 只读;改动需单独授权与预览 |
| 9 | 忽略时效 | 研究快照名字不写日期 | 用副标题注明范围与日期 |
8. 安全检查清单
执行前逐项确认:
- 已确认 bundle 路径存在且含
index.md - 已列出全部 Markdown 文件并记录已读/未读
- 实际主题与读者任务来自文件内容,未照抄 bundle 自述
- 每个候选名都有范围承诺与覆盖证据
- 中文标题与英文目录名表达同一范围
- 已做独立反向审查并保留否决理由
- 结论标记"待确认",未声称用户批准
- 时效性内容已在副标题注明范围或日期
- 未重命名、未修改 bundle、未写
log.md、未提交 - 结束时
git status与基线一致
为什么? 这张清单对应本技能两类失败:把"读了一部分"当成"读全了",以及把"建议"当成"已执行"。两者都不会报错,只能靠逐项核对拦住。
9. 幂等与重入
| 探针 | 状态 | 重入动作 |
|---|---|---|
| 同一 bundle 已有审计结论 | 文件清单与 mtime 未变 | 复用结论,不重复全文读取 |
| 同一 bundle 文件有新增或修改 | 清单变化 | 只重读变更文件,更新覆盖台账与结论范围 |
| 用户已确认推荐名 | 已获明确批准 | 停止提名,转为改动面预览;执行需另行授权 |
| 候选名被用户替换 | 新候选 | 回到 S2 与 S3,不沿用旧判定 |
| 结论为"证据不足" | 未读文件仍不可得 | 保留该结论,不凭目录名补推 |
10. 变更记录
| 版本 | 日期 | 变更 |
|---|---|---|
| 1.0.0 | 2026-10-28 | 初始版本:只读覆盖台账、主题与读者任务映射、候选名三性检查、独立反向审查、待确认命名建议、只读边界与重入规则;萃取自会话 afb0eaf2-dff2-41f6-a96d-5a88922d8709 的 bundle 命名质疑实战 |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |