用途：ProductSpec 是一种 Markdown 格式，用于记录工单、工程计划和代码之前的产品决策，每个功能一个文件承载已确认的意图。本技能负责产出该文件，读完规格再据此开发属于另一项技能（productspec）的范围；本技能在文件通过校验时结束。
主要能力与格式要求：文件扩展名为 .product-spec.md，由 --- 包裹的 YAML frontmatter 加 ## 章节标题组成。六个必填章节按顺序为 problem、hypothesis、product_summary、scope、acceptance_criteria、success_metrics。标题匹配不区分大小写与分隔符，## Acceptance Criteria 与 ## acceptance_criteria 视为同一章节，惯例用标题式大小写。frontmatter 必填 spec_format_version: "0.1"、title、artifact_type（hypothesis | prd | openspec_proposal）、author、created_at、updated_at；可选 spec_revision、linked_github_repo、applies_to、custom_sections、tool_metadata。acceptance_criteria 与 success_metrics 各需一个必填围栏代码块，仅写散文无法通过校验。结构化 scope、AI evals 与相关工件为可选。结构化条目使用持久 id：AC-<number>、SM-<number>、EVAL-<number>，供其他文档引用。AI evals 放在 ## Acceptance Criteria 内，不单独设章节；相关工件放在 ## Related Artifacts 内。
使用方式：按任务只读一个参考文件——从零写规格读 references/authoring.md；校验并修复错误读 references/validating.md；转换已有 PRD 或功能文档读 references/converting.md；记录漂移、修订与结果读 references/decision-trace.md。校验命令：npm exec --yes --package @productspec/parser -- productspec validate <file>，其中 --yes 用于抑制 npm 交互式安装提示，避免 CI 与非交互式智能体卡住。完整规范定义见仓库 SPEC.md：https://github.com/gokulrajaram/ProductSpec/blob/main/SPEC.md，与本技能冲突时以 SPEC.md 为准。
限制与规则：不得重新编号持久 id，AC-2 必须始终指同一标准，新 id 追加在末尾。成功指标需要目标与时间窗口且代码块必填；若数值依赖上线后才有的基线，写 target: tbd 并加 target_status: provisional 与具名 target_owner，不得为通过校验而编造数字。保留章节内作者原有 Markdown，表格、列表、链接不应被压平。Scope 条目写成完整句子或祈使句，避免 search、storage 之类简短标签。spec_revision 仅在产品意图实质变化时递增，拼写或格式修改不递增。