Github readme override

Skill fabioc-aloha/Alex_Skill_Mall/plugins/devops-process/github-readme-override

284 curated plugins for AI assistants across 16 categories: security, Azure, documentation, code quality, cloud infrastructure, and more. Works with GitHub Copilot. Drop into .github/skills/local/ and go.

Install

npx -y skills add fabioc-aloha/Alex_Skill_Mall --skill github-readme-override

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

GitHub README display rules — which README renders when multiple exist, profile READMEs, org READMEs

SKILL.md

2.9 KB, as published. Nobody here has run it

GitHub README Override

Category: GitHub Time Saved: 30-60 minutes Battle-tested: Yes — multiple projects affected

The Problem

You update your root README.md with new documentation. You push to GitHub. The repo landing page still shows the old content — or worse, a completely different file.

Why It Happens

GitHub treats .github/README.md as a "community health file" and displays it on the repository landing page instead of the root README.md. This is documented behavior but surprising when you don't expect it.

The Hierarchy

GitHub displays the FIRST match found in this order:

1. .github/README.md     ← Overrides everything
2. README.md             ← Standard location
3. docs/README.md        ← Alternative location

The Fix

Option 1: Delete the override

git rm .github/README.md
git commit -m "Remove README override"
git push

Option 2: Rename it

# Keep the file but don't let it override
git mv .github/README.md .github/ABOUT.md
git commit -m "Rename to prevent override"
git push

Option 3: Symlink (if you want both)

# Make .github/README.md a symlink to root
cd .github
ln -s ../README.md README.md
git add README.md
git commit -m "Symlink README"
git push

Note: GitHub renders symlinks, but some Git clients handle them poorly on Windows.

When .github/README.md Is Intentional

Sometimes you want different content on the landing page vs. what developers see locally:

Use Case	Root README	.github/README
Internal tool	Technical setup	Public-facing overview
Template repo	"How to use template"	"What this template does"
Monorepo	Navigation/workspace docs	Project overview

Verification

# Check if override exists
ls -la .github/README.md

# See what GitHub will display
# Push and check the repo landing page

Common Symptoms

"I updated README but GitHub shows old content"
"My README looks different on GitHub vs. locally"
"README changes aren't showing up"

Related Files That Override

Similar override behavior exists for:

.github/CONTRIBUTING.md → overrides root CONTRIBUTING.md
.github/CODE_OF_CONDUCT.md → overrides root CODE_OF_CONDUCT.md
.github/SECURITY.md → overrides root SECURITY.md
.github/SUPPORT.md → overrides root SUPPORT.md

Verification Checklist

Check if .github/README.md exists
Determine if override is intentional
Delete, rename, or symlink as appropriate
Verify on GitHub after push

Related Skills

github-wiki-flat — Wiki structure gotchas