general-readme-skill

name general-readme-skill description Use when generating or improving README.md for any project. Trigger on /readme, "generate readme", "write readme", "create project documentation", "更新README", "帮我写 README". version 1 tags documentation, readme, auto-generate, project-docs General README Skill 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 → Output Zero 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: Exact command: /readme Text commands: generate readme, write readme, create project documentation, update readme Chinese commands: 帮我写 README, 生成项目文档, 更新README Scenario: User requests to create/rewrite/refresh project README Phase 1: Configuration Collect configuration options from developer before generation. All options have fixed default values for quick use. Defaults (used when user supplies no configuration): Tone Profile = Professional Badge Style = Flat Primary language = English Secondary languages = none If the user provides no configuration, use these defaults. 1. Tone Profile (Default: Professional) Select README writing style: Energetic — Direct, confident, allow emojis in features. Reference: FastAPI style. Minimal — Terse, code-first, no redundant description. Reference: Tailwind CSS style. 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: package.json → dependencies / devDependencies requirements.txt / pyproject.toml → Python frameworks Gemfile → Ruby frameworks go.mod → Go frameworks Cargo.toml → Rust frameworks 2.3 Build & CI/CD Detection Makefile → Make commands CMakeLists.txt → CMake build package.json → Scripts field Dockerfile / docker-compose.yml → Docker deployment .github/workflows / .gitlab-ci.yml / Jenkinsfile → CI/CD pipelines 2.4 Database & ORM Detection Database connection config: DATABASE_URL, DB_HOST and related fields ORM frameworks: Sequelize, TypeORM, Prisma, SQLAlchemy, ActiveRecord, GORM Database drivers in dependency list 2.5 Architecture Type Detection Classify overall project architecture: Microservice : Multiple independent service folders + .proto / RPC files Frontend-Backend Split : client/server or frontend/backend directories Monolithic : Standard MVC / layered structure Event-Driven : Message queue dependencies (Kafka, RabbitMQ, etc.) 2.6 API Style Detection Identify interface type: REST : Route / endpoint definition files gRPC : .proto definition files GraphQL : .graphql schema files WebSocket : WebSocket server implementation code 2.7 License Detection Read root LICENSE / LICENSE.md Recognize common licenses: MIT, Apache-2.0, GPL-3.0, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0, Unlicense 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 diagram-templates.md — Mermaid templates + SVG fallback section-guidelines.md — Section writing rules & banned phrases language-guide.md — Multi-language naming & switcher rules Reference-file missing / invalid behavior: 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 Contributing — Standard fork → branch → commit → PR workflow License — One-line license statement Hero Template (HTML Centered Layout) 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. Structure: < h1 align = "center" > {PROJECT_NAME} </ h1 > < p align = "center" > < strong > {ONE_LINE_DESCRIPTION} </ strong > < br /> < em > {SUBTITLE_WITH_KEYWORDS} </ em > </ p > < p align = "center" > < a href = "#quick-start" > < img src = "https://img.shields.io/badge/{QUICK_START_TEXT}-{COLOR}?style=for-the-badge" alt = "Quick Start" /> </ a > < a href = "LICENSE" > < img src = "https://img.shields.io/badge/{LICENSE_TEXT}-{COLOR}?style=for-the-badge" alt = "License" /> </ a > </ p > < p align = "center" > {PLATFORM_BADGES} </ p > < p align = "center" > {LANGUAGE_SWITCHER} </ p > Rules: Title: Use <h1 align="center"> instead of Markdown # Description: Use <p align="center"> with <strong> for main description Subtitle: Use <em> for keywords/features line CTA Buttons: Use for-the-badge style for visibility (Quick Start, License) Platform Badges: Add AI IDE platform badges (Claude Code, Copilot, Cursor, etc.) Language Switcher: Use <p align="center"> with anchor tags Badge Style: Platform badges use the user-selected style from Phase 1 Platform Badge URLs: ![ Claude Code ]( https://img.shields.io/badge/Claude_Code-D97757?style=flat&logo=claude&logoColor=white ) ![ GitHub Copilot ]( https://img.shields.io/badge/GitHub_Copilot-000000?style=flat&logo=github&logoColor=white ) ![ Cursor ]( https://img.shields.io/badge/Cursor-000000?style=flat&logo=cursor&logoColor=white ) ![ Gemini CLI ]( https://img.shields.io/badge/Gemini_CLI-4285F4?style=flat&logo=google&logoColor=white ) ![ Codex ]( https://img.shields.io/badge/Codex-000000?style=flat&logo=openai&logoColor=white ) Critical Generation Rules (Must Follow) 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. 4.3 Beautification Rules Hero Region (Mandatory): Title: # Title → <h1 align="center">Title</h1> Description: > Description → <p align="center"><strong>Description</strong></p> Subtitle: keywords → <p align="center"><em>keywords</em></p> CTA Buttons: [Quick Start](#) → <a href="#"><img src="badge?style=for-the-badge"></a> Platform Badges: ![Badge](url) → <p align="center"><img src="url"></p> Language Switcher: [EN](README.md) → <p align="center"><a href="README.md">EN</a></p> Content Region (Optional): Tables: Keep Markdown (easier to maintain) Lists: Keep Markdown (easier to maintain) Collapsible panels: Keep HTML (already formatted) Code Region (Keep As-Is): Code blocks: Keep Markdown (has syntax highlighting) Mermaid diagrams: Keep Markdown (GitHub native support) Structure Region (Optional): Dividers: Keep --- Anchor links: Keep Markdown 4.4 Reference Files references/beautification-rules.md — Detailed beautification rules and HTML templates references/section-guidelines.md — Section-specific beautification notes 4.5 Exception Handling If beautification fails for an element, keep original Markdown If user rejects all suggestions, skip beautification entirely Add <!-- BEAUTIFIED --> marker after successful beautification Phase 5: Output Generate primary README.md in selected primary language. Generate secondary files: README-{lang}.md for each extra language. Add language switcher on top of every README file (follow language-guide.md ). Standard format: UTF-8 encoding, unified line break, clean empty lines. Final prompt to user: