Readme Authoring Skill
职责
当任务目标是 README.md 或项目主用户使用文档时，本 Skill 负责把“写什么、先写给谁看、哪些内容必须后置”收口为一套稳定规则。
它不新增 workflow 子类型，仍由 dev-docs / dev-init 触发。站点文档、最终用户手册、接入手册和公开能力页的主入口由 user-manual-authoring 承担；本 Skill 是其中的 README 专项分支。
触发条件
| 场景 | 是否触发 |
|---|---|
新建或改写 README.md | 🔴 必须 |
| 初始化项目时生成 README | 🔴 必须 |
| 面向真实使用者且落点为 README / 项目主文档 | 🔴 必须 |
| 站点文档、最终用户手册、接入手册、公开能力页 | 先触发 user-manual-authoring，落点为 README 时再叠加本 Skill |
| CONTRIBUTING / 架构文档 / 纯开发指南 | N/A |
默认受众模型
README 的默认第一受众必须是用户 / 使用者，而不是维护者。
这里的“用户 / 使用者”指真实依赖这份文档完成理解、安装、启动、接入、使用或排错的人；可以是外部用户，也可以是内部同事。
| 字段 | 默认值 | 说明 |
|---|---|---|
primaryAudience | 用户 / 使用者 | README 主叙事默认面向真实读者 |
secondaryAudience | 开发者 / 贡献者 / 维护者 | 仅作为后置补充受众 |
developerInfoPlacement | 后置 | 开发、贡献、维护内容不得抢占主叙事 |
README 写作契约
| 字段 | 必填 | 说明 |
|---|---|---|
primaryAudience | ✅ | 默认 用户 / 使用者 |
secondaryAudience | 条件 | 可选 开发者 / 贡献者 / 维护者 |
projectType | ✅ | library / service / application / tool |
userJourney | ✅ | 理解 -> 安装/接入 -> 启动/运行 -> 使用 -> 配置 -> 排错 |
targetSurface | ✅ | public-docs-site / project-readme-docs / requirement-deliverable / maintainer-only，不得未确认就把需求交付文档挂入项目 README/docs |
primarySurfaceCheck | ✅ | 首页首屏、quick start、nav/sidebar 前两组、CTA、reference、配置、常见任务和排错是否服务用户使用路径 |
immediateComprehension | ✅ | 功能完整性、配置易懂性、首次读者即时理解三轴结论 |
deliveryChain | 条件 | docs-first / 最终用户手册场景填写 UserFacingDeliveryChainGate：确认需求事实源、用户最终文档、条件契约文档、技术方案输入和 ECR 用户文档符合性 |
siteInformationArchitecture | 条件 | 文档站填写 DocsSiteInformationArchitectureGate：用户手册、reference、operations、compatibility、implementation、maintainer 面各归其位 |
flowAndFailurePath | 条件 | 最终用户手册填写 UserManualFlowAndFailureGate：整体流程、关键角色、第一次成功、失败分流、排查命令、恢复/降级 |
realWorkflowExample | 条件 | 队列 / 任务 / 异步 / 批处理类 quick start 填写 QueueDocsRealWorkflowGate，不能用单个硬编码 job 代替主路径 |
developerInfoPlacement | ✅ | 必须晚于快速开始、常见用法、配置与排错 |
consumerMap | ✅ | README 与 package.json / CLI / website / examples / changelog / Profile 的关联事实 |
章节顺序规则
推荐主顺序：
- 这是什么
- 适合谁、何时使用
- 如何快速开始
- 常见用法 / 最短可成功路径
- 配置 / 运行要求
- 常见问题与排错
- 进一步文档
- 开发 / 贡献 / 维护说明
docs-first 最终用户手册的顺序必须服务目标版本最终可执行路径；未实现、preview 或内部开发状态只能放在发布状态、限制说明或维护者区域，不能成为首屏、quick start 或 reference 主叙事。
禁止把以下内容前置为主叙事：
- 维护者内部流程
- 贡献约定
- 大段架构设计
- 与使用者无关的目录说明
项目类型差异
| 项目类型 | 用户最关心的信息 | 写作重点 |
|---|---|---|
library | 怎么安装、怎么 import、最小示例 | 依赖、最短调用、返回值示例 |
service | 怎么启动、端口/依赖、调用入口 | 启动命令、环境要求、运行方式 |
application | 怎么进入界面、登录/前置条件、核心操作 | 快速体验路径、主要页面或操作 |
tool | 怎么执行命令、输入输出、常见任务 | CLI/脚本入口、常见命令、输出示例 |
性能 / 语法 / 能力矩阵写法
- README 面向使用者时，性能表、语法说明、能力矩阵或路由/匹配模式说明必须先给“如何选择”的结论，再解释字段和内部术语。
- 语法、路由、匹配、配置能力类章节默认同时包含：支持的形式、明确不支持的形式、优先级或冲突示例。
- 性能数据不得只给 benchmark 术语；应说明每一列对用户选择的含义，并标明测试条件或 N/A 理由。
执行步骤
- 判断
projectType。 - 确认真实
primaryAudience是否为外部用户、内部使用者或协作方。 - 执行
UserDocsPrimarySurfaceGate：冻结targetSurface、documentLocation、首页/quick start/nav 主面和开发/维护内容后置策略。 - 执行
UserDocsImmediateComprehensionGate：写出功能覆盖、配置易懂、首次读者即时理解的三轴检查。 - docs-first / 最终用户手册场景执行
UserFacingDeliveryChainGate与FinalUserManualFirstGate，确认 README / 文档站内容来自已确认需求或产品需求，而不是未确认的整理草稿。 - 文档站执行
DocsSiteInformationArchitectureGate；最终用户手册执行UserManualFlowAndFailureGate；队列/任务/异步/批处理类 quick start 执行QueueDocsRealWorkflowGate。 - 按
userJourney组织章节，不要从开发命令开始。 - 只保留与当前项目类型相关的快速开始与示例块。
- 建立
consumerMap，核对 README 与package.json、CLI、website、examples、changelog、Profile 是否一致；公开能力页追加UserPathContractSweep。 - 交付后若任务要求 review，再调用
audit-readme。
与其他 Skill 的关系
user-manual-authoring：站点文档、最终用户手册、接入手册和公开能力页的优先入口；README 是其专项分支。dev-docs：判断当前文档是否需要进入user-manual-authoring或 README 专项分支。dev-init：初始化项目时默认用本 Skill 生成 README。document-sync：代码/规范变更后检查 README 当前消费者与consumerMap。audit-readme：实施完成后对 README / 用户使用文档做专项 review。
禁止
- 禁止把 README 默认写成“维护者操作手册”。
- 禁止让开发/贡献章节出现在快速开始之前。
- 禁止只写架构或目录而不给真实使用路径。
- 禁止把“站点文档 / 用户使用文档”写成开发契约、目标 API、数据模型或实现验收主叙事；这些内容只能后置或标为 developer/maintainer-only。
- 禁止把 docs-first 最终用户手册写成当前 preview / 当前不可用说明，也禁止把最终用户手册当成整站全部内容容器。
- 禁止队列、任务、异步处理、推送、导入导出或批处理类 quick start 只写单个硬编码 job；单 job 只能作为 API micro example，不能替代真实批量工作流。
- 禁止用内部分类名、benchmark 术语或 provider/adapter 实现名抢占用户主叙事；应先写用户场景与选择建议，再引出 API / 模式名称。
