用途
Describing products 是一个用于构建产品描述仓库的技能，适用于为某个软件产品编写按功能组织的说明文档。这里的“产品描述”把产品视为一张由用户输入推进的大状态图，仓库按功能逐个描述这张状态图，从用户视角用平实语言写出：用户看到什么、能做什么，以及在不同输入或中断下产品如何表现。每份文档使用同一骨架，便于通过对比暴露缺口和不一致。
相邻技能中，featuring 按能力盘点代码库做什么；本技能则规定每种能力在各类输入和中断下如何表现。一份 _FEATURES.md 可以作为本仓库结构的种子，但不能替代它。
主要能力
- 提供按产品形态（画布编辑器、Web 应用、CLI、聊天产品、库/SDK）映射模板的参考文件 references/product-kinds.md。
- 提供 README、目标说明、术语表、文档、验证清单与缺陷分诊的模板骨架。
- 内置两个仅用 Python 3 标准库的检查脚本：
- scripts/check_links.py：检查所有相对链接与标题锚点可解析（遵循 GitHub slug 规则）；对覆盖表中标记为“未开始”的文档链接报告为 planned，加 --strict 时视为损坏。
- scripts/check_structure.py：检查覆盖表与磁盘一致、章节顺序、页脚存在、修饰符/中断/关注点行在各文档间一致、无空单元格；--exclude 可指定额外的非功能文件。
- 两个脚本均接收仓库根目录，失败时退出码为 1。
使用方式
技能按阶段推进：
- Phase 0 范围界定：确定产品与界面、事实来源（源码仓库路径与提交）、运行方式、范围外内容、仓库位置、产品形态；并勘察源码仓库中交互状态、行为测试、UI 及默认值与阈值的定义位置。
- Phase 1 脚手架：按模板依次编写 README.md、glossary.md、goal.md、AGENTS.md、CLAUDE.md。
- Phase 2 试点与基础：先写一个小的、自包含但含真实交互的功能作为试点，确定模板、语气、深度和词汇；再写基础文档（输入/调用模型、核心对象/数据模型、模式/工具/导航模型、视口/会话模型）；最后写最难区域。
- Phase 3 并行起草其余文档：按文档或小簇分派子代理，要求遵守术语表、不修改共享文件与源码仓库，并汇总其提出的新术语。
- Phase 4 一致性检查：运行两个脚本（check_links.py 加 --strict、check_structure.py 加 --reference）确保退出码为 0，并通读全集检查术语一致、行为归属清晰、变体与中断答案一致。
- Phase 5 验证清单：编写 verification/README.md 及按文档簇的清单文件，每条可观察声明一行，含稳定 ID、优先级、前置条件、步骤、预期结果与结果列。
- Phase 6 缺陷分诊：汇总所有可疑缺陷，按根因合并，记录用户遇到的位置、实际与预期、复现步骤、代码原因、严重程度与待定决策；向上游提交 issue 属对外动作，须先征得用户同意。
对已有仓库的恢复与扩展：先读 AGENTS.md、README.md、goal.md、glossary.md 和试点文档，运行两个脚本了解现状，确认源码提交，再按新增文档或修订流程操作，且不得重新编号已使用的清单或分诊 ID。
适用场景
适合需要为软件产品编写系统化、可对比、可验证的功能行为说明文档的团队，尤其是希望统一文档骨架、从源码与测试起草、再对照运行产品核验并集中管理可疑缺陷的场景。产品形态可为画布编辑器、Web 应用、CLI、聊天产品或库/SDK。
限制
- 文档不应描述代码实现，而应描述用户体验；机制仅放在“Technical note”引用块中，且仅当它会改变用户预期时。
- 每个表格单元格都要填写，包括“No effect.”；空单元格视为未提出的问题。
- 当代码与测试无法确定某项行为时，只写它们能确定的部分，其余列入“Open questions”，不猜测、不阻塞。
- 不得修改源码仓库。
- 并行起草者不得写共享文件，新术语由主控方统一合并。
- 自动化检查只验证输出、退出码和存储状态，不验证屏幕内容或出现时长；不得仅凭自动化通过就将文档标记为已验证。
- 验证项失败不一定是产品缺陷，也可能是文档有误。
- 提交信息中 AI 署名需遵循目标仓库约定。
输出文件
README.md（目的、约定、文档模板、方法、结构、覆盖表）、goal.md（起草常驻指令）、glossary.md（术语来源）、AGENTS.md、CLAUDE.md、{area}/{feature}.md（每功能一份，同一骨架）、verification/（协议与按簇清单）、bug-triage.md（去重后的可疑缺陷）。