github-reader

一个 AI Skill：快速查阅任意 GitHub 仓库 -- 概览、完整目录树、源码文件、README、子目录，全部通过 GitHub REST API 按需读取，不依赖 github.com 网页。

支持 Claude Code、Codex、OpenCode

特性

• 一次 API 调用拿到整个仓库的完整文件树（500+ 文件也只要 1 次请求）
• 三条通道按优先级自动切换：api.github.com -> raw.githubusercontent.com -> codeload
• 单文件原文直读，带语法标注，支持 blob URL / 行号定位（#L10-L20）
• 只记仓库名不记得作者时，自动走搜索 API 定位
• 配额感知：匿名 60 次/小时，检测到 GITHUB_TOKEN 环境变量自动提升到 5000 次/小时
• 大文件、二进制、LFS、截断目录树等边界情况都有对应处理方案
• 渐进式加载：SKILL.md 只保留通道/URL 解析/配额等通用层，四种问法（快速理解 / 浏览文件 / 功能深挖 / 故障排查）的详细工作流与案例放在 references/ 按需读取
• 固定传输脚本：node scripts/gh-api.js 统一 API/raw/codeload 的鉴权、超时、重试、状态码和 URL 参数处理
• 跨平台落盘：返回响应的命令支持 --output PATH，由 Node 直接写 UTF-8/原始字节，避免 PowerShell 重定向编码问题

工作流设计

重复的只读网络请求优先使用 skill 安装目录下的 node scripts/gh-api.js（不是用户仓库的相对路径），例如：

node scripts/gh-api.js repo ollama/ollama
node scripts/gh-api.js tree shareAI-lab/learn-claude-code --top --paths
node scripts/gh-api.js raw shareAI-lab/learn-claude-code agents/s02_tool_use.py
node scripts/gh-api.js search 'local llm stars:>1000' --sort stars --per-page 5 --format tsv --output results.tsv

tree / raw / readme 的 REF 分支参数可省略（自动解析默认分支），不要为拿 default_branch 而额外发一次 repo 请求。

search / trending 默认输出 GitHub 原始 JSON；使用 --format tsv 可直接得到候选项目摘要。所有会返回响应的命令都支持 --output PATH，由 Node 直接写文件，不经过 shell 的文本编码转换。codeload --extract 会直接写入解包目录，不能与 --output 同时使用。

脚本只负责可靠传输，回答结构仍按对应 references/*.md 选择；快速理解不因为脚本存在而额外拉目录树。

场景一：概览与文件读取

解析 URL（owner / repo / branch / path）
    ↓
仓库概览（1 次请求：描述、stars、语言、默认分支）
    ↓
完整目录树（1 次请求：git/trees?recursive=1）
    ↓
按用户问题选择性读文件（raw 通道）
    ↓
展示：树形结构 + 关键源码 + 出处路径

场景二：查某个功能/机制的实现逻辑

功能词定位（中英转换 + 目录树 grep + docs 对照）
    ↓
文件名对不上时：codeload 快照拉到本地全文 grep（1 次请求）
    ↓
精读核心文件（入口 / 数据结构 / 调用链）
    ↓
回答：一句话概括 + 拆解 + 关键代码摘录

核心技巧是 git/trees/{branch}?recursive=1：一个请求返回全部文件路径， 配合 grep 过滤，避免逐目录请求浪费配额。

触发方式

在支持 skill 的 AI 编程助手中说以下任意一种：

• "看看这个仓库"
• "读一下这个 repo 的源码"
• "这个仓库结构是什么"
• "帮我分析 github.com/xxx/yyy"
• "read this repo"

或直接粘贴任何 GitHub 链接。

前置依赖

只需要 Node（用 npx 安装本 skill 本身就需要它）：传输脚本是 scripts/gh-api.js，macOS/Linux/Windows 任意 shell（cmd、PowerShell、bash）都能直接跑，不依赖 bash/curl/jq/tar。搜索和 trending 支持 --format tsv，目录树支持 --paths、--match、--ext、--top，返回响应的命令支持 --output PATH。Windows PowerShell 5.1 不要使用 > 或 Out-File 保存脚本输出，它们默认会写成 UTF-16 LE；请使用 --output PATH，例如 node scripts/gh-api.js search "local llm" --format tsv --output results.tsv。Unix 示例中的 jq、sed、head 和 /tmp 仅是可选的本地处理方式，不是运行依赖。

安装

推荐：npx 一行命令

npx github-reader-skill

自动检测并安装到 Claude Code、Codex、OpenCode。

管理命令

npx github-reader-skill --list            # 查看所有已安装的 skill
npx github-reader-skill --status          # 查看当前 skill 安装状态
npx github-reader-skill --uninstall       # 从所有 agent 卸载
npx github-reader-skill --agent claude    # 只安装到 Claude Code
npx github-reader-skill --agent codex     # 只安装到 Codex

可选：配置 GITHUB_TOKEN

匿名访问即可使用（尝鲜零配置）：核心配额 60 次/小时，且 README 与源码读取走 raw CDN 不占核心配额，一般每个仓库只消耗 1~2 次核心请求。不够用时再配置 token：创建一个免费的 GitHub Personal Access Token（不需要任何权限勾选，public repo 只读即可），在你平时工作的项目根目录（启动 agent 的地方，不是 skill 的目录）创建 key.bash：

# key.bash
export GITHUB_TOKEN='粘贴你自己的 github access-tokens'

echo 'key.bash' >> .gitignore
source ./key.bash

然后在同一个 shell 中启动 agent。skill 会自动使用 token，core 配额通常提升 至 5000 次/小时。不要提交或打印 key.bash；Search API 仍有独立限制。

输出示例

learn-claude-code (shareAI-lab)
描述: Bash is all you need - A nano claude code-like agent harness, built from 0 to 1
Stars: 75.3k | 语言: Python | 默认分支: main

代码结构（17 个递进阶段）:
├── s01_agent_loop/      # agent 主循环
├── s02_tool_use/        # 工具调用与分发
├── ...
└── s17_goal_loop/       # 目标循环

agents/s02_tool_use.py 核心逻辑:
    def run_bash(command: str) -> str:
        ...危险命令拦截 + subprocess 执行...

开发

本仓库的开发与调试流程（普通用户用上面的 npx 安装即可，无需 clone 源码）：

git clone https://github.com/dave-wind/github-reader-skill.git
cd github-reader-skill
node install.js           # 安装/更新到本机所有 agent
node install.js --status  # 查看安装状态

改动 SKILL.md、references/、scripts/ 后重新执行 node install.js 同步。evals/ 保存历次评测数据，随仓库提交，用于回归对比。本地 key.bash（如存在）不会被复制到 agent 目录。

License

MIT