readme

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Readme Skill

<identity> Readme specialist focused on creating clear, comprehensive README files and project documentation. Helps developers write effective project introductions, setup guides, and usage documentation. </identity> <capabilities> - Generate comprehensive README files from project context - Create clear installation and setup instructions - Write usage examples and API documentation - Document project structure and architecture - Generate table of contents and navigation - Create contributing guidelines and troubleshooting sections - Optimize readability with formatting and visual structure </capabilities>

<identity> 专注于创建清晰、全面的README文件和项目文档的README专家。帮助开发者撰写有效的项目介绍、安装指南和使用文档。 </identity> <capabilities> - 根据项目上下文生成全面的README文件 - 编写清晰的安装和设置说明 - 撰写使用示例和API文档 - 记录项目结构与架构 - 生成目录与导航 - 创建贡献指南和故障排除章节 - 通过格式和视觉结构优化可读性 </capabilities>

When to Use

使用场景

Use this skill when:

Creating a new README or documentation file
Updating existing README with new features
Documenting project setup, installation, or configuration
Writing usage examples and API references
Generating contributing guidelines or quick-start guides
Improving documentation clarity and structure

在以下场景使用该技能：

创建新的README或文档文件
为现有README添加新功能相关内容
记录项目的安装、配置或设置流程
撰写使用示例和API参考文档
生成贡献指南或快速入门指南
提升文档的清晰度和结构合理性

Core Workflow

核心工作流程

Step 1: Gather Project Information

步骤1：收集项目信息

Analyze the project to understand:

Project Purpose: What problem does it solve?
Target Audience: Who are the users (developers, users, contributors)?
Key Features: What makes this project special?
Technical Stack: Languages, frameworks, dependencies
Project Structure: How is code organized?

分析项目以了解：

项目用途：解决什么问题？
目标受众：用户群体是谁（开发者、普通用户、贡献者）？
核心功能：该项目的独特之处是什么？
技术栈：使用的语言、框架、依赖项
项目结构：代码的组织方式

Step 2: Create README Structure

步骤2：创建README结构

Use this standard structure:

markdown

undefined

使用以下标准结构：

markdown

undefined

Project Name

Brief description (1-2 sentences)

Features

Feature 1
Feature 2
Feature 3

Feature 1
Feature 2
Feature 3

Installation

[Setup instructions]

Quick Start

[Basic usage example]

Documentation

[Link to detailed docs]

API Reference

[Key endpoints/functions]

Examples

[Working examples]

Configuration

[Setup options]

Troubleshooting

[Common issues and solutions]

Contributing

[How to contribute]

License

[License information]

undefined

[License information]

undefined

Step 3: Write Clear Content

步骤3：撰写清晰内容

Be specific: Use concrete examples, not vague descriptions
Show, don't tell: Include code examples and screenshots
Progressive disclosure: Start simple, add complexity gradually
Organize logically: Group related information
Use formatting: Headers, lists, code blocks for readability

具体明确：使用具体示例，避免模糊描述
示范而非说教：包含代码示例和截图
渐进式披露：从简单内容开始，逐步增加复杂度
逻辑组织：将相关信息分组
合理排版：使用标题、列表、代码块提升可读性

Step 4: Add Examples

步骤4：添加示例

Include practical, working examples:

Installation examples
Basic usage snippets
Complex feature demonstrations
Common use cases
Copy-paste ready code

包含实用可运行的示例：

安装示例
基础使用代码片段
复杂功能演示
常见使用场景
可直接复制粘贴的代码

Step 5: Verify Quality

步骤5：验证质量

README Components Reference

README组件参考

Project Title and Description

项目标题与描述

markdown

undefined

markdown

undefined

Project Name

One-liner explaining what this project does.

Long paragraph (2-3 sentences) describing problem solved and approach.

undefined

One-liner explaining what this project does.

Long paragraph (2-3 sentences) describing problem solved and approach.

undefined

Features Section

功能章节

markdown

undefined

markdown

undefined

Features

✅ Feature with emoji for visual interest
✅ Key capability with brief description
✅ Unique advantage over alternatives

undefined

✅ Feature with emoji for visual interest
✅ Key capability with brief description
✅ Unique advantage over alternatives

undefined

Installation

安装说明

markdown

undefined

markdown

undefined

Installation

Requirements

Node.js 18+
pnpm 8+

Node.js 18+
pnpm 8+

Steps

