repo2skill 使用指南：把 GitHub、GitLab、Gitee 仓库转换成 AI 技能

AI 编程助手能读代码、解释项目、生成调用示例，但面对一个大型开源仓库时，直接把链接丢给它并不总是好用。仓库里可能有大量源码、示例、配置、文档和历史文件，AI 需要先判断项目结构，再提炼安装方式、核心概念、常用命令、接口说明和常见问题。

repo2skill 解决的就是这个整理过程：把一个 GitHub、GitLab 或 Gitee 仓库转换成 OpenCode / Claude Code 可使用的 Skill（技能）。

Skill 可以理解成一份给 AI 编程助手使用的结构化说明书。它通常以 SKILL.md 这类文档形式存在，里面包含项目用途、安装方式、核心 API（应用程序编程接口）、常见任务、代码示例和排错建议。AI 助手加载这个技能后，就能更稳定地回答“这个项目怎么用”“某个功能如何调用”“如何排查安装失败”等问题。

repo2skill 适合解决什么问题

直接阅读一个陌生仓库，通常要做几件事：

1. 看 README，判断项目定位；
2. 浏览目录结构，找入口文件、示例和文档；
3. 理解安装命令、配置项和运行方式；
4. 找 API、CLI（Command Line Interface，命令行接口）或 SDK（Software Development Kit，软件开发工具包）的用法；
5. 整理常见问题和排错步骤。

repo2skill 把这些步骤自动化，让 AI 助手帮你从仓库里提取信息，并生成一个可复用的技能包。

它的核心能力可以概括为：

工作流程

repo2skill 的工作流并不复杂：用户给出仓库地址，AI 助手调用 repo2skill，repo2skill 获取仓库内容并组织上下文，再由 LLM 生成技能文档。

flowchart LR
    A[用户输入仓库地址] --> B[OpenCode / Claude Code 调用 repo2skill]
    B --> C[解析仓库平台与 owner/repo]
    C --> D{仓库平台}
    D -->|GitHub| E[官方 API 与镜像轮换]
    D -->|GitLab| F[GitLab 仓库数据]
    D -->|Gitee| G[Gitee 仓库数据]
    E --> H[提取 README、目录结构、文档]
    F --> H
    G --> H
    H --> I[LLM 分析项目用途与接口]
    I --> J[生成 SKILL.md]
    J --> K[保存到全局或项目技能目录]

这个流程里最重要的是两层转换：

• 仓库内容转换成结构化上下文：把 README、文件树、文档入口等信息提取出来，避免 LLM 在无关文件里浪费上下文。
• 结构化上下文转换成 Skill：把项目信息整理成 AI 助手更容易使用的说明文档，而不是简单复制仓库 README。

安装方式

repo2skill 本身以技能目录的方式使用。拿到 repo2skill 目录后，把它复制到对应的技能路径即可。

OpenCode 全局技能目录

mkdir -p ~/.config/opencode/skills
cp -r repo2skill ~/.config/opencode/skills/

放在全局目录后，OpenCode 在不同项目中都可以使用这个技能。

Claude Code 技能目录

mkdir -p ~/.claude/skills
cp -r repo2skill ~/.claude/skills/

如果主要使用 Claude Code，把目录复制到 ~/.claude/skills 即可。

项目本地技能目录

mkdir -p your-project/.opencode/skills
cp -r repo2skill your-project/.opencode/skills/

项目本地技能适合只在某个工程里使用，不影响全局配置。

三种安装位置的差异如下：

基本使用方式

安装完成后，在 OpenCode 或 Claude Code 中直接用自然语言描述转换需求即可。

帮我把这个仓库转成技能: https://github.com/vercel/next.js

repo2skill 会完成这些动作：

1. 识别仓库地址；
2. 判断仓库来自 GitHub、GitLab 还是 Gitee；
3. 获取 README、文件树、文档等内容；
4. 让 LLM 分析项目的功能、安装方式和常用接口；
5. 生成结构化技能文档；
6. 提示选择保存位置。

生成结果通常是一个技能目录，核心文件是 SKILL.md。OpenCode 或 Claude Code 后续可以加载它，用来回答和该仓库相关的问题。

支持的仓库地址格式

repo2skill 支持常见仓库地址写法，不要求必须带 https://。

GitHub

https://github.com/owner/repo
www.github.com/owner/repo
github.com/owner/repo

GitLab

https://gitlab.com/owner/repo
gitlab.com/owner/repo

Gitee

https://gitee.com/owner/repo
gitee.com/owner/repo

其中 owner 表示用户或组织名，repo 表示仓库名。例如：

https://github.com/vercel/next.js

对应关系是：

生成的技能文档包含什么

repo2skill 的目标不是生成一份很短的摘要，而是生成 AI 助手能直接使用的技能说明。一个完整技能通常会包含这些内容：

