update-readme

Update README

Keep README.md (English, primary) and README.zh-CN.md (Simplified Chinese, secondary) in sync with the project's actual current state. Both files must be accurate, complete, and consistent with each other.

Header Format (Required)

Every README must open with this exact structure — adapt the badges, project name, and description to the project at hand:

# <Project Name> ![](https://img.shields.io/badge/<label>-<message>-<color>)

[![<Badge1 Label>](<badge-url>)](<link>) [![<Badge2 Label>](<badge-url>)](<link>)

**English** | [简体中文](README.zh-CN.md)

For README.zh-CN.md, reverse the language toggle:

# <Project Name> ![](https://img.shields.io/badge/<label>-<message>-<color>)

[![<Badge1 Label>](<badge-url>)](<link>) [![<Badge2 Label>](<badge-url>)](<link>)

[English](README.md) | **简体中文**

Choose badges that reflect what is genuinely true about the project. Common types: CI status, license, language/runtime version, package registry version, code coverage. Use shields.io static badges when there is no live endpoint. Prefer reference-style Markdown links for badge rows with more than two badges — it keeps the source readable. Broken or always-failing badges are worse than no badges; only include ones that are maintained.

Process

1. Survey the project

Before writing anything, read the actual project state:

• Scan all skill/module directories and their SKILL.md or equivalent descriptor files
• Note each component's name, one-line purpose, installation method, and any notable prerequisites
• Check git log for recent additions or removals
• Read the existing README files to understand what is already there and what has gone stale

Write from ground truth, not from memory or assumption.

2. Draft README.md (English)

Use references/template.md as the structural starting point. Adapt section names to the project's domain — the template shows the skeleton, not the words.

Section order (omit what doesn't apply, don't add sections just to fill space):

1. Header — title + badges + language toggle
2. One-liner description (one sentence)
3. Logo, banner, or demo GIF — optional, but place it early if the project has one
4. Main content sections (Available Items, Usage, etc.)
5. Contributing / Adding a new item
6. License

For READMEs over ~300 lines, add a Table of Contents after the one-liner.

The README is a directory, not a tutorial. Keep each component description to one or two sentences. Installation commands must be copy-pasteable — exact commands, no ambiguity. Always use fenced code blocks with a language tag (```bash, ```json).

Write with a human voice. README prose is some of the most AI-trope-prone writing that exists — it tends to accumulate "robust", bold-first bullet points, and "serves as" constructions without anyone noticing. Specific things to watch for:

• Word choice: avoid "leverage", "streamline", "robust", "utilize", "delve". Say the plain thing.
• Bullets: don't start every item with a bolded phrase. It reads as AI-generated documentation.
• Descriptions: say what the component does, not what it "serves as" or "stands as".
• Marketing tone: "powerful", "seamless", "comprehensive" add nothing. Cut them.
• Filler transitions: "It's worth noting", "Importantly", "Notably" — delete these.

A useful test: read each sentence aloud. If it sounds like promotional copy, rewrite it as a plain statement of fact.

3. Draft README.zh-CN.md (Chinese)

Translate the English README faithfully. Rules:

• Use natural Simplified Chinese — do not translate technical terms that are universally used in English (CLI tool names, package manager commands, GitHub URLs, code blocks).
• Keep all code blocks, commands, and file paths identical to the English version.
• Section headings should be idiomatic Chinese (e.g., "可用技能", "添加新技能"), not word-for-word translations.
• The language toggle must be [English](README.md) | **简体中文**.
• Apply the same plain-language discipline as the English version. Chinese technical writing has its own AI tells — avoid 「赋能」, 「助力」, 「生态」 where a simpler word works.

4. Review before writing

Before writing either file, verify:

• Every skill/component listed actually exists in the repository right now
• Installation commands are copy-pasteable and accurate
• No section describes something that has been removed
• Both files cover the same content in the same order

Then scan the draft for writing issues:

• Em-dashes used more than 2-3 times total? Cut most of them.
• Any sentence starts with "The X serves as..."? Rewrite as "The X is...".
• Bold-first bullet pattern throughout? Remove the bold.
• Same word or metaphor repeated across multiple descriptions? Vary it.
• Unicode arrows (→)? Replace with plain text.

5. Write the files

Write README.md first, then README.zh-CN.md. Use the Edit or Write tool — do not output the content as a code block in the conversation.

After writing, briefly confirm what changed (e.g., "Added update-readme skill, removed stale apple-events prerequisite note").

References

• references/template.md — README structure template (load when drafting)