github-repo-seo-standard

name	github-repo-seo-standard
description	Use when auditing, planning, measuring, or implementing GitHub repository discoverability work, including README/README_zh SEO review, Description or Topics proposals, release copy review, search ranking tracking, competitor or alternative term handling, Baidu/Bing/AI search channel assessment, site asset readiness, or portfolio rollout.

GitHub Repo SEO Standard

Overview

Use this skill to improve GitHub repository discoverability without unsupported claims, spam, or fake popularity signals. Treat SEO as an evidence loop: define facts, assess channels, measure, change only within permission, then retest.

Mode Gate

Choose a mode before any work:

• audit_only: read-only findings. Do not edit files, push branches, open PRs, change GitHub metadata, create releases, issues, or discussions.
• planning_only: draft copy, metadata proposals, keyword plans, measurement plans. Do not modify online state or open PRs.
• implementation: edit only after explicit user authorization. Stay within the requested write scope.

If the user did not explicitly authorize implementation, default to planning_only or audit_only.

Automation Implementation Guard

Cron, heartbeat, and recurring automation runs default to audit_only or planning_only.

They must not enter implementation unless the automation prompt contains all of:

• a current explicit user authorization for implementation
• a specific experiment_id
• the exact repositories and fields allowed to change
• the required verification and rollback or stop condition

If those are missing, output candidate experiments and requires_user_approval=true instead of editing README files, GitHub metadata, releases, branches, PRs, issues, discussions, or external pages.

Workflow

1. Define product facts and forbidden claims:
   • What the project is.
   • Who it is for.
   • What action it performs.
   • Which platforms and integrations are real.
   • Which upstream or competitor relationships are true.
   • Which claims are forbidden because they are unverified.
2. Assess channel fit:
   • GitHub, Baidu, Bing, AI search, docs/GitHub Pages, and external content.
   • For each channel, record execute, manual_task, or skip.
   • If skipped, record skip_reason.
   • For Chinese-user projects, default to at least Baidu and AI-search manual tasks unless product facts make them irrelevant.
   • Classify the controllable asset path: github_repo_only, docs_or_pages_available, external_site_available, or deferred_by_user.
   • If a docs/site asset exists, check sitemap, robots, schema/JSON-LD, canonical URL, llms.txt, Bing Webmaster/Search Console access, and IndexNow/Baidu submit readiness.
   • If the user paused site work, mark docs/site work deferred_by_user; do not design or publish pages.
3. Define target language and keyword breadth:
   • If target users are Chinese, use Chinese-first README/Description proposals and Chinese-first baseline queries.
   • Do not use easy English exact-match rankings as a substitute for Chinese discovery.
   • Mark keyword_width: broad_category, scenario_problem, platform_tool, exact_long_tail, or brand.
   • At least 60% of baseline queries should be broad_category or scenario_problem.
   • If only brand or exact_long_tail queries rank well, state "real discovery is unverified."
4. Build keyword candidates with evidence level:
   • brand, category, scenario, technical, competitor, alias.
   • Allowed evidence levels: observed_once, confirmed_weekly, repo_specific, channel_specific, portfolio_candidate, standardized.
5. Run baseline measurement before edits:
   • GitHub top100 for candidate queries.
   • Bing/Baidu checks or manual tasks.
   • AI prompts for DeepSeek/Doubao/Kimi/etc. or manual tasks.
   • Record query protocol: method, locale, region, logged-in state, sort mode, result type, endpoint, reviewer, raw evidence path/hash.
6. Choose one experiment theme:
   • Record hypothesis, changed fields, unchanged fields, target query groups, expected signal, confounders, and evidence level.
7. Draft or edit controlled fields only if mode allows:
   • Repository Description proposal.
   • Topics proposal.
   • README and README_zh first screen.
   • Release body.
   • Profile README for portfolio-level discovery.
8. Apply anti-stuffing review:
   • H1: project name plus at most one category or alias.
   • Description: at most one core category, one scenario, and one necessary relationship term.
   • First screen: no comma-separated keyword strings.
   • Competitor terms must be truthful, explained, and evidence-backed.
   • The copy must still help a real user after removing the SEO motive.
9. Verify and record:
   • Save pre-change metadata.
   • Use draft PRs for README changes when implementation is authorized.
   • Run git diff --check.
   • Run or queue tracking.
   • Mark immediate smoke results separately from stable 24-48 hour results.
   • List unverified conclusions.
10. Produce standard artifacts:

