accelint-readme-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

README Writer

README 撰写器

This skill guides the creation and maintenance of comprehensive, human-friendly README documentation by analyzing the codebase and ensuring documentation stays in sync with actual functionality.

该技能通过分析代码库并确保文档与实际功能保持同步，指导创建和维护详尽、符合人类阅读习惯的README文档。

When to Activate This Skill

何时启用该技能

Use this skill when:

Creating a new README.md for a project or package
Updating an existing README.md after code changes
Auditing documentation for completeness and accuracy
Converting sparse documentation into thorough guides
User asks to "document this package" or "write a README"
User mentions README in context of a monorepo subdirectory

在以下场景使用该技能：

为项目或包创建新的README.md
代码变更后更新现有的README.md
审核文档的完整性和准确性
将简略文档转换为详尽指南
用户要求“为这个包生成文档”或“撰写README”
用户在单体仓库子目录的语境中提及README

When NOT to Use This Skill

何时不启用该技能

Do not activate for:

API documentation generation (use JSDoc/TSDoc tools)
Changelog or release notes
Internal developer notes not meant for README
Documentation in formats other than Markdown

请勿在以下场景启用：

API文档生成（使用JSDoc/TSDoc工具）
变更日志或发布说明
不适合放入README的内部开发者笔记
Markdown以外格式的文档

How to Use

使用方法

Step 1: Locate the README Context

步骤1：确定README的上下文位置

Identify where the README should live. In monorepos, this determines the scope of codebase analysis:

project-root/           # README here documents entire monorepo
├── packages/
│   └── my-lib/         # README here documents only my-lib
│       └── README.md
└── README.md

确定README应存放的位置。在单体仓库中，这将决定代码库分析的范围：

project-root/           # 此处的README记录整个单体仓库
├── packages/
│   └── my-lib/         # 此处的README仅记录my-lib
│       └── README.md
└── README.md

Step 2: Analyze the Codebase

步骤2：分析代码库

Recursively parse code starting from the README's directory:

Identify entry points: Look for
```
index.ts
```
,
```
main.ts
```
, package.json
```
main
```
/
```
exports
```
Map public API: Find all exported functions, classes, types, constants
Trace dependencies: Understand what the package depends on
Find examples: Look for
```
examples/
```
, test files, or inline usage comments
Check package.json: Extract scripts, dependencies, peer dependencies

从README所在目录开始递归解析代码：

识别入口文件：查找
```
index.ts
```
、
```
main.ts
```
、package.json中的
```
main
```
/
```
exports
```
字段
梳理公开API：找出所有导出的函数、类、类型、常量
追踪依赖关系：了解该包依赖的内容
查找示例：寻找
```
examples/
```
目录、测试文件或内联使用注释
检查package.json：提取脚本、依赖项、对等依赖项

Step 3: Compare Against Existing README

步骤3：与现有README对比

If a README exists, identify gaps:

Missing exports: Public API not documented
Stale examples: Code samples using deprecated patterns
Missing sections: No installation, no quick start, no API reference
Outdated commands: Wrong package manager, missing scripts

如果已有README，找出其中的差距：

缺失的导出内容：未记录的公开API
过时的示例：使用已弃用模式的代码示例
缺失的章节：没有安装说明、快速开始、API参考
过时的命令：错误的包管理器、缺失的脚本

Step 4: Generate or Update README

步骤4：生成或更新README

Follow the README Structure and apply Writing Principles.

Use the README Template as a starting point for new READMEs.

遵循README结构并应用撰写原则。

对于新的README，可使用README模板作为起点。

README Workflow Decision Tree

README 工作流决策树

Start
  ↓
Does README.md exist?
  ├─ No → Analyze codebase → Generate from template
  └─ Yes → Analyze codebase → Compare with existing
             ↓
         Identify gaps and staleness
             ↓
         Suggest specific changes
             ↓
         Apply updates (with user confirmation)

