Github readme

GitHub README

Create a README that helps a new reader quickly decide whether the project fits, reach a first successful result, and continue without friction.

The desired feel is:

• 高级：信息有取舍，视觉克制，事实可信，不像模板拼装；
• 简单：接口少、路径短、没有为了“完整”而堆章节；
• 舒适：从读者问题出发，命令可复制，段落易扫描，下一步明确。

Default outcome

Unless the user says otherwise:

• Work on the repository-root README.md.
• Create it if missing; otherwise improve it conservatively.
• Match the user's language. If unspecified, follow the existing README and repository docs; if none exist, follow the user's language.
• Edit only the README. Report missing examples, scripts, license files, screenshots, or docs instead of fabricating them.
• Base technical claims on repository evidence or explicit user input.
• Preserve correct project-specific knowledge and the project's voice.
• Use the bundled checker at the end when Node.js is available.

The reader journey

Design the README so a first-time visitor can answer, in order:

1. 这是什么？
2. 它解决什么问题，适合谁？
3. 为什么值得继续看？
4. 怎样得到第一个成功结果？
5. 常见用法是什么？
6. 限制、兼容性、安全或维护状态有哪些？
7. 去哪里看完整文档、提问、贡献和确认许可证？

This is a cognitive funnel: broad and decision-critical information first, detailed and optional information later.

Workflow

1. Understand the request

Infer:

• create, rewrite, simplify, or review;
• primary reader: evaluator, user, contributor, operator, or teammate;
• project shape: library, CLI, app, service/API, plugin/agent package, docs, starter, or monorepo;
• explicit constraints: language, tone, sections/assets to preserve, public vs internal use.

Do not start with a questionnaire. Ask only when a missing answer would materially change the README and cannot be inferred from the repository.

2. Inspect evidence before writing

Read the smallest high-signal set first:

1. existing README and project instructions;
2. manifests and lockfiles;
3. entry points, public exports, CLI help, routes, or startup code;
4. examples, tests, docs, and CI workflows;
5. LICENSE*, CONTRIBUTING.md, SECURITY.md, release/deployment configuration;
6. existing screenshots, diagrams, or demo links.

Establish evidence for:

• project name and one-line definition;
• target reader and core use case;
• prerequisites and supported installation path;
• shortest real start/use command;
• visible success signal;
• common use cases;
• important limitations or warnings;
• project status and license;
• deeper documentation and support entry points.

If a fact is not supported, omit it, phrase it cautiously, or list it for confirmation. Never polish a guess into a fact.

3. Audit the existing README

Classify current content:

• keep — correct, project-specific, valuable;
• repair — stale commands, broken links, weak ordering, jargon, missing success signal;
• remove — empty sections, repeated prose, generic template residue, decorative noise;
• confirm — important but unverifiable statements.

Prefer focused restructuring over replacing everything. Preserve benchmarks, deployment notes, warnings, compatibility details, acknowledgements, and contribution rules when they remain accurate.

4. Choose the minimum useful structure

A strong default is:

1. title;
2. one-sentence value proposition;
3. optional essential status/warning;
4. optional screenshot/demo/terminal evidence;
5. quick start;
6. common usage;
7. project-specific depth: configuration, API, deployment, concepts, architecture, or troubleshooting;
8. documentation/support;
9. contributing;
10. license.

Do not force every section into every project. Read references/project-shapes.md when project-specific guidance is useful.

When the user explicitly wants a beautiful, polished, premium-looking, visually rich, or highly presentable README—or when the repository already has useful visual assets—also read references/visual-design.md. Use it to design the first screen, choose comparable examples, and decide whether screenshots, badges, Mermaid, tables, <details>, or restrained HTML genuinely help.

A short honest README is better than a large template containing empty or invented sections.

5. Write the top section first

The first screen should usually contain:

• a clear title;
• one sentence saying for whom, what it does, and in what situation;
• one short paragraph or a few concrete benefits when needed;
• only decision-relevant status badges;
• the most explanatory evidence: a screenshot, demo link, terminal result, or minimal code example.

Avoid starting with implementation history, architecture, a long table of contents, a badge wall, or marketing adjectives such as “awesome”, “next-generation”, and “blazing fast” without evidence.

6. Build a complete quick start

A quick start needs more than an install command. Include:

