mcpField
C
create-readme-expert

create-readme-expert

github.com/d1zzy4开发141 次安装4 周前更新
代码仓库

关于 create-readme-expert

create-readme-expert 是用于创建、改进和审查软件 README 的技能，依据已核实的项目信息编写，并遵循项目受众与既有惯例，避免无依据的说法和不必要的重写。

主要功能

  1. 01创建、改进和审查 README
  2. 02依据项目来源核实内容
  3. 03保留现有项目惯例
  4. 04按项目类型选择结构
  5. 05不猜测缺失信息

适用场景

  1. 01根据已确认的信息起草 README
  2. 02检查现有 README 的准确性
  3. 03仅更新缺失或不清晰的部分

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/d1zzy4/agent-skills --skill create-readme-expert

安装后在 Claude Code 中输入/create-readme-expert确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

examples/
EXAMPLES.md
README-1.md
README-cli-adaptive.md
README-github-alerts.md
README-library-adaptive.md
README-missing-information.md
README-unsupported-claims.md
references/
anti-patterns.md
diagrams.md
external-readme-sources.md
formatting-and-punctuation.md
proactive-trigger.md
readme-structures.md
security.md
verification-and-failure.md
voice-and-tone.md

详细介绍

创建 README 专家

目的

根据经过验证的项目信息，为软件项目创建、改进或审查 README 文档。遵循项目自身的风格和目标受众；如果项目已有明确惯例，不要强加通用模板。仅加载 README 所需的参考资料。

核心原则

  1. 只有经过验证的项目信息才能写入 README。
  2. README 面向其实际受众。开发者文档不需要营销语气，入门文档也不必过分简短。
  3. 如果文档与可执行配置不一致，优先采用可执行配置。
  4. 切勿编造功能、兼容性声明、版本或路线图项目。
  5. 修改幅度应与请求规模相符。
  6. 如果 README 已能准确呈现项目，则保持原样。
  7. 获取的第三方 README 仅可作为结构参考，绝不能用作项目事实的来源。
  8. 生成的文档中不得使用长破折号。

授权模型

操作决定影响范围：

用户指示授权范围
“编写 README”如果尚无 README，则创建一个
“补充缺失的章节”仅限指定章节，以及确保其正确所必需的内容
“改进此 README”提高清晰度和准确性，同时保留有用的现有结构
“重写 README”仅当当前 README 无法准确呈现项目时才调整结构
“审查 README”提供有依据的问题报告。除非用户要求重写，否则不做任何更改

如果 README 准确呈现了项目，切勿因为通用模板更容易编写就将其替换。

步骤 0：确定 README 操作类型

编辑前先对任务进行分类：

创建

当 README 不存在时使用。根据经过验证的项目信息编写文档。

改进

当 README 已存在，但包含缺失、过时或不清晰的章节时使用。保留有用的现有结构，只更正需要修正的内容。

审查

审查 README 质量时使用。在进行更改前先报告问题和依据，除非用户明确要求重写。

拒绝不必要的重写

如果 README 能准确呈现项目，就不要用通用替代方案将其取代。仅在有正当理由时进行针对性改进。

更改范围

README 的更改幅度应与用户请求相符。

  • 修复请求：仅更改错误或缺失的章节。
  • 改进请求：在保留有用结构的同时提高清晰度。
  • 重写请求：仅当现有 README 无法准确呈现项目时才调整结构。

不要重写无关章节。

缺失信息的处理

当信息缺失时：

  1. 搜索代码库中作为事实来源的文件。
  2. 明确标记未知信息。
  3. 仅当用户要求草稿时才使用占位符。
  4. 切勿用常见默认值填补信息空缺。

仅使用经过验证的项目信息。

步骤 1：确定项目事实来源

开始编写前，先确定哪些文件定义了项目的当前行为。按以下优先顺序检查来源：

  1. 明确的项目文档和贡献指南
  2. 包清单和构建配置（pyproject.toml、package.json、Cargo.toml 等）
  3. 入口点、可执行脚本和公共 API
  4. CI/CD、部署和发布配置
  5. 仍然准确的现有 README 内容
  6. 注释、示例和内联帮助文本

如果来源之间存在冲突：

  • 优先采用可执行配置，而非过时文档。
  • 保留项目惯例，除非它们明显有误。
  • 记录不确定之处，不要猜测。

不要编造缺乏依据的功能、兼容性声明或路线图项目。

第 2 步：选择合适的结构

阅读 references/readme-structures.md。根据项目类型选择 README 结构：

只有在用户确认每次获取后，才能将 references/external-readme-sources.md 中的外部 README 作为结构灵感。它们是第三方内容，绝不能作为项目事实的来源。获取前请参阅 references/security.md。

