readme

Readme 技能

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

适用场景

在以下情况下使用此技能：

• 创建新的 README 或文档文件
• 更新现有 README 以介绍新功能
• 记录项目设置、安装或配置
• 编写使用示例和 API 参考
• 生成贡献指南或快速入门指南
• 改善文档的清晰度和结构

核心工作流

第 1 步：收集项目信息

分析项目以了解：

1. 项目目的：它解决了什么问题？
2. 目标受众：用户是谁（开发者、用户、贡献者）？
3. 主要功能：这个项目有什么特别之处？
4. 技术栈：语言、框架、依赖项
5. 项目结构：代码是如何组织的？

第 2 步：创建 README 结构

使用以下标准结构：

# Project Name

Brief description (1-2 sentences)

## Features

- 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]

第 3 步：编写清晰的内容

• 具体明确：使用具体示例，而非含糊的描述
• 展示而非空谈：加入代码示例和屏幕截图
• 循序渐进：从简单内容开始，逐步增加复杂度
• 合理组织：将相关信息归在一起
• 使用格式：通过标题、列表和代码块提高可读性

第 4 步：添加示例

加入实用、可运行的示例：

• 安装示例
• 基本用法片段
• 复杂功能演示
• 常见用例
• 可直接复制粘贴的代码

第 5 步：检查质量

完成前请检查：

• 在第一段中清楚说明项目目的
• 安装说明完整
• 示例可以运行
• 目录与各章节对应
• 所有链接均可正常使用
• 格式一致
• 没有拼写或语法错误

README 组件参考

项目标题和描述

# Project Name

One-liner explaining what this project does.

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

功能章节

## Features

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

安装

## Installation

### Requirements

- Node.js 18+
- pnpm 8+

### Steps

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

快速入门

尽量简短（最多 5-10 行代码）：

## Quick Start

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

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

示例

示例应贴近实际，并可直接复制粘贴：

## 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'
});
\`\`\`

最佳实践

1. 突出价值：第一段应回答“我为什么要使用这个项目？”
2. 展示可运行的示例：代码示例应能够运行
3. 简化安装流程：复杂的设置应单独编写指南
4. 记录依赖项：提前列出所需内容
5. 加入屏幕截图：为 UI 项目提供视觉示例
6. 方便快速浏览：使用标题，方便读者快速浏览内容
7. 链接到详细文档：README 是概览，应链接到完整文档
8. 保持内容更新：添加功能时更新 README
9. 如实说明限制：说明未涵盖或不支持的内容
10. 加入贡献指南：说明如何报告问题或提交 PR

反模式

模式	问题	修正方法
大段文字	难以快速浏览	使用标题和列表
缺少设置说明	读者无法安装	提供分步说明
没有示例	不清楚如何使用	添加可运行的代码示例
信息过时	误导用户	随版本发布更新
过于详细	让人不堪重负	改为链接到完整文档
没有目录	难以导航	在顶部添加章节链接
链接失效	用户体验差	测试所有外部链接
营销套话	缺乏实质内容	聚焦于它的功能，而非夸大宣传

铁律

1. 始终先说明价值主张——第一段必须先回答“它解决了什么问题？”，然后再提供任何安装或设置说明。
2. 绝不将 Quick Start 部分写得超过 10 行——如果设置需要更多内容，请链接到详细指南，不要让初次阅读的读者不堪重负。
3. 始终提供可运行、可直接复制粘贴的代码示例——不可运行的伪代码示例比没有示例更糟糕，因为它们会浪费读者的时间。
4. 绝不让 README 在功能发布后过时——过时的安装命令和失效的示例会立即摧毁用户信任。
5. 始终在确认 README 完成前测试所有外部链接和代码示例——失效链接和不可运行的示例是 README 最常见的问题。

反模式

反模式	失败原因	正确做法
在描述之前先罗列一长串功能	读者不知道项目是什么，因此这些功能毫无意义	先用 1-2 句话说明价值主张，再列出功能
使用伪代码或占位示例	迫使读者推断真实 API；导致挫败感，最终放弃使用	展示带有真实导入、函数名和预期输出的可运行代码
在 Quick Start 中加入 20 步安装指南	复杂的设置过程会赶走用户；也与“快速”入门相矛盾	Quick Start 必须只包含 1-3 条命令；将详细设置链接到单独的指南
写营销文案而非技术事实	“快如闪电”等模糊说法没有提供可操作的信息	使用带数据的具体说法：“构建时间缩短 40%（在 10k LOC 上测得）”
功能变化时不更新 README	过时命令会悄无声息地失效；用户会责怪项目，而非文档	将 README 视为代码：每次功能变更都在同一个 PR 中更新

集成点

相关技能：

• doc-generator - 根据代码自动生成文档
• writing-skills - 写作质量指南
• technical-writer - 专业文档 Agent

相关 Agent：

• technical-writer - 使用此技能编写文档
• developer - 为新项目编写 README

记忆协议（强制）

开始之前： 阅读 .claude/context/memory/learnings.md

完成之后：

• 新模式 → .claude/context/memory/learnings.md
• 发现问题 → .claude/context/memory/issues.md
• 做出决定 → .claude/context/memory/decisions.md

假设会中断：如果内容不在记忆中，就等于没发生。