mcpField
G
generate-standard-readme

generate-standard-readme

github.com/nesnilnehcDevelopment867 installsUpdated 1d ago
Repository

About generate-standard-readme

A skill for creating concise, information-dense READMEs for software projects and documentation repositories. It adapts sections to the project type and grounds claims in concrete paths, commands, behavior, or constraints.

Key features

  1. 01Structure content by project type
  2. 02Keep sections that meet a value threshold
  3. 03Emphasize entry points and minimal usage
  4. 04Avoid vague claims and invented details
  5. 05Check links and section completeness

Use cases

  1. 01Write a README for a new repository
  2. 02Standardize landing pages across services
  3. 03Document core entry points in a legacy project
  4. 04Check a README before handoff or release

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/nesnilnehc/ai-cortex --skill generate-standard-readme

After installing, type/generate-standard-readmein Claude Code to confirm it loaded.

Bundled filesREADME.md

Details

From the project README

技能（Skill）：生成精简 README

目的

为任何软件项目或文档仓库生成高信息密度、低冗余的首页文档。

唯一核心目标：读者在 30 秒内知道——

  1. 这个项目是什么（一句话）
  2. 去哪里找关键入口
  3. 怎么用（可执行的最短路径）

适用范围

本技能负责：

  • 按价值门槛裁剪章节的精简 README 生成
  • 项目类型分流（代码/应用仓库 vs 文档/规范仓库）
  • anti-fluff 输出（每个主张落到具体路径、命令、行为或约束）

本技能不负责：

  • 完整 docs/ 套件 → 由 AgentFabric runtime 或人工按 docs/ARTIFACT_NORMS.md 承接
  • AGENTS.md / 代理合同文件 → 使用 generate-agent-entry
  • 敏感信息脱敏 → 使用 decontextualize-text

使用场景

  • 新建仓库：项目创建后需要首页文档，无现有 README。
  • 资产治理：跨服务统一 README 风格，提升可索引性。
  • 遗留系统：补全缺失文档，以最小信息量覆盖核心入口。
  • 移交与发布：项目转交或公开发布前确保首页文档完整。

触发信号：用户说"帮我写 README"、"生成自述文件"或直接提供仓库路径。

行为

交互策略
情况行为
项目类型已知直接生成，无需询问
项目类型不明先检查仓库结构（是否有 package.json / pyproject.toml / Dockerfile / INDEX.md 等）推断类型；推断有把握则直接生成并说明推断依据；推断不确定时询问用户
用户未提供描述从仓库名称和文件结构推断最保守描述，标注 TBD，不臆造
写文件前默认直接写入 README.md；若仓库已有 README，先提示将覆盖，等待确认
默认骨架
# <项目名> [徽章（可选）]

<一句话说明>（必须）

## <核心入口 / 如何使用>（必须）

## License（必须）

其余章节按价值门槛决定是否保留。

章节价值门槛

判定原则：若某章节不能提供其他章节中不存在的新决策信息，则删除或并入最近的章节。

章节类型保留条件
标题 + 一句话说明必须无条件保留
核心入口 / 如何使用必须无条件保留
License必须无条件保留，含有效链接
功能列表可选存在 ≥2 个非显而易见的功能且一句话说明无法覆盖时
安装可选（仅 code 类型）安装步骤超过 pip install / npm install 单行时
快速启动可选（仅 code 类型）存在可复制粘贴的最小可运行示例时
配置/使用说明可选有非显而易见的配置项或参数时
贡献指南可选贡献流程有特殊要求时（PR 规范、测试门槛等）
作者/致谢可选有明确归属需求时

省略规则：

  • doc 类型仓库：默认不生成安装和快速启动节，改为导航索引
  • 任何章节若内容为空或仅含 TBD → 省略（不保留空壳章节）
  • 贡献/作者章节若只能写通用套话 → 省略
项目类型分流

code 类型（代码/应用仓库）

判定信号：存在 package.json / pyproject.toml / Makefile / Dockerfile / 主程序入口文件。

输出重点：安装路径、最小可运行示例、关键 API 入口。

# MyApp

单行说明项目做什么。

## Installation

