tsubaki-01/tsubaki_skills/writing-readme

编写与更新 README

为指定目标写出准确、便于使用的 README。可处理新建、完整重写或局部更新，工作范围由本次请求决定，不因技能同时覆盖多种任务就全部执行。

用 grilling 确定本次写法

先从请求、已有 README 和项目入口确认目标范围；多个项目或包都可能是目标时，澄清选择。只做足以理解任务的初步读取，不先扫描整个仓库。

调用 grilling，共同确定本次读者要完成什么、README 应写到什么深度。可以是帮助首次使用者快速上手，也可以是包含实现架构、执行链路与维护方式的技术导览。不要预设所有调用都需要完整技术导览。

把请求中已经明确的读者、深度和修改范围带入 grilling，不重复询问已经回答的事项。只讨论尚未确定且会改变文档的写作取舍；文件中能查到的事实由 agent 查证，不交给用户补课，也不把这轮问答扩展为整体系统设计。

沿用项目的主语言、文件名、互链和文档布局。用户明确要求改变时再调整。新项目没有语言约定、请求也未指定时，写一份与请求语言一致的 README.md；不默认增加翻译版本。

查明要写的技术事实

围绕已选范围查阅包或项目清单、公开入口、有关实现、现有测试及维护中的示例。需要架构或维护者导览时，再追踪相关调用链和开发脚本。相邻包、全仓目录和 CI 并非每次必读材料。

分清依据的角色：用户与项目指令决定写作目标；导出、入口和项目约定说明受支持的接口；代码说明当前实现；测试和示例提供特定情境下的预期或使用证据。它们冲突时说明冲突及影响，不用一份固定排行榜把计划中的能力写成已实现事实。

重点核实将出现在文档中的内容：

• 用途、范围、真实运行要求、安装或运行方式。不能仅从包名推断它已发布。
• 受支持的导入、命令、配置、类型和扩展入口。能访问的内部实现不自动等于公共 API；实验性状态按项目证据标明。
• 会影响正确使用的参数、默认行为、返回结果、状态、生命周期与必要失败行为。
• 所选深度需要的模块职责、主执行路径、改动位置和已有开发命令。

对重要技术结论保留可回查的文件或符号，在有助于读者导航时链接源码。没有查证的能力不写成保证；关键冲突需要用户决定时继续 grilling，其余有依据的内容可以完成。

围绕读者任务组织内容

让开头清楚回答“它做什么”和“怎样开始”。最小示例使用真实受支持的入口，交代必要前提、操作及可观察结果，使读者能完成一个正常流程。

按共同确定的深度展开。技术导览应说明模块怎样协作、关键数据或控制如何流动，以及这些关系对使用和修改意味着什么；不要用逐文件清单代替解释。API 较多时按能力分组并链接已有完整参考，不把 README 变成全部符号目录。

维护者内容使用实际项目脚本和约定说明环境、测试、构建与修改入口，不发明贡献或发布流程。图能更清楚地解释关系时再使用简洁 Mermaid，不为每份 README 强制配图、徽章或固定章节。

更新已有 README 时，保留仍准确的内容、有效链接、项目语气和结构，只修改过时或本次需要补充的部分。深入细节已有独立文档时优先链接，避免重复整份说明；也不要为了采用模板重排项目文档。

请求双语或更新一组语言版本时，从同一组技术事实编写自然的各语言说明，沿用已有文件名和互链。代码、命令、路径、数值与行为含义保持一致，文字可以适应语言表达。只维护本次请求涵盖的版本。

核对并交付

对照实际入口检查这次新增或变化的名称、参数、配置、命令和示例。检查改动涉及的相对链接和图表是否指向真实内容；仓库内部文件尽量使用相对链接。

对新增或实质修改、且当前环境可执行的关键示例做针对性验证。纯文字调整不要求运行功能测试，也不批量执行所有代码块或把全量测试当作文档交付前提。验证暴露问题时先区分示例错误与实现问题，不为了写 README 擅自修改产品代码。

交付所修改的 README 路径、主要变化及实际验证结果，说明无法核实而影响读者使用的内容。除本次 README 和 grilling 所需决策记录外，不扩展到实现、许可证、贡献或其它文档的修改，除非用户要求。