用途
generar-readme 用于生成面向外部评估者的 README.md。多数 README 是写给已有上下文的同事看的，而这个技能面向从未见过项目、只有几分钟时间判断项目是否可用、内容是什么的评估者、评委或评审。每个章节都按评估者实际提问的顺序回答一个具体问题：这是什么、我能运行吗、它是如何构建的、为什么这样构建、它真的能工作吗。主要产出是写入磁盘的文件：项目根目录下的 README.md。
主要能力
- 发现真实项目：读取清单文件确定技术栈和真实的安装、构建、运行脚本；检查 .env.example 或 .env.sample，若不存在则通过搜索代码中实际读取配置的方式（process.env.、os.environ.、os.Getenv、配置加载器）生成真实的 .env.example，不猜测变量名。
- 确定三命令快速开始：具体确定安装（真实的依赖安装命令）、配置（复制或填写 .env.example）、运行（启动项目的真实命令，按需选择开发或生产模式）。如果项目确实需要超过三个步骤（如数据库迁移、种子命令），会如实说明并列出真实步骤，不强行凑成三命令。
- 架构与技术栈：根据真实组件边界构建简短图表（紧凑的 Mermaid 图或清晰的文本图，视项目复杂度而定），并配以按层（前端、后端、数据、基础设施）划分的技术栈表，使用清单中实际锁定的版本。
- 关键决策：如果存在 adrs/*.md，逐条列出并用一行总结其决策，附上直接相对链接（adrs/000X-slug.md）；如果没有 ADR，则完全省略该章节，而不是写没有实质内容的假决策。
- 演示与执行摘要：向用户索取演示链接或视频；执行摘要基于 PRD.md 的问题和目标用户章节撰写，否则直接向用户索取一段问题陈述；学习心得直接向用户索取，不编造。
- 写入文件：使用 assets/readme-template.md 组装 README.md。如果已存在 README.md，会询问是覆盖还是将新章节合并到现有结构中，不会静默替换用户可能手写的内容。
使用方式
技能需要以下输入：项目自身文件（清单文件、.env.example、docker-compose.yml、入口脚本）；PRD.md（如存在，用于执行摘要的问题陈述，否则向用户询问一两句话的问题描述）；TECH-DESIGN.md 和 adrs/*.md（如存在，用于架构章节和关键决策列表，否则直接从仓库实际结构和服务推导架构描述，并省略关键决策章节）；演示链接或约 3 分钟视频（向用户索取，不伪造 URL，若暂无则明确写“待定”而非占位链接）；执行摘要的学习心得（直接向用户询问，不用“我们学会了团队合作”之类的通用填充）。
工作流程为：发现真实项目、确定三命令快速开始、架构与技术栈、关键决策、演示与执行摘要、写入文件。
README.md 章节顺序
- 标题与一句话简介
- 执行摘要（问题、面向谁、学习心得）
- 演示（链接或约 3 分钟视频）
- 快速开始（安装、配置、运行——真实命令）
- 架构（图表与技术栈表）
- 关键决策（ADR 链接）——仅当存在 ADR 时
- 仓库结构（可选，仅当能补充文件夹树本身无法说明的内容时）
质量门禁
返回前会静默检查：快速开始中的每条命令都对照项目中真实脚本或入口点验证过，没有根据“这类项目通常怎么运行”编造；.env.example 要么原本存在，要么根据代码中真实的 env 变量读取生成；没有伪造的演示 URL，若未提供则明确写“待定”而非占位链接；学习心得和问题陈述（无 PRD 时）来自用户，而非通用填充；架构章节反映仓库中实际发现的组件，而非默认套用的通用三层模板；关键决策仅在存在真实 ADR 可链接时出现。
适用场景
适合需要向外部评估者、评委或评审展示的项目，尤其是希望对方能在几分钟内理解项目并实际运行起来的场景。也适合需要规范化 README 结构、确保命令真实可执行的开发项目。
限制
技能不编造功能、命令、URL 或学习心得；缺少 PRD、演示链接或学习心得时会向用户索取。如果项目确实需要超过三个步骤，会如实列出而非强行压缩。没有 ADR 时不会生成关键决策章节。如果已存在 README.md，会询问覆盖或合并，不会静默替换。