name github-exposure-standard description Use when releasing a new open-source project or skill pack on GitHub. Follows the proven exposure playbook from Hermes Core Skills release — covering README, community health, topics, social media, and verification. Ensures every release meets a minimum exposure bar so the project is discoverable, trustworthy, and ready for adoption. version 1.0.0 author Chris Lam / Hermes Agent (experiential learning from hermes-core-skills release, Jun 2026) tags ["github","release","exposure","open-source","README","social-proof","community-health","topics","badges","SEO"] trigger_phrases ["release this to GitHub","publish on GitHub","提高曝光","發佈去 GitHub","做好個 repo 先","GitHub exposure","準備 release","開源發佈"]
GitHub Release Exposure Standard
Point of View
當你準備 release 一個新 open-source project 上 GitHub，唔可以就咁 push code 就算。你需要一個系統性曝光流程 ，確保每個層面嘅用家（全端工程師、AI 初學者、CTO、開源貢獻者、非英語用家等）都搵到佢哋想要嘅嘢，從而提高 star、fork、adoption 嘅機會。
呢個標準係從 hermes-core-skills 發佈嘅實戰經驗提煉出嚟，涵蓋 3 個階段、15 項操作 。
Phase 1: Repo 基礎建設（先於發佈）
呢啲係發佈前就要做嘅底層工作，唔可以後補。
1.1 README 結構標準
README 必須包含以下 sections（按順序）：
[1] Title + Badges row
[2] One-liner tagline（解決咩問題）
[3] Pain points / 場景描述（You've been there）
[4] Quick Start（git clone + 多平台 install，參考 Anthropic Cybersecurity Skills 嘅 npm + clone 雙選方式）
[5] Why This Project（背景動機 + 痛點 + 解決方案，參考佢哋嘅 workforce gap framing）
[6] Comparison vs alternatives（如適用，參考佢哋嘅 comparison table style）
[7] 使用範例（至少 3 個實際 scenarios，對話格式）
[8] Feature overview / Skill table + Skill Anatomy（解釋每個 skill 嘅內部結構）
[9] Compatible Platforms table（列出所有支援平台，參考佢哋嘅 category breakdown）
[10] Beginner guide（For Beginners section，4 個基本問題）
[11] Use Cases table（邊個角色用邊個功能）
[12] Roadmap（未來發展路線，checkbox 形式）
[13] What People Are Saying（testimonials / 早期用家 feedback）
[14] Star History（star-history.com 圖表 badge）
[15] Featured In（被邊啲 awesome list / 平台收錄）
[16] How to Contribute（Good First Issues，包括非 code 貢獻）
[17] Citation（學術引用格式 bibtex）
[18] License
參考案例： mukul975/Anthropic-Cybersecurity-Skills （18.8k ⭐）嘅 README 結構係 gold standard：
佢有「Why This Project」section 用 workforce gap 帶出 project 必要性
佢有「Quick Start」用 npm install + git clone 雙選
佢有「What People Are Saying」testimonials 增加社交 proof
佢有「Featured In」section 顯示被收錄狀態
佢有「Star History」圖表展示增長趨勢
佢有「Compatible Platforms」詳細分類（AI Code Assistants / Autonomous Agents / Agent Frameworks）
佢有「Citation」bibtex 格式俾學術用家引用
佢有「Skill Anatomy」解釋每個 skill 嘅 YAML frontmatter + markdown body 結構
佢有「Roadmap」唔使用 checkbox 形式，用 bullet list 描述未來計劃
Badges 要求：
Badges 要求：
GitHub stars（動態）
GitHub forks（動態）
License（MIT 推薦）
每個支援平台一個 badge（Claude Code、Cursor、Codex、Hermes Agent 等）
Badges 格式範例：
[](https://claude.ai)
Pain Points section 必須用「You've been there:」bullet list 形式 ，直接打中 target audience 嘅日常痛點。
1.2 Community Health Files
Repo 必須有以下檔案先算 complete：
檔案 位置 用途 CODE_OF_CONDUCT.mdroot Contributor Covenant CONTRIBUTING.mdroot 貢獻指引 SECURITY.mdroot 安全漏洞上報流程 LICENSEroot MIT 推薦 .github/CODEOWNERS.github/ 預設 code owner .github/FUNDING.yml.github/ Funding 鏈接 .github/PULL_REQUEST_TEMPLATE.md.github/ PR template .github/ISSUE_TEMPLATE/bug_report.md.github/ISSUE_TEMPLATE/ Bug report template .github/ISSUE_TEMPLATE/feature_request.md.github/ISSUE_TEMPLATE/ Feature request template .github/ISSUE_TEMPLATE/config.yml.github/ISSUE_TEMPLATE/ 指向 Discussions
GitHub 會自動檢測呢啲檔案 ，喺 repo 頂部顯示 Community Standards 進度條。目標係 100%。
1.5 Infrastructure Files（參考 Anthropic Cybersecurity Skills）
以下 infrastructure 檔案令 repo 更專業、agent 更容易使用：
檔案 用途 建議 index.json所有 skills 嘅 JSON 索引，agent 可快速 scan 唔使逐個 file 開 必加 — 用嚟俾 agent discoverySPECT-*.md大型改動前嘅 spec document 建議保留喺 repo 做記錄 mappings/Skills 對應標準框架（如 MITRE、NIST、用家場景） 後續可加 .claude-plugin/Claude Code marketplace 插件設定 後續可加 docs/補充文件 選擇性加
index.json 格式範例：
{
"version" : "1.0.0" ,
"generated_at" : "2026-06-23T10:00:00Z" ,
"repository" : "https://github.com/user/repo" ,
"domain" : "your-domain" ,
"total_skills" : 25 ,
"skills" : [
{
"name" : "skill-name" ,
"description" : "Brief description" ,
"domain" : "main-category" ,
"subdomain" : "sub-category" ,
"path" : "skills/skill-name" ,
"tokens" : {
"scan" : 150 ,
"load" : 2500 ,
"category" : "standard"
}
}
]
}
1.6 SKILL.md Frontmatter 標準
每個 SKILL.md 嘅 frontmatter 應該有：
---
name: skill-name
description: ...
domain: main-category
subdomain: sub-category
tokens:
scan: 150
load: 2500
category: standard
---
Domain 分類系統參考（4 domains, 9 subdomains）：
agent-core: quality-control, safety, efficiency, planning
ecosystem: agent-comparison, agent-skills
cross-session: continuity, setup
integration: architecture
去 repo Settings → About section → Topics input，加以下 tags（空格分隔，最多 20 個）：
核心 tags（必加）：
ai-agent open-source developer-tools
平台 tags（視乎支援）：
claude-code codex mcp hermes-agent
功能 tags：
automation workflow-automation skills agent-skills
搜尋 reach tags（擴展 reach）：
langchain llamaindex cursor prompt-engineering
資源限制：
Fine-grained PAT 唔可以 透過 API 寫 topics（403）
Topics 必須用 browser UI 手動 set
建議分批次 save（3-5 tags 一次），太多 tags 同時 save 會 fail
Phase 2: README 深度內容（發佈時做）
2.1 Why This Project Section
參考 Anthropic Cybersecurity Skills 嘅 framing pattern：
## 💡 Why These Skills?
### The problem
[Describe the industry-wide pain point with concrete numbers/statements]
### The solution
[Explain how this project solves that problem - what makes it different]
用「problem → solution」嘅 framing，唔好直接 sell features。先令讀者覺得「佢明我嘅痛」，再講點解你嘅方案得。
2.2 Skill Anatomy Section
解釋每個 skill 嘅內部結構，幫助用家/貢獻者理解格式：
## 🧬 Skill Anatomy
Every skill follows a consistent directory structure:
skills/<skill-name > 如果係 YAML frontmatter 格式，提供真實例子。
2.3 Compatible Platforms Table
列出所有支援平台，分 category：
| Category | Platform |
|----------|----------|
| **AI Code Assistants** | Claude Code, OpenAI Codex CLI, Cursor, Hermes Agent, GitHub Copilot |
| **Agent Frameworks** | LangChain, CrewAI, AutoGen, Any MCP-compatible agent |
| **MCP Clients** | Claude Desktop, VS Code via Continue/Cline, JetBrains, any MCP host |
2.4 Testimonials / What People Are Saying
Social proof section 放 early adopter quotes：
> *"[Concrete benefit quote]"*
> — **Role / Person, Date**
> *"[Specific feature saved me X]"*
> — **Role / Person, Date**
唔好作 fake quotes。如果未有 real feedback，用「Early adopter feedback」等 neutral phrasing。
2.5 Star History
用 star-history.com badge 顯示增長趨勢：
[](https://star-history.com/#user/repo&Date)
呢個 badge auto-update，展示 project 嘅 social proof。
2.6 Featured In Section
列出被邊啲 awesome list / platform 收錄：
## 📖 Featured In
- **awesome-list-name** — Description ([link](url))
- **platform-name** — Description ([link](url))
如果未有被收錄，用「Want to feature this project? Let us know 」俾人聯絡。
2.7 Citation Section
學術引用格式（bibtex），幫 researcher 引用：
@software{project_name,
author = {Your Name},
title = {Project Title},
year = {2026},
url = {https://github.com/user/repo},
note = {Brief description. License.}
}
2.8 Roadmap Section
未來發展路線，checkbox 形式或 bullet list：
## 🗺️ Roadmap
- [x] v1.0.0 — Core features released
- [ ] v1.1.0 — Next milestone
- [ ] v2.0.0 — Major upgrade
2.9 Platform-Specific Quick Start
每個支援平台都要有自己嘅 install section，格式：
### Platform Name
\`\`\`bash
cp -r skills/* ~/.platform/skills/
\`\`\`
Platform auto-discovers skills in ~/.platform/skills/. After copying, just ask:
> *"Use the [skill-name] skill to [task]."*
唔可以只寫一條通用 command。每個平台嘅 behavior 唔同，要分開寫。
2.2 實際對話範例（Scenarios）
至少 3 個 scenarios，格式：
### Scenario N: [Pain point title]
\`\`\`
You: "[Prompt using the skill]"
Agent: [Loads workflow]
- Step 1
- Step 2
- Step 3
Result: [Concrete outcome]
\`\`\`
每個 scenario 必須對應一個真實痛點，同埋一個具體 skill。
2.3 Comparison Table（如適用）
同 alternatives 比較，格式：
| Feature | This Project | Alternative A | Alternative B |
|---------|-------------|---------------|---------------|
| Feature 1 | ✅ ✓ | ❌ ✗ | ❌ ✗ |
| Feature 2 | ✅ ✓ | ❌ ✗ | ✅ ✓ |
必須誠實。只比較真正有優勢嘅維度。
2.4 Beginner Guide
For Beginners section 必須回答 4 個問題：
What is [project type]? — 用 simplest 嘅定義What's a [core concept]? — 比喻解釋（e.g. skill = recipe for AI chef）How do I use it? — 3 步流程Which [feature] should I start with? — 推薦順序
2.5 Use Cases Table
依角色分類，格式：
| Who | Problem | Solution |
|-----|---------|----------|
| **Solo developer** | [pain point] | [specific features] |
| **Startup CTO** | [pain point] | [specific features] |
2.6 Contribution Guide
「Good First Issues」必須列出唔使寫 code 嘅貢獻方式：
📝 Review a feature
🌐 Translate README
🐛 Report a bug
✨ Suggest new features
2.7 Translation Invites
加多語言 badges，鼓勵 community 貢獻翻譯：
[](discussion-link)
[](discussion-link)
2.8 Visual Placeholder
如果未有 screenshot/demo GIF，至少加一個 placeholder section：
<div align="center">
## 📸 Demo
*Screenshot coming soon — [watch the repo](link) for updates*
</div>
Phase 3: 曝光渠道（發佈後立即做）
3.1 GitHub 層面
操作 點做 效果 Pin repo 去 profile Profile → Popular repos → Customize pins Profile 首頁顯示 GitHub Pages 啟用 Settings → Pages → Enable 有 landing page Release 建立 Releases → Draft new release → Tag + 描述 v1.0.0 ZIP 可下載 Discussions 啟用 Settings → General → Discussions ✅ Community 交流區 Social preview image Settings → Social preview → upload 1280x640 PNG 分享 link 時有 preview Wiki / Projects 關閉 Settings → 唔需要就關 保持 repo 整潔 Profile README 更新 個人 profile repo 加 pinned repo 描述 Profile 引導流量
3.2 社交媒體層面
平台 內容策略 頻率 X/Twitter Short post + repo link + 1-2 個痛點 bullet + 1 screenshot/GIF 發佈日 1 次 Reddit (r/programming, r/MachineLearning, r/ClaudeAI) Longer post → project介紹 → pain point → 同 alternatives 比較 → 點解唔同 發佈日 1 次 Hacker News Show HN post → 直接 link repo → comment 區回應問題 發佈日 1 次
Social post 結構標準：
Hook（一句捉住注意力，e.g. "Your AI coding agent keeps doing dumb things?"）
Pain point bullet（3 個 bullet max）
解決方案（簡單一句）
Link to repo + 話明 MIT license
Call to action（Try it, star it）
Top 100 爆星因素研究（2026-06-23 分析）
從 GitHub Top 100 starred repos 研究所得，排除社交媒體因素，純粹 GitHub 層面嘅爆星共通因素：
爆星因素排名（由最重要到次要）
零摩擦價值主張（≤3秒明） — 標題+第一句就要令人明呢個 repo 做咩。爆星 repo 全部符合問題導向定位 — 唔好 sell features，sell solutions。用 pain points 做章節標題（仿 mattpocock/skills 嘅 #1, #2, #3 pattern）Social Proof Badges — 自訂 badge 顯示採用率（仿 anthropics/skills 嘅「▲ Skills - 2.2M」）快速入門體驗 — Quick Start 要寫「30 seconds」，越低 friction 越好平台兼容性 — 支援越多平台，distribution channel 越闊。obra/superpowers 支援 5+ IDE pluginsTopics SEO — 越多 topics 越容易被發現。hermes-agent 有 16 個 topics 係策略性作者/機構品牌 — 呢個最難複製但最重要。anthropics, github, torvalds, sindresorhus 全部有品牌光環Bookmarkability — Lists / tutorials / primers 呢類 repo 天然易爆星（star = bookmark）。Skills repo 都係 reference material，有同樣優勢
具體執行建議
README 頭 20 行必須涵蓋：badges row + tagline + numbered pain points + Quick Start
pain points 用 #1, #2, #3 形式，唔好用普通 bullet list
加 custom badge 顯示 skills count / users count
Quick Start 寫「30 seconds」唔係「Quick Start」
Topics 策略：16-20 個 tags，覆蓋平台 + 功能 + 搜尋 reach 三類
用以下 checklist 驗證每個項目完成咗先叫「發佈完成」：
✅ Phase 1: Repo 基礎建設
✅ Phase 2: README 深度內容
✅ Phase 3: 曝光渠道
Pitfalls
Topics API 403 : Fine-grained PAT 唔可以寫 topics，必須 browser UI 手動。分批次 save 3-5 tags 一次，全部 save 會 fail社交 proof chicken-and-egg : 0 stars 會令新用家卻步。呢個只能靠社交媒體發文引發第一波。聽日發文後有人 star 先有 momentumREADME 太長嚇人 : 用 emoji + 分隔線 --- + tables 增加掃讀性。關鍵信息放頭 30%Translation badges 點去邊 : Badges 必須 link 去 Discussions／PR，唔好 link 去 dead pageBadge logo 參數 : shields.io badge logo 參數必須正確，否則 badge 顯示空白。測試每個 badge 先 pushGIF demo 困難 : Headless 環境錄 terminal GIF 需要 ttyd/VHS。如果環境唔支援，可叫 user 用 asciinema / QuickTime 自己錄Community health 檢測 delay : GitHub 需要時間 crawl 新檔案，community standards 可能延遲 1-24 小時先更新到 100%Fine-grained PAT 嘅 Git push ：gh auth login 後 git push 可以 work，但 gh repo create 會 403。Create repo 需要 user 手動去 github.com/new
相關 Skill
github-repo-management — Cloning, creating, configuring reposgithub-finegrained-pat-limitations — PAT edge casesgithub-topics-react-form-workaround — Browser UI topics workaroundgithub-skills-release-preparation — Original release prep workflow 