关于 readme-standards
为项目 README 提供模板与撰写规范，面向需要创建或改进项目文档的开发者。内容按项目类型和详略程度组织，并包含结构、徽章、技术栈与合规清单。
主要功能
- 01提供精简、标准和详细模板
- 02按项目类型提供模板
- 03说明徽章与 Logo 规范
- 04列出 README 合规检查项
适用场景
- 01为新项目选择 README 结构
- 02检查现有 README 是否完整
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/readme-standards确认已加载。
详细介绍
README 标准（v2025.1）
此技能为项目提供 README.md 模板和标准。
概述
结构良好的 README 是项目的门面。它应该：
- 立即说明项目的用途
- 通过恰当的品牌设计展现专业形象
- 提供清晰的入门说明
- 通过良好的视觉层次便于快速浏览
模板样式
极简样式
适用于：库、小型实用工具、内部工具
# project-name
[](LICENSE)
Brief description of what this project does.
## Installation
```bash
npm install package-name
用法
import { feature } from 'package-name';
feature();
许可证
MIT
### Standard Style (Recommended)
Best for: Most projects, applications, services
```markdown
<div align="center">
<img src="assets/logo.png" alt="Project Logo" width="128">
# Project Name
**A compelling tagline that explains the project's purpose**
[](LICENSE)
[](https://github.com/OWNER/REPO/stargazers)
[](https://github.com/OWNER/REPO/actions)
[]()
</div>
## Features
- **Feature One** - Description of the first key capability
- **Feature Two** - Description of the second key capability
- **Feature Three** - Description of the third key capability
- **Feature Four** - Description of the fourth key capability
## Tech Stack
| Category | Technology |
|----------|------------|
| Runtime | Bun 1.x |
| Framework | Fastify |
| Frontend | React 18, Vite |
| Database | SQLite (Drizzle ORM) |
| Testing | Vitest, Playwright |
## Getting Started
### Prerequisites
- [Bun](https://bun.sh) >= 1.0
- [Node.js](https://nodejs.org) >= 20 (optional)
### Installation
```bash
# Clone the repository
git clone https://github.com/OWNER/REPO.git
cd REPO
# Install dependencies
bun install
# Start development server
bun run dev
开发命令
bun run dev # Start development server
bun run build # Build for production
bun run test # Run tests
bun run lint # Run linter
项目结构
project-name/
├── src/
│ ├── client/ # Frontend React application
│ │ ├── components/ # UI components
│ │ └── stores/ # State management
│ ├── server/ # Backend Fastify server
│ │ ├── routes/ # API endpoints
│ │ └── services/ # Business logic
│ └── shared/ # Shared types and utilities
├── tests/ # Test files
├── docs/ # Documentation
└── README.md
贡献
欢迎贡献！请随时提交 Pull Request。
许可证
本项目采用 MIT License 许可。
### Detailed Style
Best for: Open source projects, documentation-heavy projects, developer tools
Includes everything from Standard plus:
- Architecture diagrams (Mermaid)
- API reference section
- Detailed configuration options
- Changelog link
- Security policy
- Code of conduct reference
## Badge Reference
### Repository Status Badges
```markdown
[](LICENSE)
[](https://github.com/OWNER/REPO/stargazers)
[](https://github.com/OWNER/REPO/network/members)
[](https://github.com/OWNER/REPO/issues)
[](https://github.com/OWNER/REPO/commits)
CI/CD 状态徽章
[](https://github.com/OWNER/REPO/actions)
[](https://github.com/OWNER/REPO/actions/workflows/build.yml)
[](https://codecov.io/gh/OWNER/REPO)
包注册表徽章
[](https://www.npmjs.com/package/PACKAGE)
[](https://www.npmjs.com/package/PACKAGE)
[](https://pypi.org/project/PACKAGE/)
[](https://pypi.org/project/PACKAGE/)
[](https://crates.io/crates/PACKAGE)
[](https://docs.rs/PACKAGE)
[](https://pkg.go.dev/github.com/OWNER/REPO)
技术徽章
[]()
[]()
[]()
[]()
[]()
[]()
[]()
[]()
[]()
[]()
[]()
Logo 指南
推荐规格
- 格式：PNG（支持透明背景）或 SVG
- 尺寸：128x128px 至 512x512px
- 位置：
assets/logo.png或assets/icon.svg
Logo 居中
<div align="center">
<img src="assets/logo.png" alt="Project Name" width="128">
</div>
使用 Emoji 作为占位符
如果没有 Logo：
<div align="center">
# 🚀 Project Name
</div>
常见项目类型 Emoji：
- 🚀 - 通用工具/部署工具
- 🛠️ - 开发者工具
- 📊 - 数据/分析
- 🔒 - 安全
- 🌐 - Web 应用
- 📱 - 移动应用
- 🤖 - AI/ML 项目
- 📦 - 包/库
章节指南
功能章节
以优势而非单纯的能力来描述功能：
较好：
- **Automatic Scanner Detection** - Discovers eSCL-compatible scanners via mDNS without manual configuration
- **Smart Photo Separation** - Intelligently detects and crops multiple photos from a single scan using edge analysis
对比 — 侧重实现（效果较差）：
- Uses mDNS for scanner discovery
- Has edge detection algorithm
技术栈章节
使用表格以便清晰呈现：
| Category | Technology |
|----------|------------|
| Runtime | Bun 1.x |
| Server | Fastify 4 |
| Frontend | React 18, Tailwind CSS |
| Database | SQLite (Drizzle ORM) |
快速开始章节
始终包含：
- 带版本要求的前置条件
- 克隆说明
- 安装依赖的命令
- 运行命令
- （可选）环境设置
项目结构章节
- 深度保持在 2-3 层
- 只展示有意义的目录
- 为不易理解的文件夹添加简短说明
project/
├── src/ # Source code
├── tests/ # Test files
├── docs/ # Documentation
└── scripts/ # Build/dev scripts
特定项目类型的模板
CLI 工具
## Installation
```bash
# With npm
npm install -g tool-name
# With Bun
bun install -g tool-name
# Or run directly
npx tool-name
用法
tool-name <command> [options]
Commands:
init Initialize a new project
build Build the project
deploy Deploy to production
Options:
-h, --help Show help
-v, --version Show version
### Library/Package
```markdown
## Installation
```bash
npm install package-name
# or
bun add package-name
用法
import { feature } from 'package-name';
const result = feature({
option: 'value'
});
API
feature(options)
函数说明。
参数：
options.key（string）- 说明
返回值： ReturnType - 说明
### Web Application
```markdown
## Demo
🌐 [Live Demo](https://demo.example.com)
## Screenshots
<div align="center">
<img src="docs/screenshots/dashboard.png" alt="Dashboard" width="600">
</div>
## Environment Variables
Create a `.env` file:
```env
DATABASE_URL=postgresql://...
API_KEY=your-api-key
## Compliance Checklist
### Minimal Style
- [ ] Title (h1)
- [ ] Description (1-2 sentences)
- [ ] License badge
- [ ] Installation instructions
- [ ] Basic usage example
- [ ] License section
### Standard Style (all of minimal plus)
- [ ] Logo or emoji header
- [ ] 3+ badges (license, stars, CI)
- [ ] Features section (4+ items)
- [ ] Tech stack table
- [ ] Prerequisites
- [ ] Development commands
- [ ] Project structure
- [ ] Contributing mention
### Detailed Style (all of standard plus)
- [ ] Architecture diagram
- [ ] API reference or link
- [ ] Configuration options
- [ ] Changelog link
- [ ] Security policy mention
- [ ] Code of conduct mention
## Cookiecutter Integration
For creating entire new projects from templates, consider using [cookiecutter](https://cookiecutter.readthedocs.io/):
```bash
# Install cookiecutter
pip install cookiecutter
# or
uv tool install cookiecutter
# Create project from template
cookiecutter https://github.com/your-org/project-template
Cookiecutter 适用于：
- 创建多个结构一致的项目
- 组织范围内的项目模板
- 不仅包含 README，还包含整个项目脚手架
/configure:readme 命令更适用于：
- 更新现有项目
- 为已有代码的项目生成 README
- 检查现有 README 是否符合规范
评论
支持 Markdown