• baseline-ranking.csv
• metadata-proposal.md
• readme-change-summary.md
• post-change-smoke.csv when a smoke test is run
• asset-readiness.csv for release, profile, docs/site, package registry, issue/discussion, and AI citation assets
• Optional GITHUB-SEO-REPORT.md and GITHUB-ACTION-PLAN.md when a user asks for a portable report.

README First-Screen Standard

The first screen should contain:

• H1 with project name plus one category or alias.
• One sentence explaining user, platform, and job-to-be-done.
• A natural search-intent line with at most three phrase clusters, prioritizing the target user's language and broad category/scenario terms.
• Release/download or quick-start link.
• Essential trust boundary: privacy, upstream relation, non-official relationship, or unsupported claims.

Avoid turning the first screen into an unrelated keyword list. Keywords must read naturally and match real product capabilities.

Competitor and Upstream Terms

Default placement:

• Prefer README relation paragraph, Alternatives, or FAQ.
• Use Topics or Release only when evidence and context support it.
• Avoid H1. Use Description only when search-intent evidence and relationship clarity justify it.

Allowed examples:

• OpenLess-based
• 基于 OpenLess 改造
• Typeless alternative direction
• Typeless 替代方向

Forbidden examples without evidence:

• OpenLess official
• Typeless official
• 达到 80% Typeless 效果
• better than Typeless
• Accuracy, latency, cost, ranking, or adoption claims without measurement.

If evidence is weak, label the statement as a hypothesis and keep it out of user-facing README copy.

Measurement

Use the bundled script only when it matches the current lab format and the task permits running it:

Resolve the directory containing this SKILL.md as skill_root, then run the bundled script by its actual absolute path:

python "<resolved-skill-root>/scripts/run_seo_tracking.py"

Do not pass the literal placeholder to the shell.

When working in the GitHub SEO lab, prefer the project-local script if a script run is requested:

python 03_CODEX/scripts/run_seo_tracking.py

Visibility score is diagnostic only. Do not treat it as platform weight or proof of causality. GitHub rank, web rank, and AI mention/citation must be judged separately.

Website and AI Citation Assets

Separate GitHub repo SEO from website SEO:

• GitHub repo SEO controls README, Description proposals, Topics proposals, releases, and profile README.
• Website SEO controls page titles, meta descriptions, sitemap, robots, schema/JSON-LD, canonical URLs, IndexNow/Baidu submission, and webmaster data.
• AI citation readiness controls clear public pages, truthful entity descriptions, FAQ/limitations, release notes, upstream relationship notes, and optional llms.txt.

Use sitemap, URL submission, IndexNow, and Baidu push as indexing/discovery actions only. Do not record them as ranking improvements unless later measurement supports that.

Treat llms.txt, schema/JSON-LD, and brand entity coherence as candidate AI-search hypotheses. They are useful to consider when a controllable site exists, but they are not proven ranking levers for GitHub repo pages.

Release And Profile SEO

When release or profile work is in scope, audit or draft:

• release title, tag, asset names, download explanation, verification notes, platform words, and user-facing changelog
• repository profile or owner profile README language, project grouping, flagship links, and clear boundaries
• issue/discussion templates only as discoverability and support assets, not ranking proof

Release/profile copy must describe real artifacts and use cases. Do not add unsupported performance, quality, popularity, or competitor claims.

Hard Rules

• Do not edit GitHub metadata, push branches, open PRs, create releases, or change online repository state unless the user explicitly requested implementation.
• Do not let recurring automation perform implementation by default; it may only propose candidate experiments unless it has a specific user-approved experiment_id and write scope.
• Do not present a fix or causal explanation when evidence is insufficient; output known facts, candidate hypotheses, validation paths, temporary mitigations, and unverified conclusions.
• Do not optimize only for precise, low-result, or English exact-match queries when the target users search in Chinese.
• Do not present high rank on brand or exact-long-tail queries as proof of real exposure.
• Do not buy, trade, simulate, or automate stars, clicks, rankings, or low-quality backlinks.
• Do not use black-hat Baidu SEO, click scripts, site networks, or mechanically duplicated external content.
• Do not treat sitemap submission, URL submission, IndexNow, Baidu push, schema, or llms.txt as ranking proof; they require later validation.
• Do not design, create, or publish docs/GitHub Pages/site pages when the user has deferred site work.
• Do not put competitor terms in H1/Description/Topics unless the relationship is truthful, explained, and supported by search-intent evidence.
• Do not repeat the same keyword family across H1, Description, first screen, Topics, and Release without a user-readable reason.
• Do not treat AI mention as rank, citation, or recommendation unless the evidence separately supports that label.

Read references/repo-seo-standard.md for the compact execution reference.