name: generate-standard-readme
description: 创建专业、规范的项目 README 文件。包含完整的结构、安装说明、使用示例、贡献指南等，适用于开源及企业内部项目。
tags: [documentation, eng-standards, devops, writing]
related_skills: [decontextualize-text]
version: 1.2.0
recommended_scope: user

Skill: 生成标准 README (Generate Standard README)

目的 (Purpose)

为各类软件项目（包括开源仓库、内部中间件、微服务、工具链等）创建专业、规范、高可读性的首页文档。通过标准化的信息组织架构，降低成员协作成本，提升工程规范性，并确保核心资产的“可发现性”。

适用场景 (Use Cases)

• 新项目基建：为新启动的工程快速同步一套标准的说明文档。
• 资产治理 (Asset Governance)：统一企业内部微服务或库的 README 风格，提升内部搜索引擎的索引质量，方便跨团队发现和调用。
• 审计与合规 (Audit)：为遗留系统 (Legacy Systems) 补齐文档，确保存量资产在内部审计或架构评审时符合工程标准。
• 移交与发布 (Handovers)：在项目跨部门移交、人员变动或对外发布时，确保接收方能无障碍地理解项目全貌。

何时使用：当项目需要一份“第一面孔”来向他人解释其存在价值、使用方法及协作方式时。

行为要求 (Behavior)

核心原则

• 清晰性：第一眼就能理解项目是什么、解决什么问题。
• 完整性：包含用户和贡献者需要的所有必要信息。
• 可操作性：提供“粘贴即用”的安装和快速开始命令。
• 专业性：使用标准的 Markdown 语法和业界公认的章节顺序。

语气与风格 (Tone & Voice)

• 使用客观、中性的语言；避免夸张词汇（如“The best,” “Revolutionary”），除非有数据支持。
• 直接、简洁：短句为主，少用堆砌形容词和“文绉绉”表述；专业性通过清晰、可操作、可扫读来体现，而非公文式用语。
• code 示例简洁，注释清晰。

视觉元素 (Visual Elements)

• 徽章 (Badges)：顶部应包含 License、Version、Build Status 等必要徽章。
• 分隔符：使用 --- 或标题层级清晰划分章节。
• Emoji：适度使用 Emoji（如 📦, 🚀, 📖）增加可读性。

输入与输出 (Input & Output)

输入 (Input)

• 项目元数据：项目名称、一句话描述。
• 功能列表：核心特性描述。
• 环境要求：Node.js 版本、Python 版本等。
• 安装/运行方式：具体的 Shell 命令。

输出 (Output)

• 标准 README 源码：遵循以下层级的 Markdown 文本：
• 项目标题与徽章
• 核心项目描述
• ✨ 功能特性
• 📦 安装
• 🚀 快速开始
• 📖 使用文档/配置
• 🤝 贡献指南
• 📄 License
• 👤 作者与致谢

禁止行为 (Restrictions)

• 禁失效链接：严禁提供无法访问的 404 链接。
• 禁重复引用：同一信息（如 License 类型）不要在不同章节重复多次。
• 禁硬编码路径：在安装和快速开始示例中，使用通用的占位符或变量。
• 禁缺失协议：必须明确声明开源协议，严禁遗漏 License 章节。

质量检查 (Self-Check)

• [ ] 三秒原则：普通用户能否在 3 秒内读懂项目是做什么的？
• [ ] 闭环测试：按照安装步骤，能否无障碍地跑通“快速开始”？
• [ ] 语气：表述是否直接、简洁，无文绉绉或公文感，读起来像专业文档而非汇报材料？
• [ ] 徽章一致性：徽章链接是否指向了正确的分支或文件？
• [ ] 移动端兼容：表格和长代码块在窄屏下是否可读？

示例 (Examples)

Before vs. After 对比

Before (简陋版本)：

MyProject

这是一个处理图片的程序。
安装：pip install .
运行：python run.py

After (标准版本)：

MyProject

这是一个基于 AI 的高性能图片批处理工具，旨在通过并发加速图像压缩任务。

---

✨ 功能特性

• 并发压缩：支持多线程处理，比原生工具快 3 倍。
• 格式支持：支持 WebP, PNG, JPEG 的互相转换。

---

📦 安装

bash pip install my-project

---

🚀 快速开始

python from myproject import Compressor Compressor('images/').run()

边界示例：信息极少的遗留项目

• 输入：项目名：legacy-auth。描述：无。功能：无列表。环境与安装方式未知。
• 预期行为：仍产出结构完整的 README；在缺失处使用占位符（如「功能见源码」「安装方式待补充」）并明确标注「待补全」，不虚构功能或命令；保留徽章、章节顺序与 License 声明，便于后续补齐。

参考资源

• GitHub README Documentation
• Awesome README Collection
• Shields.io (Badge Generator)