github-repo-launch-page

GitHub 仓库发布页技能

用途

将仓库从“代码堆”变成一个面向公众的项目页面，并依次回答：

1. 这是什么？
2. 面向哪些人？
3. 为什么现在值得关注？
4. 我可以信任它吗？
5. 我能在 5 分钟内试用吗？
6. 接下来该去哪里？

此技能涵盖 GitHub 仓库页面的各个部分：

• 仓库名称和产品名称
• GitHub About 描述
• 主页 URL
• topics
• README
• 截图、演示、图表、社交预览图
• 文档结构
• 许可证、贡献、安全和支持文件

如果需要处理命名，请先调用 github-repo-product-naming，也可以同时调用。再好的 README 也无法完全弥补糟糕的名称。

适用场景

当用户要求以下事项时，使用此技能：

• 创建或重写仓库 README
• 让 GitHub 仓库更有吸引力、更可信，或更容易“走红”
• 为发布、分享、招聘人员、Hacker News、Reddit、LinkedIn 或 X 做准备
• 改善仓库 SEO 和可发现性
• 设置 GitHub About 描述、topics、网站、置顶仓库外观、社交预览图、文档、截图、徽章、议题模板或贡献文件
• 反向分析成功开源项目的 README 模式

撰写前先检查

如有以下内容，请先检查：

