skills.rest
natthasath
natthasathCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

refactor-readme

Restructures README.md files into a standardized GitHub open-source format with emoji conventions and badges.

1|Updated Jun 29, 2026
Search Tags:#documentation#markdown#github#readme#refactor#badges#open-source
One-click install
npx skills add https://github.com/natthasath/natthasath-marketplace --skill refactor-readme-natthasath
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: refactor-readme
Source: https://github.com/natthasath/natthasath-marketplace/tree/main/plugins/refactor/skills/refactor-readme
Command: npx skills add https://github.com/natthasath/natthasath-marketplace --skill refactor-readme-natthasath

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? README files often grow inconsistent, cluttered, or poorly structured, making repositories hard to scan and unprofessional-looking. This Skill rewrites README.md files into one consistent, minimal pattern used across all projects. ## Core Features & Use Cases - Standardized Structure: Reorganizes sections into a fixed order (Title, Intro, Badges, Features, Installation, Usage, etc.) with English H3 headers and a consistent emoji convention. - Badge Management: Adds shields.io badges in a defined 6-group order, checking repo visibility first since dynamic GitHub badges fail on private repos. - Dual Patterns: Applies a full 27-section pattern for main/root READMEs and a compact pattern for sub-folder READMEs in monorepos, with progressive disclosure for large projects. - Use Case: You share a messy README for a FastAPI project. The Skill reads the file, restructures it with proper sections, converts config lists into tables, adds language-tagged code blocks and GitHub Alert callouts, then writes the result directly back to the file. ## Quick Start Run /refactor-readme with the path to your README.md file to rewrite it in the standard GitHub format.

Frequently Asked Questions about refactor-readme

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I refactor a README file to look like a standard GitHub open-source repo?▼

Invoke /refactor-readme with the path to your README.md. The Skill reads the existing content, restructures sections into a fixed order with emoji-prefixed English H3 headers, adds badges, and writes the result directly back to the file while preserving all original content.

What sections should a standard GitHub README include?▼

The standard order covers Title, Description, Features, Requirements, Installation, Configuration, Usage, Testing, Troubleshooting, License, and Contact among 27 optional sections. Only sections with real content are included; empty placeholders are removed.

Why do shields.io badges show repo not found on my README?▼

Dynamic badges that query the GitHub API fail on private repositories because shields.io calls the public API without authentication. For private repos, use static badges only for facts verifiable from project files like version and license, and omit metrics like build status or stars.

Can I use MkDocs or Docusaurus admonition syntax in a GitHub README?▼

No. Syntax like !!! note or ::: note renders as plain text on GitHub. Use GitHub Alert syntax (> [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]) instead, limited to one callout per section and only when skipping the note causes real consequences.

When should a monorepo use sub-folder READMEs instead of one long main README?▼

Split when the main README lists more than five components that each need their own usage details or reference tables. Keep the main README to one line per component with a link, and write each sub-folder README using the compact pattern without badges, installation, or license sections.

Related Skills

Explore More Software Engineering Skills→
oalansilvaoalansilva

dependency-risk-audit

Audit dependencies for licensing, security, and maintenance risk across software projects.

Community
Intermediate
GlourGlour

github-publisher

Publish GitHub repositories with bilingual READMEs and validation checklists.

Community
Advanced
gh-xjgh-xj

go-script-style

Standardize Go CLI scripts with a flat project structure and Taskfile.yml.

Community
Intermediate
beelabstudiobeelabstudio

documentation-writer

Creates and maintains technical documentation, API docs, README files, and user guides.

Official
Basic