\```bash
npm install myapp
\```

## Usage

\```bash
myapp --input file.csv --output result.json
\```

## License

MIT — see [LICENSE](LICENSE)

doc 类型（文档/规范仓库）

判定信号：无可执行入口，主要内容为 .md / .yaml / .json spec 文件，存在 INDEX.md / skills/INDEX.md。

输出重点：导航索引、阅读路径。安装/快速启动默认省略。

# MySpec

单行说明规范/文档的范围和受众。

## 如何使用

- 从 [INDEX.md](INDEX.md) 开始
- 核心定义见 [docs/architecture/terminology.md](docs/architecture/terminology.md)
- 贡献规范见 [CONTRIBUTING.md](CONTRIBUTING.md)

## License

MIT — see [LICENSE](LICENSE)
Anti-Fluff 规则

以下内容禁止出现：

禁止模式示例修复方向
空泛形容词堆叠"可复用、可治理、可落地"删除或替换为具体行为："通过 skills/INDEX.md 注册并与变更一并自检"
无主语的价值主张"提高工程规范"删除或具体化："维护 skills/INDEX.md 与文档链接一致性"
重复已知信息在安装节重述描述节的内容合并或删除
占位套话"欢迎贡献！请提 PR。"若无具体流程说明，省略贡献节
臆造命令或功能无 docker-compose.yml 却写 docker compose up用 TBD 或省略

每个主张必须落到：具体文件路径 / shell 命令 / 可观测行为 / 明确约束。

输入与输出

输入
字段必需说明
项目名称必需用于标题
一句话描述必需精确说明项目做什么
项目类型推荐code 或 doc；不提供时从仓库结构推断
许可证推荐类型 + 文件路径；不提供时用 TBD
安装命令可选仅 code 类型项目使用
快速启动示例可选仅 code 类型项目使用
核心入口列表可选关键文件、目录、URL

未提供的字段：用 TBD 占位或直接省略该章节；禁止臆造。

输出
  • README.md 写入项目根目录
  • 章节数由价值门槛决定，最少 3 节（标题+说明、入口/使用、许可证）
  • 无损坏链接，内部路径优先

限制

  • 禁止臆造：所有命令、路径、功能必须来自输入或仓库实际内容；缺失时用 TBD 或省略
  • 禁止损坏链接：外部链接仅在高度稳定时使用（如 shields.io）；内部路径须可验证存在
  • 禁止空壳章节：每个保留章节至少含一条可执行信息；内容为空则省略
  • doc 类型硬限制：doc 类型仓库不生成安装/快速启动节，即使用户要求也应说明理由
  • 许可证不可省：始终包含 License 节；未提供时用 TBD 而非省略
  • 已有 README 须确认：若目标目录已有 README.md，覆盖前必须提示用户

自检

生成 README 后逐项核查：

  • 30 秒测试：陌生读者能否在 30 秒内读完一句话说明并找到使用入口？
  • 无空泛形容词：未出现"可复用"、"可治理"、"专业"等无具体行为支撑的形容词
  • 无臆造内容：所有命令、路径、功能均来自输入或仓库实际内容
  • 无损坏链接：内部路径已验证存在；外部链接仅在高度稳定时使用
  • 无空壳章节：每个保留章节至少含一条可执行信息
  • 许可证节存在：含许可证类型 + 有效链接（或 TBD）
  • 项目类型匹配：doc 类型无安装/快速启动节；code 类型的安装命令实际可执行
  • 价值门槛通过：每个保留章节能提供其他章节不含的新决策信息

验收标准：以上 8 项全部通过，或对每个未通过项有明确的豁免理由。

示例

示例 1：代码仓库（精简输出）

输入：名称 img-crush，描述"批量压缩图片"，安装 pip install img-crush，用法 img-crush ./images，许可证 MIT。

输出：

# img-crush

批量压缩图片，支持 WebP / PNG / JPEG 格式。

## Installation

\```bash
pip install img-crush
\```

## Usage

\```bash
img-crush ./images          # 原地压缩
img-crush ./images -o out/  # 输出到指定目录
\```

## License

MIT — see [LICENSE](LICENSE)
示例 2：文档/规范仓库（doc 类型）

输入：名称 ai-cortex，描述"agent-first 技能库"，许可证 MIT，核心入口 skills/INDEX.md、AGENTS.md。

输出：

# ai-cortex

面向软件交付和项目治理的 agent-first 技能库。

## 如何使用

- 从 [AGENTS.md](AGENTS.md) 了解代理行为契约
- 浏览 [skills/INDEX.md](skills/INDEX.md) 查找可用技能
- 核心术语定义见 [docs/architecture/terminology.md](docs/architecture/terminology.md)

## License

MIT — see [LICENSE](LICENSE)
示例 3：边缘案例——信息极少的遗留项目

输入：名称 legacy-auth，无描述，无功能列表，安装和环境未知。

处理：

  • 一句话说明：从名称推断最保守描述，标注 TBD
  • 安装节：省略（无可执行命令）
  • 功能节：省略（无内容）
  • 许可证：TBD（不省略，只是内容待补）

输出：

# legacy-auth

认证服务（详情待补充）。

## 如何使用

TBD — 请参阅项目内部文档。

## License

TBD
示例 4：失败案例——doc 类型仓库生成了安装节

症状：为文档规范仓库生成了 ## Installation 节，内容为 npm install 或空 TBD。

根因：未识别项目类型，套用了 code 模板。

修复：检查仓库结构 → 无可执行入口则判定为 doc 类型 → 删除安装/快速启动节，替换为导航索引。

Comments

Markdown supported