对于大型框架仓库，生成内容可能达到数百行；对于小工具库，技能文档会更短，重点集中在安装、API 和示例上。

示例：转换一个框架仓库

以 Next.js 仓库为例：

帮我把这个仓库转成技能: https://github.com/vercel/next.js

这类仓库通常体量较大，repo2skill 会更关注这些信息：

• 项目定位：React 框架、路由、渲染模式、构建工具链；
• 安装与启动方式：创建项目、运行开发服务器、构建生产包；
• 核心概念：页面、路由、服务端渲染、静态生成等；
• 常用命令：开发、构建、测试、Lint；
• 文档入口：官方文档、示例目录、配置说明；
• 常见问题：构建失败、依赖版本、部署相关错误。

生成的 Skill 可以让 AI 助手更稳定地围绕 Next.js 回答问题，而不是每次都重新理解整个仓库。

示例：批量转换多个仓库

repo2skill 支持在一次请求中列出多个仓库。

帮我转换这些仓库:
- https://github.com/anthropics/anthropic-sdk-typescript
- https://gitlab.com/gitlab-org/gitlab
- https://gitee.com/mindspore/docs

批量转换适合下面几种情况：

批量处理时要注意网络质量和仓库体量。大型仓库越多，耗时越长，LLM 上下文消耗也会更明显。

示例：转换小工具库

小型工具库可以这样描述：

帮我把这个工具库转成技能: https://github.com/user/my-utils

这类仓库的技能文档通常重点放在：

• 工具库能做什么；
• 如何安装；
• 暴露了哪些函数或命令；
• 每个函数如何调用；
• 常见输入输出示例；
• 可能的边界情况。

对于小仓库，生成内容不需要很长，关键是让 AI 助手能准确回答“如何调用”和“哪里会出错”。

私有仓库配置

公开仓库可以直接转换。私有仓库需要配置对应平台的 Token，让 repo2skill 有权限读取仓库内容。

GitHub Token

export GITHUB_TOKENS="ghp_xxx,ghp_yyy"

可以配置多个 GitHub Token，用英文逗号分隔。多个 Token 有助于在请求次数受限时轮换使用。

GitLab Token

export GITLAB_TOKENS="glpat_xxx"

Gitee Token

export GITEE_TOKEN="gitee_xxx"

Token 配置建议遵守三个原则：

如果在团队环境中使用，推荐通过 Shell 环境变量、密钥管理工具或 CI/CD（持续集成/持续交付）平台的 Secret 管理能力注入 Token。

适合与不适合的场景

repo2skill 很适合做“仓库到 AI 技能”的初始化整理，但它不是代码审计工具，也不能替代维护者级别的深度理解。

常见问题

需要安装依赖吗？

作为技能使用时，只需要把 repo2skill 目录复制到技能目录，不需要额外执行 npm install 或安装单独工具链。

需要单独提供模型 API key 吗？

不需要为 repo2skill 单独配置模型 API key。它使用你当前 OpenCode 或 Claude Code 已经配置好的 LLM 能力。

技能生成到哪里？

生成过程中会提示选择保存位置。常见位置包括：

~/.config/opencode/skills
~/.claude/skills
your-project/.opencode/skills

选择全局路径，多个项目都能用；选择项目本地路径，技能只跟当前项目绑定。

转换一个仓库大概需要多久？

耗时主要取决于仓库大小、文件数量、网络速度和 LLM 响应速度。

如果 GitHub 访问不稳定，镜像轮换可以提高成功率，但不能保证所有网络环境都完全稳定。

使用时容易踩的坑

1. 不要把生成结果当成绝对准确

repo2skill 会基于仓库内容和 LLM 分析生成技能文档。LLM 可能会漏掉细节，也可能对复杂代码路径理解不完整。用于生产接入前，关键命令、API 参数和配置项都应该回到仓库文档或源码中确认。

2. 大仓库要关注上下文取舍

大型仓库文件很多，不可能把所有内容完整塞进 LLM 上下文。repo2skill 会优先处理 README、文档入口和目录结构，但某些边缘模块可能覆盖不到。遇到复杂项目，可以先生成基础 Skill，再针对特定模块补充说明。

3. 私有仓库 Token 要控制权限

Token 只用于读取仓库时，权限不要给得过大。尤其不要使用带有写权限或管理员权限的长期令牌。

4. 批量转换要控制数量

一次列太多大型仓库，可能导致等待时间变长，也更容易遇到网络失败或请求限制。更稳妥的方式是按项目类型分批转换。

项目地址

https://github.com/zhangyanxs/repo2skill/tree/main

repo2skill 的价值在于把“理解仓库”这件事变成一个可复用流程：一次转换，后续就能让 OpenCode 或 Claude Code 反复使用同一份技能上下文。对于经常研究开源项目、接入第三方 SDK、整理团队工具知识的人来说，它可以减少大量重复阅读和手动归纳工作。