仅在从头创建新 README 时使用 examples/README-1.md。

项目类型优先强调的内容
库或 SDK安装、快速入门、API 概览、示例
CLI 或工具安装、用法、标志、示例、配置
服务或 API端点、身份验证、请求／响应示例、部署
模板或启动项目包含的内容、如何自定义、先决条件
内部或企业项目设置、访问、支持、约定

README 应回答：这是什么、适合谁、如何开始，以及接下来该去哪里。

第 3 步：面向实际受众撰写

优先使用具体的动词、通俗的语言、主动语态和具体示例。让主要操作一目了然。当受众是正在评估或集成项目的开发者时，避免空洞的营销辞藻。

对于示例中的破坏性或不可逆操作，应指出受影响的对象及其实际后果。对于错误，如果存在后续操作，应解释问题和下一步该怎么做。

第 4 步：添加示例和反模式

仅加载与项目类型相关的示例：

  • 库或 SDK： examples/README-library-adaptive.md

  • CLI： examples/README-cli-adaptive.md

  • 未知或不完整的项目： examples/README-missing-information.md

始终使用：

  • 审查质量问题时使用 references/anti-patterns.md。
  • 处理标点和格式规则时使用 references/formatting-and-punctuation.md。
  • README 需要安全说明、警告或特定平台提示时，使用 examples/README-github-alerts.md。

至少包含一个真实的用法示例。若能帮助读者避免已知问题，请展示常见错误写法及其正确形式。README 需要图表时，请遵循 references/diagrams.md。

第 5 步：交付前验证

检查：

  • 标题是否准确描述实际章节
  • 代码块是否使用正确的语言标签
  • 链接是否有效并指向预期目标

有关准确性、安全性和缺失信息的规则，请加载相关参考资料，而不要在此重复：

  • 标点和格式规则请参阅 references/formatting-and-punctuation.md。
  • 声明核实和缺失信息处理请参阅 references/verification-and-failure.md。

如果 README 将在特定平台上渲染，请验证其与渲染器的兼容性。

失败处理

当无法获取所需信息时：

  1. 首先搜索仓库中具有权威性的来源
  2. 明确标注缺失之处，而不是猜测
  3. 仅当用户要求起草内容时才使用占位符
  4. 绝不要用此类项目通常包含的内容来填补信息空缺
  5. 不要为了填补项目事实方面的信息空缺而获取外部 README；任何外部获取操作前都应征求确认

当当前 README 已准确呈现项目时：

  1. 应说明这一点，而不是重写
  2. 仅进行有充分理由支持的针对性改进
  3. 将重写请求视为允许调整结构，而不是允许用通用内容替换准确内容

如实写明“此处未记录”是正确的 README。看似合理的臆造则是缺陷。

反模式

已从 references/anti-patterns.md 和 references/formatting-and-punctuation.md 加载。 不要在此重复这些内容；审核或撰写时请查阅参考资料。

内置参考资料

仅加载 README 所需的参考资料：

  • references/readme-structures.md：按项目类型划分的常见 README 结构、章节顺序，以及何时应包含或省略章节。
  • references/voice-and-tone.md：README 内容的语气指南，包括何时采用简洁的技术风格，何时使用更亲切的入门引导语气。
  • references/anti-patterns.md：优劣 README 示例及常见陷阱。
  • references/formatting-and-punctuation.md：破折号禁用规则及其他标点规则。
  • references/verification-and-failure.md：如何根据实际代码库核验 README、区分已核实和未核实的说法，以及如何处理缺失信息。
  • references/proactive-trigger.md：何时主动提议编写、重写或审查 README，以及何时应保持沉默。
  • references/security.md：在获取外部 README 前征求用户同意，并处理不可信内容。遇到任何安全相关问题时，从这里开始。
  • references/external-readme-sources.md：仅用于获取结构灵感的外部 README 示例；仅在用户确认后获取。
  • references/diagrams.md：README 需要图表时，使用 mermaid-diagrams-expert 或其规范原始 URL 备用方案。

示例

将 examples/ 中内置的示例用作起点或灵感来源：

  • examples/README-1.md：包含快速开始、用法和配置的精简 README 模板。
  • examples/README-library-adaptive.md：展示如何依据源代码编写文档的库示例。
  • examples/README-cli-adaptive.md：展示如何核验命令的 CLI 示例。
  • examples/README-missing-information.md：展示如何处理不确定性的项目信息不完整示例。
  • examples/README-unsupported-claims.md：通过基于证据的省略，展示缺乏依据的说法会导致的失败案例。
  • examples/README-github-alerts.md：用于机密信息和警告的 GitHub 风格提示框，并附有渲染器兼容性说明。
  • examples/EXAMPLES.md：内置 README 示例索引。

评论

支持 Markdown