Use when generating or improving README.md for any project. Trigger on /readme, "generate readme", "write readme", "create project documentation", "更新README", "帮我写 README".
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use when generating or improving README.md for any project. Trigger on /readme, "generate readme", "write readme", "create project documentation", "更新README", "帮我写 README".
Generate professional, human-feeling README files for any project.
Strictly follow real project content, reject filler text and placeholder content.
Overview
Full workflow: Configure → Scan → Generate → Beautify → OutputZero external dependencies. All rules, templates and assets are embedded in the skill.
No third-party CLI, runtime or network service required for core functions.
Trigger Rules
Trigger this skill when user inputs match any of the following:
Professional — Neutral, structured, formal layout. Reference: Kubernetes style.
2. Badge Style (Default: Flat)
Select shields.io badge appearance:
Flat — Clean, compact, standard style
Flat-square — Sharp edges, modern compact style
for-the-badge — Tall, bold, highly visual style
3. Multi-Language Setting
Primary language (Default: English)
Secondary languages (Optional: Chinese, Japanese, Korean, Spanish, French etc.)
File naming follows rules in language-guide.md.
Phase 2: Project Scan
Use built-in Read, Grep, Glob tools to scan local project directory.
Rules: Only read static files. Never execute, modify or delete any project files.
Ignore directories: node_modules, .git, build, dist, pycache, .venv, .next, coverage, logs
Detector priority and tie-break rules (deterministic order):
Manifest parsing: inspect recognized manifests (package.json, pyproject.toml, go.mod, Cargo.toml, etc.). If a manifest clearly declares language/framework, mark that as primary.
Explicit dependency declarations: prefer declared dependencies/devDependencies when identifying frameworks.
File-extension majority: use only if manifests are absent or ambiguous.
Heuristic filename patterns: use as a last resort.
If multiple sources conflict, prefer the earlier item in this list. If manifests conflict (multiple package roots), prompt the user to choose which package root to document or follow the manifest precedence rules below.
2.1 Language Detection
Parse recognized manifests: package.json, pyproject.toml, Cargo.toml, go.mod, Gemfile, pom.xml, build.gradle. If a single manifest declares the project language unambiguously, that is the Primary Language.
If no manifest is present or manifests are ambiguous, use majority file-extension count across the selected package root.
If multiple manifests declare different languages for different package roots, prompt the user to select which package root to document, or default to manifest precedence: package.json > pyproject.toml > go.mod > Cargo.toml.
2.2 Framework Detection
Parse dependency fields to identify used frameworks:
If no LICENSE file is present, do not add a license section; instead add a one-line recommendation: No LICENSE file detected. Add a LICENSE to clarify project licensing.
If multiple conflicting license files are present, list them and prompt the user to confirm which to use (for example: Detected license files: LICENSE, LICENSE.md. Please confirm which to use.).
2.8 Project Type Detection
Library: Publish config for distribution, no startup script
Application: Has dev/start runtime scripts, not for public publishing
CLI Tool: bin field, executable output, Go cmd/ directory
Static Site / Demo: Frontend-only, no backend service
2.9 Git & Contributor Detection
Do NOT execute commands or modify the repository. Never run git or other tools that alter state.
If a readable .git directory or static contributor file (e.g., CONTRIBUTORS, AUTHORS) exists and can be inspected without executing commands, extract contributors' names only (no emails). Redact or omit sensitive metadata. Example: Contributors: 3 (Alice, Bob, and 1 other).
If git metadata is inaccessible (no .git, shallow clone, permission denied, or cannot be read without executing), skip contributor detection and include this note: Contributor history unavailable (no git metadata access). Offer an option to supply contributors manually.
Extract commit convention rules only from static config files (e.g., .github/commit-convention.md, CONTRIBUTING.md)—do not execute or parse live git logs.
2.10 Configuration File Detection
Scan root & config folders for .env, .env.example, *.config, *.yml, *.yaml etc.
Phase 3: Generate Content
Load all reference files first, then generate content strictly by rules.
Load Reference Files
All references located in references/ folder:
tone-profiles.md — Style rules & sample phrases
badge-styles.md — Badge layout & grouping rules
badges.md — Technology to shields.io badge mapping
Before generation, verify that all listed files in references/ exist and are readable. If any are missing or malformed, abort generation and return: Missing or invalid reference files: <list>. Generation paused.
Optionally allow a proceed-with-defaults flag to continue using built-in safe defaults; require explicit user confirmation to proceed.
Fixed Section Order (Inverted Pyramid)
Do NOT reorder sections. Skip any section if no matched project data.
No N/A, Coming soon or placeholder content.
Fixed-order application and manual content preservation:
Fixed section order applies only to auto-generated sections. Preserve any manually written content in-place when it is wrapped with HTML markers <!-- MANUAL-START --> and <!-- MANUAL-END -->, or when a top-level section is not tagged <!-- AUTO-GENERATED -->.
If a preserved manual section breaks the fixed order, leave it in place and insert regenerated auto sections around it rather than moving or deleting manual content.
Hero — Project name(H1), one-line description, badges. Use HTML centered layout for professional appearance (see Hero Template below).
Features / Why — Max 6 core differentiating features
Quick Start — Max 4 copy-paste command steps
Usage — Real code examples, max 4 items
Architecture Diagram — Mermaid/SVG with color classes. Required for all project types. Select diagram type based on architecture (see diagram-templates.md)
Configuration — Table view, only if config files exist
API — Endpoint table, only if API routes exist
Directory Structure — Annotated tree, max depth = 3
Tech Stack — Grouped by technical layers
Deployment — Docker/CI guide, only if deployment files exist
The Hero section uses HTML <p align="center"> tags for a professional, centered appearance. This layout is inspired by modern open-source projects like Understand Anything.
No fabrication: All features, commands, code examples must come from real project files.
Style consistency: All text follows selected Tone Profile and banned phrase list.
Badge rules: Follow grouping & style in badge-styles.md.
Structure rules: Every section strictly obeys section-guidelines.md.
Incremental Update: If README.md already exists:
Preserve manual content only when explicitly marked: content between <!-- MANUAL-START --> and <!-- MANUAL-END -->, and any top-level sections not tagged <!-- AUTO-GENERATED -->.
Re-generate only sections marked <!-- AUTO-GENERATED --> or other clearly auto-scanned regions.
Precedence (constraint resolution order):
Privacy Protection (must) — mask secrets and private data.
Preserve manual content (markers above) — do not move or delete.
No fabrication — do not invent facts not present in project files.
Fixed section order — applies when composing only auto-generated sections; do not move preserved manual sections.
If constraints conflict, follow the numeric precedence above.
Privacy Protection: Mask sensitive keys, passwords and private info in config/code.
Phase 4: Beautification (Auto-Triggered)
After Phase 3 generates the README, this phase automatically triggers to enhance visual presentation by replacing suitable Markdown syntax with HTML.
4.1 Trigger Conditions
Automatically triggers after Phase 3 completes
Skips if user explicitly disables beautification (--no-beautify flag)
Skips if README already contains HTML markers (<!-- BEAUTIFIED -->)
4.2 Execution Flow
Step 1: Analysis (Automatic)
Scan the generated README.md and identify beautifiable elements:
Hero region: title, description, badges, language switcher
Content region: tables, lists, collapsible panels
Code region: code blocks, Mermaid diagrams
Structure region: dividers, anchor links
Step 2: Confirmation (User Interaction)
Display beautification suggestions to user:
AI: README generation complete! Analyzing beautification opportunities...
Found the following beautification suggestions:
1. ✅ [Hero] Title centered → <h1 align="center">
2. ✅ [Hero] Description centered and bold → <p align="center"><strong>
3. ✅ [Hero] Add CTA buttons
4. ✅ [Hero] Platform badges centered
5. ⚪ [Content] Tables keep Markdown (easier to maintain)
6. ⚪ [Code] Code blocks keep Markdown (has syntax highlighting)
Accept these suggestions?
[Accept All] [Confirm Each] [Reject All]
Step 3: Execution (Automatic)
Apply selected beautifications based on user confirmation.