开始
  ↓
是否存在README.md？
  ├─ 否 → 分析代码库 → 基于模板生成
  └─ 是 → 分析代码库 → 与现有内容对比
             ↓
         找出差距和过时内容
             ↓
         提出具体修改建议
             ↓
         应用更新（需用户确认）

Key References

关键参考资料

Load these as needed for detailed guidance:

references/readme-structure.md - Section ordering and content requirements
references/writing-principles.md - How to write human-sounding, thorough docs
references/codebase-analysis.md - How to parse and understand code for documentation
references/readme-template.md - Copy-pasteable template for new READMEs

可按需加载以下资料获取详细指导：

references/readme-structure.md - 章节顺序和内容要求
references/writing-principles.md - 如何撰写符合人类阅读习惯的详尽文档
references/codebase-analysis.md - 如何解析和理解代码以用于文档撰写
references/readme-template.md - 可复制粘贴的新README模板

Example Trigger Phrases

示例触发语句

"Create a README for this package"
"Update the README to reflect recent changes"
"The README is out of date, can you fix it?"
"Document this library"
"Write docs for packages/my-lib"
"This package needs better documentation"

"为这个包创建README"
"更新README以反映最近的变更"
"README已经过时了，能修复吗？"
"为这个库生成文档"
"为packages/my-lib撰写文档"
"这个包需要更好的文档"

Required Skills

所需技能

This skill requires the

humanizer

skill for reviewing generated content.

humanizer

is not available:

Check Settings > Capabilities to enable it
Or invoke it with
```
/skill humanizer
```

The humanizer skill removes AI writing patterns and ensures documentation sounds natural. Without it, generated READMEs may contain robotic language, inflated significance claims, and other AI artifacts.

该技能需要

humanizer

技能来审核生成的内容。

如果

humanizer

不可用：

前往设置>功能页面启用它
或通过
```
/skill humanizer
```
调用它

humanizer技能可移除AI写作模式，确保文档听起来自然。如果没有它，生成的README可能会包含机器人式语言、夸大的重要性表述以及其他AI生成痕迹。

Important Notes

重要注意事项

Package Manager Detection

包管理器检测

Always use the correct package manager based on lockfiles:

Lockfile	Package Manager	Install Command
`pnpm-lock.yaml`	pnpm	`pnpm install`
`package-lock.json`	npm	`npm install`
`yarn.lock`	yarn	`yarn`
`bun.lockb`	bun	`bun install`

始终根据锁文件使用正确的包管理器：

锁文件	包管理器	安装命令
`pnpm-lock.yaml`	pnpm	`pnpm install`
`package-lock.json`	npm	`npm install`
`yarn.lock`	yarn	`yarn`
`bun.lockb`	bun	`bun install`

Human-Sounding Writing

符合人类阅读习惯的写作

REQUIRED SUB-SKILL: Use

humanizer

to review and refine generated README content.

Documentation should sound like it was written by someone who genuinely wants to help. The humanizer skill identifies and removes AI writing patterns including:

Inflated significance language ("pivotal", "testament", "crucial")
Promotional/advertisement-like tone
Superficial -ing analyses
Vague attributions and weasel words
Em dash overuse and rule-of-three patterns

After generating README content, apply the humanizer skill to ensure the output sounds natural and human-written. See references/writing-principles.md for additional guidance specific to technical documentation.

必备子技能： 使用

humanizer

审核和优化生成的README内容。

文档应听起来像是由真心想要提供帮助的人撰写的。humanizer技能可识别并移除以下AI写作模式：

夸大重要性的语言（如“关键的”、“至关重要的”、“核心的”）
推广/广告式语气
表面化的-ing形式分析
模糊的归因和含糊其辞的表述
破折号过度使用和三段式结构

生成README内容后，应用humanizer技能以确保输出自然、符合人类撰写风格。有关技术文档的额外指导，请参阅references/writing-principles.md。