• prerequisites only when necessary;
• copyable commands;
• smallest safe configuration;
• first invocation;
• a success signal: expected output, URL, response, generated file, UI state, or next step.

Use commands supported by manifests, lockfiles, CI, examples, or actual project configuration. Do not invent package publication, ports, scripts, flags, environment variables, or output.

If runtime verification is safe and the user allows it, run the smallest non-destructive path. Otherwise state that validation was static.

7. Make it feel polished, simple, and comfortable

Polished

• Use specific nouns and verbs rather than slogans.
• Keep terminology and heading style consistent.
• State limitations and maturity honestly.
• Prefer evidence over claims.
• Link to deep docs instead of duplicating them.

Simple

• One primary path before alternatives.
• One good example before an option catalog.
• No empty sections or generic filler.
• No manual table of contents unless the README is genuinely long.
• Keep paragraphs short and lists purposeful.

Comfortable

• Put commands in fenced blocks with a language.
• Separate commands from explanations.
• Explain what success looks like.
• Use descriptive link text and repository-relative links for local files.
• Make warnings visible but rare.
• Let headings answer reader questions.
• Preview the final result in GitHub's renderer when publication is part of the task.

8. Use visual elements with restraint

Images, GIFs, demos, diagrams, HTML, and badges are optional tools—not the structure of the README.

Use them when they answer a project question faster than text:

• screenshot: what does the UI look like?
• GIF: what is the short interaction flow?
• diagram: how do a few major parts relate?
• terminal output: what does the tool actually do?
• badge: what is the current build, version, compatibility, or license status?
• table: which small, regular set of options or compatibility facts must be compared?
• <details>: which optional variants or bulky output can leave the primary path?

Rules:

• Essential information must remain available as text.
• Prefer repository-hosted essential assets and relative paths.
• Add meaningful alt text.
• Use GitHub-supported Mermaid when a small architecture or workflow diagram reduces explanation cost.
• Keep badges few—normally 3–6—and link them to real evidence.
• Use <details> only for optional variants, not prerequisites, warnings, or the primary example.
• Do not add decorative GIFs, contribution snakes, streak cards, language cards, or personal activity graphs to a project README.
• Do not add badges without a trustworthy target and real reader value.
• Do not generate or redesign branding unless the user requests it.

9. Verify and refine

Reread the result as a new reader, then check:

• title and one-line value are clear;
• the first screen balances identity, positioning, navigation/trust, and proof without visual noise;
• first success path is complete;
• commands/scripts/paths/ports/env vars match repository evidence;
• local links and anchors work;
• images have useful alt text and important visuals remain readable;
• badges link to real evidence and Mermaid diagrams render when used;
• code fences and heading levels are valid;
• no template residue remains;
• no secret or unsafe copy-paste command appears;
• license wording matches repository files;
• no important existing knowledge was lost.

When Node.js 22.19+ is available, run from the target repository root:

node /path/to/this-skill/scripts/check-readme.mjs README.md --strict

Resolve the actual skill directory before running the command. Fix deterministic errors and relevant warnings, then rerun it. Do not invent content merely to silence a warning.

The checker is offline and does not execute README commands. A passing result verifies mechanical consistency, not writing quality or runtime success.

10. Report succinctly

Tell the user:

• what changed;
• the main reader journey you optimized;
• what was verified and whether commands were actually run;
• checker result;
• unresolved facts requiring human confirmation.

Review-only mode

When the user asks for review but not editing:

1. inspect the repository and README;
2. report issues by reader impact, highest first;
3. distinguish factual errors from editorial suggestions;
4. propose a simpler information architecture;
5. do not rewrite unless asked.

Useful categories:

• adoption blockers;
• quick-start failures;
• stale or unsupported facts;
• missing trust/status/license information;
• readability and ordering;
• decorative or duplicated content;
• maintenance risks.

Never do this

• Invent features, compatibility, performance, installation channels, ports, env vars, output, maintainers, roadmap, or license terms.
• Turn a project README into a GitHub profile README.
• Optimize for length, section count, badge count, or a subjective score.
• Hide caveats that affect adoption.
• Put architecture/history before a usable example without a strong reason.
• Execute destructive, deployment, migration, or remote-pipe commands just to validate documentation.
• Replace a project's voice with generic AI marketing prose.
• Claim runtime validation when only static inspection was performed.