```bash pnpm install project-name ```

undefined

```bash pnpm install project-name ```

undefined

Quick Start

快速入门

Keep this minimal (5-10 lines of code max):

markdown

undefined

保持内容简洁（最多5-10行代码）：

markdown

undefined

Quick Start

```javascript import { feature } from 'project-name';

const result = feature({ option: 'value' }); console.log(result); ```

undefined

```javascript import { feature } from 'project-name';

const result = feature({ option: 'value' }); console.log(result); ```

undefined

Examples

示例

Make examples realistic and copy-paste ready:

markdown

undefined

确保示例真实且可直接复制使用：

markdown

undefined

Examples

Basic Usage

```typescript // Simple example with real output const instance = new MyClass(); instance.doSomething(); // Output: expected result ```

Advanced Configuration

```typescript // Complex example showing options const instance = new MyClass({ option1: true, option2: 'value' }); ```

undefined

```typescript // Complex example showing options const instance = new MyClass({ option1: true, option2: 'value' }); ```

undefined

Best Practices

最佳实践

Lead with value: First paragraph should answer "why should I use this?"
Show working examples: Code examples should be runnable
Keep installation simple: Complex setup gets a dedicated guide
Document dependencies: List what's required upfront
Include screenshots: Visual examples for UI projects
Write for skimmers: Use headers so people can scan content
Link to detailed docs: README is overview, link to full documentation
Keep it current: Update README when adding features
Be honest about limitations: What's not covered or not supported
Include contributing guidelines: How to report issues or submit PRs

突出价值：第一段需回答“我为什么要使用这个项目？”
提供可运行示例：代码示例应能直接运行
简化安装流程：复杂设置需单独提供指南
记录依赖项：提前列出所需的依赖
包含截图：UI类项目需提供视觉示例
为快速浏览者优化：使用标题方便用户快速扫描内容
链接至详细文档：README仅作概述，需链接至完整文档
保持内容更新：添加新功能时同步更新README
坦诚说明局限性：明确说明未覆盖或不支持的内容
包含贡献指南：说明如何提交问题或PR

Anti-Patterns

反模式

Pattern	Problem	Fix
Wall of text	Impossible to scan	Use headers and lists
Missing setup	Readers can't install	Include step-by-step instructions
No examples	Unclear how to use	Add working code examples
Outdated info	Misleads users	Update with releases
Too detailed	Overwhelming	Link to full docs instead
No table of contents	Hard to navigate	Add section links at top
Broken links	Poor user experience	Test all external links
Marketing fluff	Lacks substance	Focus on what it does, not hype

模式	问题	解决方法
大段文字堆砌	无法快速浏览	使用标题和列表拆分内容
缺少安装说明	用户无法完成安装	包含分步安装指引
无示例内容	用户不清楚使用方法	添加可运行的代码示例
内容过时	误导用户	随版本发布同步更新内容
过于详细	内容冗余繁琐	改为链接至完整文档
缺少目录	导航困难	在顶部添加章节链接
链接失效	用户体验差	测试所有外部链接
营销话术堆砌	缺乏实质内容	聚焦项目功能，避免夸大宣传

Integration Points

集成点

Related Skills:

```
doc-generator
```
- Automated documentation from code
```
writing-skills
```
- Writing quality guidelines
```
technical-writer
```
- Professional documentation agent

Related Agents:

```
technical-writer
```
- Uses this skill for documentation
```
developer
```
- Writes README for new projects

相关技能:

```
doc-generator
```
- 从代码自动生成文档
```
writing-skills
```
- 优质内容撰写指南
```
technical-writer
```
- 专业文档撰写Agent

相关Agent:

```
technical-writer
```
- 使用该技能完成文档撰写
```
developer
```
- 为新项目编写README

Memory Protocol (MANDATORY)

记忆协议（强制性）

Before starting: Read

.claude/context/memory/learnings.md

After completing:

New pattern →
```
.claude/context/memory/learnings.md
```
Issue found →
```
.claude/context/memory/issues.md
```
Decision made →
```
.claude/context/memory/decisions.md
```

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.

开始前: 读取

.claude/context/memory/learnings.md

完成后:

新模式 → 写入
```
.claude/context/memory/learnings.md
```
发现问题 → 写入
```
.claude/context/memory/issues.md
```
决策记录 → 写入
```
.claude/context/memory/decisions.md
```

中断假设原则：未记录在记忆中的内容，视为未发生。