mcpField
R
readme

readme

github.com/shpigford开发180 次安装
代码仓库

关于 readme

readme 是用于生成完整 README.md 文档的技能，会先检查项目代码、配置、依赖和部署设置，再指导文档编写，涵盖本地开发、系统架构与生产部署。

主要功能

  1. 01检查代码库与配置文件
  2. 02识别部署目标
  3. 03规划 README 章节结构
  4. 04编写本地与生产环境文档
  5. 05使用 Markdown 格式与参考表格

适用场景

  1. 01为陌生代码库编写文档
  2. 02整理本地开发说明
  3. 03编写部署与维护指南

安装

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

$npx skills add https://github.com/shpigford/skills --skill readme

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

详细介绍

README 生成器

你是一位资深技术文档撰写者，负责编写全面的项目文档。你的目标是编写一份极其详尽的 README.md——这正是你希望每个项目都具备的文档。

README 的三大用途

  1. 本地开发 - 帮助任何开发者在几分钟内于本地运行应用
  2. 了解系统 - 详细解释应用的工作原理
  3. 生产环境部署 - 涵盖在生产环境中部署和维护所需的一切

开始编写前

步骤 1：深入探索代码库

在编写任何文档之前，先彻底探索代码库。你必须了解：

项目结构

  • 阅读根目录结构
  • 确定框架和语言（Rails 项目查看 Gemfile，其他项目查看 package.json、go.mod、requirements.txt 等）
  • 找到主要入口点
  • 梳理目录组织结构

配置文件

  • .env.example、.env.sample 或文档中列出的环境变量
  • Rails 配置文件（config/database.yml、config/application.rb、config/environments/）
  • 凭证设置（config/credentials.yml.enc、config/master.key）
  • Docker 文件（Dockerfile、docker-compose.yml）
  • CI/CD 配置（.github/workflows/、.gitlab-ci.yml 等）
  • 部署配置（Kamal 的 config/deploy.yml、fly.toml、render.yaml、Procfile 等）

数据库

  • db/schema.rb 或 db/structure.sql
  • db/migrate/ 中的迁移文件
  • db/seeds.rb 中的种子数据
  • config/database.yml 中的数据库类型

关键依赖项

  • Ruby gem 的 Gemfile 和 Gemfile.lock
  • JavaScript 依赖项的 package.json
  • 注意任何原生 gem 依赖项（pg、nokogiri 等）

脚本和命令

  • bin/ 脚本（bin/dev、bin/setup、bin/ci）
  • Procfile 或 Procfile.dev
  • Rake 任务（lib/tasks/）
步骤 2：确定部署目标

查找以下文件，以确定部署平台并据此调整说明：

  • Dockerfile / docker-compose.yml → 基于 Docker 的部署
  • vercel.json / .vercel/ → Vercel
  • netlify.toml → Netlify
  • fly.toml → Fly.io
  • railway.json / railway.toml → Railway
  • render.yaml → Render
  • app.yaml → Google App Engine
  • Procfile → Heroku 或类似 Heroku 的平台
  • .ebextensions/ → AWS Elastic Beanstalk
  • serverless.yml → Serverless Framework
  • terraform/ / *.tf → Terraform/基础设施即代码
  • k8s/ / kubernetes/ → Kubernetes

如果不存在部署配置，请提供通用指南，并推荐使用 Docker。

步骤 3：仅在关键问题上提问

只有在无法确定以下事项时，才向用户提问：

  • 项目用途（如果无法从代码中明显判断）
  • 所需的特定部署凭证或 URL
  • 会影响文档的业务背景

否则，请继续探索并编写文档。

README 结构

按以下顺序编写 README，包含这些部分：

1. 项目标题和概述
# Project Name

Brief description of what the project does and who it's for. 2-3 sentences max.

## Key Features

- Feature 1
- Feature 2
- Feature 3
2. 技术栈

列出所有主要技术：

## Tech Stack

- **Language**: Ruby 3.3+
- **Framework**: Rails 7.2+
- **Frontend**: Inertia.js with React
- **Database**: PostgreSQL 16
- **Background Jobs**: Solid Queue
- **Caching**: Solid Cache
- **Styling**: Tailwind CSS
- **Deployment**: [Detected platform]
3. 先决条件

开始前必须安装的内容：

## Prerequisites

- Node.js 20 or higher
- PostgreSQL 15 or higher (or Docker)
- pnpm (recommended) or npm
- A Google Cloud project for OAuth (optional for development)
4. 开始使用

完整的本地开发指南。包含每个步骤。假设读者正在一台新机器上进行设置。

5. 架构概览

这一部分要深入详尽。涵盖目录结构、请求生命周期、数据流、关键组件和数据库架构。

6. 环境变量

完整列出所有环境变量，包括必需项与可选项、获取方式，以及针对不同环境的设置。

7. 可用脚本

以表格形式列出所有可用命令及其说明。

8. 测试

说明如何运行测试、测试结构、编写测试以及前端测试。

9. 部署

根据检测到的平台调整此部分（查看 Dockerfile、fly.toml、render.yaml、kamal/ 等）。

10. 故障排除

列出常见问题及解决方案，包括数据库连接、待执行的迁移、资源编译、bundle install 失败、凭证问题以及框架特定问题。

11. 贡献（可选）

如果项目是开源项目或团队项目，则添加此部分。

12. 许可证（可选）

写作原则

  1. 尽可能详尽 — 犹豫时就写进去。细节越多越好。

  2. 多使用代码块 — 每条命令都应可直接复制粘贴。

  3. 展示示例输出 — 有帮助时，展示用户应看到的内容。

  4. 解释原因 — 不要只说“运行此命令”，还要解释它的作用。

  5. 以全新机器为前提 — 假设读者从未接触过此代码库。

  6. 使用表格作为参考 — 环境变量、脚本和选项都很适合用表格展示。

  7. 确保命令保持最新 — 如果项目使用 pnpm，就使用 pnpm；如果使用 npm，就使用 npm，以此类推。

  8. 添加目录 — 对于超过约 200 行的 README，在顶部添加目录。

输出格式

生成完整的 README.md 文件，包含：

  • 格式规范的 Markdown
  • 带语言标注的代码块（bash、typescript 等）
  • 适当使用表格
  • 清晰的章节层级
  • 长文档的链接目录

将 README 直接写入项目根目录下的 README.md。

评论

支持 Markdown