• 仓库名称、包名称／应用程序名称、CLI 名称
• GitHub About 描述、主页 URL、topics、许可证、可见性、归档状态
• README.md
• LICENSE
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• CHANGELOG.md
• .github/ISSUE_TEMPLATE/*
• .github/PULL_REQUEST_TEMPLATE.md
• docs/
• examples/
• demo/
• assets/
• screenshots/
• 包配置文件，例如 pyproject.toml、package.json、Cargo.toml、go.mod、Dockerfile、docker-compose.yml
• 测试和 CI 工作流
• 现有截图、图表、演示 GIF、视频、落地页、文档页面、发行版本
• 项目是否包含私密信息、雇主拥有的信息、机密信息或不安全内容

如果无法自动读取元数据，请索取信息或输出手动检查清单。

命名依赖

在完成 README 前，请检查名称本身是否传达了预期联想。

如果符合以下任一条件，请使用 github-repo-product-naming：

• 仓库名称听起来像内部文档
• 名称仅表示一个类别，例如 engineering-methods 或 workstation-setup
• 名称太长
• 名称容易引发错误联想
• 名称未能体现产品身份
• 用户想要更“酷”、更好记、更容易走红，或更具开源项目风格的名称
• 仓库属于多仓库生态系统，需要保持命名一致

不要把命名问题藏在 README 里。命名是战略层面的问题。

反向分析得出的发布页模式

优秀的公开仓库通常会在页面顶部附近组合以下内容：

1. Hero 区块

常见模式：

# ProjectName — concrete promise

> Memorable one-line tagline.

[badges]

![screenshot or banner](...)

One short paragraph explaining what it is, who it is for, and the concrete outcome.

优秀的 Hero 区块会明确具体，不会从内部架构讲起。

常见的有效变体：

• 产品／工具页面：名称、风趣的标语、徽章、截图，然后说明具体的实际收益。
• 框架／平台页面：居中显示的 Logo、简短的类别说明、安装命令、生态链接。
• 研究／模型页面：论文／博客／模型卡链接、简明的模型描述、图表、设置说明、模型表格、CLI 和 Python 用法。
• 社区／开发工具页面：Logo、鲜明风格、兼容性、安装命令、手动检查／安全说明。
• 开发者实用工具页面：先展示截图，再列出“为何使用”要点、快速安装、隐私／安全说明和文档链接。

2. 定位段落

使用以下公式：

<Project> is a <category> for <target user> who need to <job-to-be-done>. It helps them <outcome> by <mechanism/differentiator>, while <constraint or trust factor>.

示例：

RepoPilot is a local-first CLI for maintainers who need to triage many GitHub issues quickly. It mirrors issues into SQLite, clusters duplicates, and produces reviewable summaries without sending private repository content to a hosted backend.

ProofStack turns private work evidence into public-safe career signal: resumes, LinkedIn sections, portfolio stories, articles, and interview material that preserve proof without leaking private details.

3. Why 章节

在罗列详尽功能前，先使用 ## Why。

优秀的 “Why” 要点会指出用户遇到的痛点：

## Why

- Stop guessing which command to run first.
- Keep private data local by default.
- Make the happy path copy-pasteable.
- Give maintainers a quick mental model before they read the code.

糟糕的 “Why” 要点则含糊不清：

- Easy to use
- Fast
- AI-powered
- Modern

4. 深入阅读文档前，先提供快速入门

尽可能在 README 前约 100-150 行内提供可运行的快速入门。

快速入门至少应包含：

## Quickstart

```bash
# install
...

# run
...
```

Expected result:

```text
...
```

如果设置过程较复杂，可提供以下内容之一：

• Docker 快速入门
• 托管演示
• GitHub Codespaces
• 示例输入/输出
• 试运行模式
• 如果项目目前尚不可运行，则仅提供截图

5. 截图/演示佐证

至少添加以下内容之一：

• 主视觉截图
• 短 GIF
• CLI 录屏
• 架构图
• 前后对比图
• 示例输出
• 托管演示链接
• 社交媒体预览图

每个视觉素材都需要有用的替代文本。避免添加没有说明作用的装饰性截图。

6. 能力要点

使用 5-7 个要点，每个要点都应说明结果和实现机制：

## Features

- **Local archive** — mirrors issues and PRs into SQLite for offline triage.
- **Duplicate clustering** — groups related reports before maintainers read them manually.
- **Reviewable output** — writes Markdown summaries instead of taking irreversible actions.

除非实现细节会影响用户采用，否则不要列出这些细节。

7. 可信度信息

只添加真实且相关的可信度信息：

• 许可证
• 隐私模型
• 安全模型
• 数据存储位置
• 所需权限
• 限制
• 当前状态：alpha、beta、production、experiment、archived
• 已知风险
• 支持的 OS/Python/Node 版本
• 测试/CI 状态
• 维护者

绝不要伪造星标数、下载量、生产环境用户、赞助商、基准测试结果或从属关系。

8. 后续路径链接

在靠近顶部的位置提供直达链接：

<p align="center">
  <a href="#quickstart">Quickstart</a> ·
  <a href="docs/">Docs</a> ·
  <a href="examples/">Examples</a> ·
  <a href="CHANGELOG.md">Changelog</a> ·
  <a href="CONTRIBUTING.md">Contributing</a>
</p>

推荐的 README 结构

除非仓库类型需要采用其他结构，否则使用此默认结构。

# ProjectName — one-line concrete promise

> Memorable tagline.

[badges]

![Hero screenshot or banner](assets/social-preview.png)

Short positioning paragraph: what it is, who it is for, outcome, differentiator.

<p align="center">
  <a href="#quickstart">Quickstart</a> ·
  <a href="#features">Features</a> ·
  <a href="docs/">Docs</a> ·
  <a href="#contributing">Contributing</a>
</p>

## Why

## Features

## Quickstart

## Demo

## How it works

## Use cases

## Requirements

## Configuration

## Documentation

## Privacy and security

## Roadmap / status

## Contributing

## License

README 变体

产品或应用

适用于发布面向用户的应用的仓库。

顺序：

1. 主视觉图片
2. 一句话说明产品价值
3. 截图
4. 为什么
5. 安装
6. 首次运行步骤
7. 功能
8. 权限/隐私
9. 文档
10. 支持
11. 许可证

框架或库

适用于开发者平台、SDK 或软件包仓库。

顺序：

1. 标志/名称/标语
2. 安装命令
3. 最简代码示例
4. 生态图谱
5. 使用理由
6. API 文档/参考
7. 集成/示例
8. 贡献指南
9. 许可证

研究/模型仓库

适用于模型、论文实现、基准测试或 ML 产物仓库。

顺序：

1. 项目名称
2. 链接：论文、博客、模型卡、演示、数据集
3. 简短摘要
4. 图示/方法
5. 设置
6. 模型/数据表格
7. CLI 用法
8. Python/API 用法
9. 评估/限制
10. 引用
11. 许可证

CLI/开发工具/配置仓库

适用于终端/开发工作流工具的仓库。

顺序：

1. 吸引人但准确的标语
2. 动画演示或截图
3. 安装命令
4. 3 个常用命令
5. 配置
6. 示例
7. 安全/手动检查说明
8. 故障排查
9. 贡献指南

技能/插件仓库

适用于打包 AI Agent 技能、Claude Code 插件、Codex 插件、提示词、命令或可复用指令的仓库。

顺序：

1. 产品名称和具体用途
2. 生态兼容性：Codex、Claude Code、OpenCode、ChatGPT、MCP 等
3. 安装命令
4. 所含技能表格
5. 工作流示例
6. 安全/隐私模型
7. 本地开发设置
8. 贡献和扩展指南

GitHub 元数据检查清单

请在 README.md 之外单独准备这些内容。

仓库名称

仓库名称应根据 github-repo-product-naming 进行选择。

基本要求：

• 简短
• 易于发音
• 易于搜索
• 足够具体，便于记忆
• 除非有必要，否则不要使用 -app、-tool、-repo 等多余后缀
• README、软件包名称、CLI 名称、文档、网站和安装命令中的大小写保持一致

GitHub About 描述

建议长度：70-140 个字符。

公式：

<Category> for <target user> to <outcome> with <differentiator>.

示例：

Local-first GitHub issue triage CLI for maintainers drowning in duplicate reports.

Engineering methods for code, agents, docs, security, reviews, and system architecture.

避免使用：

• “一个简单的工具……”
• “AI 驱动的应用……”
• “此仓库包含……”
• 仅描述实现细节的内容

主页 URL

如果存在以下任意页面，请添加主页：

• 文档站点
• 已部署的应用
• 演示
• 博客文章
• 项目落地页
• 软件包页面

主题

最多使用 20 个主题。主题应使用小写字母、以连字符分隔，并且便于发现。

混合使用以下类型：

• 领域：agentic-ai、developer-tools、workflow-automation
• 语言/框架：python、typescript、swift、langchain
• 产物类型：cli、macos、chrome-extension、github-profile
• 问题：issue-triage、browser-automation、readme-generator
• 受众：maintainers、data-engineering、ai-agents

不要添加无关的热门主题。

社交预览

为仓库创建社交预览图片。

建议：

• 1280 x 640 px
• PNG 或 JPG
• 小于 1 MB
• 项目名称足够大，能在链接预览中清晰辨认
• 一句承诺
• 如有帮助，可添加截图或产品视觉素材
• 使用纯色背景，除非已专门测试透明背景

徽章

谨慎使用徽章。建议优先展示：

• 软件包版本
• 许可证
• CI
• 文档
• 发布
• 支持的平台
• 仅在有意义时展示软件包下载量

不要一开始就放 20 个徽章。

确定性审查检查项

README 文件顶部检查

• 前 5 行内有 H1 标题。
• 前 15 行内有一句话承诺。
• 前 100 个词说明类别、受众、成果和差异化特点。
• 在深入文档之前，至少出现截图、图表、GIF、徽标或示例输出之一。
• 第 150 行之前出现快速入门或安装链接，除非仓库无法运行。
• 不留有“TODO”、“lorem ipsum”、占位徽章或失效的演示链接。

命名检查

• 名称不只是文件夹名或类别名。
• 名称能引发预期联想。
• 名称不会引发更强烈的错误联想。
• 名称带有说明其字面类别的副标题。
• 仓库 slug 使用小写字母、可用于 URL，且便于用于安装命令。
• 如果仓库属于某个生态系统，名称应符合该生态系统的命名风格。
• 如果命名决策并不简单，应提供 github-repo-product-naming 的输出。

必需章节检查

README 至少应包含以下章节或对应链接：

• 为什么 / 动机
• 功能 / 能力
• 快速入门 / 安装
• 用法 / 示例
• 要求
• 文档 / 更多示例
• 状态 / 限制（如果项目尚未成熟）
• 贡献 / 支持
• 许可证

链接和资源检查

• 所有相对链接均可访问。
• 所有图片均可访问。
• 图片替代文本有意义。
• 社交预览图片存在。
• README 未超过 GitHub 的截断限制。
• README 链接到的本地文档均存在。
• 代码片段均带有语言标签。

命令检查

• Shell 命令可直接复制粘贴执行。
• 安装命令与软件包管理器元数据一致。
• 快速入门可在全新克隆的仓库中运行，或清楚说明前置条件。
• 避免使用危险命令，或对其进行说明。
• 命令不应假设存在密钥，除非有 .env.example。

元数据检查

• 描述以成果为导向。
• 如有主页，需设置主页 URL。
• 主题相关、使用小写字母、以连字符分隔，且不超过 20 个。
• 许可证文件存在，并且与 README 中的声明一致。
• 如果仓库希望有人贡献，则需提供问题模板和贡献指南。

声明检查

拒绝或改写以下声明：

• 无法验证的声明
• 夸大的声明
• 涉及雇主机密的声明
• 基于私人指标的声明
• 使用虚假的 star 数、下载量或用户数的声明
• 未经许可暗示存在关联关系的声明

输出格式

应用此技能时，请输出：

1. 诊断：目前哪些问题阻碍了用户采用。
2. 命名和定位：
   • 对当前名称的评估
   • 建议的产品名称
   • 仓库 slug
   • 标语
   • 一句话定位
   • 被否决的名称及原因
3. README：完整的 README.md 或补丁。
4. GitHub 界面设置：
   • About 描述
   • 主页 URL
   • 主题
   • 社交预览建议
5. 需要创建的资源：
   • 截图
   • 横幅/社交预览
   • 演示 GIF
   • 图表
6. 仓库卫生 TODO：
   • 许可证
   • 贡献指南
   • 问题模板
   • 文档
   • 更新日志
   • 安全/隐私
7. 确定性检查清单结果。

语气规则

使用：

• 具体名词
• 可观察的结果
• 简短段落
• 先提供证据，再进行宣传
• 坦诚说明局限
• 通俗易懂的英语
• 可直接复制粘贴的命令

避免：

• “革命性”
• “改变游戏规则”
• 未加说明的“无缝”
• 不说明 AI 执行了什么任务的“AI 驱动”
• 在用户了解项目价值之前就罗列大量架构细节
• 把私人实验说成已可用于生产

Arthur 专属默认定位

对于 Arthur Zakirov 的公开仓库，除非仓库证据另有说明，否则默认采用以下适合公开展示的定位：

Practical data/cloud engineer building small automation systems for high-friction personal and developer workflows.

适合反复强调的主题：

• 数据工程
• 云工作流
• Python 自动化
• 浏览器／任务自动化
• Agent 式 AI 应用
• 个人效率系统
• 开发者工具
• 公开实验室／实用实验

已知的生态方向：

• ProofStack — 职业能力证明与适合公开展示的定位
• AgentDesk — 机器与 AI Agent 工作站设置
• SystemSmith — 面向代码、Agent 和架构的工程方法

除非用户明确提供适合公开展示的证据，否则避免声称项目归私人雇主所有、使用私人公司的代码，或提供生产指标。