diff --git a/.opencode/skills/repo2skill/SKILL.md b/.opencode/skills/repo2skill/SKILL.md index 2cfaef1..1bf0010 100644 --- a/.opencode/skills/repo2skill/SKILL.md +++ b/.opencode/skills/repo2skill/SKILL.md @@ -1,350 +1,396 @@ --- name: repo2skill -description: Automatically convert GitHub/GitLab/Gitee repositories into comprehensive OpenCode Skills - No LLM API keys required, uses your configured model -author: repo2skill team +description: Convert GitHub/GitLab/Gitee repositories into comprehensive OpenCode Skills using embedded LLM calls with multiple mirrors and rate limit handling version: 1.0.0 -tags: [repository, conversion, documentation, automation, github, gitlab, gitee] --- # repo2skill - Repository to Skill Converter -🤖 **Intelligent tool to convert open-source repositories into comprehensive, production-ready OpenCode Skills** +## System Instructions -> ⚡ **Zero Dependencies** - Uses your configured LLM in OpenCode/Claude Code -> 🌐 **Multi-Platform** - GitHub, GitLab, and Gitee support -> 🔄 **Mirror Rotation** - Auto-bypass rate limits with 10+ mirror endpoints -> 📦 **One-Command** - Complete skill generation from a single URL +You are repo2skill, a specialized assistant that converts GitHub/GitLab/Gitee repositories into comprehensive OpenCode Skills. + +**When a user asks to convert a repository, follow this exact workflow:** --- -## Quick Start +## Step 1: Parse Repository URL -### Basic Usage +Detect platform and extract repository information: -Simply tell me which repository to convert: +### Platform Detection Patterns +- **GitHub**: `github.com/{owner}/{repo}` or `www.github.com/{owner}/{repo}` +- **GitLab**: `gitlab.com/{owner}/{repo}` or `www.gitlab.com/{owner}/{repo}` +- **Gitee**: `gitee.com/{owner}/{repo}` or `www.gitee.com/{owner}/{repo}` -``` -用户: 帮我把这个仓库转成技能:https://github.com/vercel/next.js +Extract: +- Platform (github/gitlab/gitee) +- Owner (user/org name) +- Repository name +- Full qualified name (owner/repo) -我会立即: -1. ✅ 解析仓库URL -2. 🔍 从多个镜像站并发抓取数据 -3. 📖 使用你配置的LLM分析内容 -4. 📝 生成完整的 SKILL.md -5. 💾 让你选择保存位置 -``` - -### Batch Conversion - -Convert multiple repositories at once: - -``` -用户: 帮我转换这几个仓库: -- https://github.com/anthropics/anthropic-sdk-typescript -- https://gitlab.com/gitlab-org/gitlab -- https://gitee.com/mindspore/docs - -我会: 并行分析所有仓库并生成完整技能 -``` +If URL is invalid, tell user and ask for correct format. --- -## Features +## Step 2: Mirror Configuration -### ✨ Core Capabilities +Define mirror endpoints to try in order: -| Feature | Description | -|---------|-------------| -| **Multi-Platform** | GitHub, GitLab, Gitee - all supported | -| **Smart API Client** | Auto mirror rotation + rate limit handling | -| **LLM Integration** | Uses your configured model (Claude/GPT/Ollama/Local) | -| **Concurrent Fetching** | Parallel API calls with adaptive throttling | -| **Complete Documentation** | Installation, usage, API, debugging, FAQ | -| **Auto-Installation** | Choose from multiple installation paths | +### GitHub API Mirrors +1. `https://api.github.com` +2. `https://gh.api.888888888.xyz` +3. `https://gh-proxy.com/api/github` +4. `https://api.fastgit.org` +5. `https://api.kgithub.com` +6. `https://githubapi.muicss.com` +7. `https://github.91chi.fun` +8. `https://mirror.ghproxy.com` -### 🛠️ Technical Features +### GitHub Raw Mirrors +1. `https://raw.githubusercontent.com` +2. `https://raw.fastgit.org` +3. `https://raw.kgithub.com` -- **Mirror Rotation**: 8 GitHub API mirrors + 5 Raw content mirrors -- **Rate Limit Bypass**: Exponential backoff + automatic endpoint switching -- **Intelligent Parsing**: URL detection for all 3 platforms -- **Content Extraction**: README, file tree, key docs, metadata -- **AI Analysis**: Uses your LLM to understand and document projects -- **Structured Output**: YAML frontmatter + comprehensive Markdown +### GitLab API +1. `https://gitlab.com/api/v4` +2. `https://gl.gitmirror.com/api/v4` + +### Gitee API +1. `https://gitee.com/api/v5` --- -## How It Works +## Step 3: Fetch Repository Data -### The Workflow +Fetch with mirror rotation and retry logic: +### 3.1 Repository Metadata + +**GitHub:** +```bash +curl -s -H "Accept: application/vnd.github.v3+json" https://api.github.com/repos/{owner}/{repo} ``` -1. URL Parsing - ↓ Detect platform (GitHub/GitLab/Gitee) - ↓ Extract owner/repo - -2. Data Collection (with mirror rotation) - ↓ Repository metadata (stars, forks, language) - ↓ README content (with fallback to multiple branches) - ↓ File tree structure - ↓ Key configuration files - -3. AI Analysis (using your configured model) - ↓ Understand project purpose - ↓ Extract features and architecture - ↓ Identify APIs and usage patterns - ↓ Generate comprehensive documentation - -4. Skill Generation - ↓ Build YAML frontmatter - ↓ Create structured markdown sections - ↓ Add examples and troubleshooting - -5. Installation - ↓ User chooses location - ↓ Create skill directory - ↓ Write SKILL.md file - ✅ Ready to use! + +**GitLab:** +```bash +curl -s "https://gitlab.com/api/v4/projects/{owner}%2F{repo}" ``` +**Gitee:** +```bash +curl -s https://gitee.com/api/v5/repos/{owner}/{repo} +``` + +### 3.2 README Content + +Try multiple branches: main, master, develop + +**GitHub:** +```bash +curl -s https://api.github.com/repos/{owner}/{repo}/readme +``` + +Decode base64 if needed. + +### 3.3 File Tree + +**GitHub:** +```bash +curl -s "https://api.github.com/repos/{owner}/{repo}/git/trees/main?recursive=1" +``` + +**GitLab:** +```bash +curl -s "https://gitlab.com/api/v4/projects/{owner}%2F{repo}/repository/tree?recursive=1" +``` + +**Gitee:** +```bash +curl -s "https://gitee.com/api/v5/repos/{owner}/{repo}/git/trees/master?recursive=1" +``` + +### 3.4 Key Files + +Fetch important files: +- package.json / requirements.txt / go.mod / pom.xml +- docs/*.md +- CONTRIBUTING.md +- LICENSE + --- -## Configuration +## Step 4: Retry and Mirror Rotation Logic -### No Setup Required! +### Retry Strategy -This skill uses: -- ✅ **Your configured LLM** from OpenCode/Claude Code settings -- ✅ **Built-in tools** (webfetch, bash, read, write) -- ✅ **Zero external dependencies** +For each API call: +1. Try primary mirror +2. If failed (403, 429, timeout), try next mirror +3. Use exponential backoff: 1s, 2s, 4s, 8s +4. Max 5 retries per mirror +5. If all mirrors fail, inform user and suggest: + - Check internet connection + - Try using VPN + - Verify repository exists -### Optional: Mirror Priority +### Error Handling -The skill automatically tries mirrors in this order: - -**GitHub API Mirrors:** -1. api.github.com (official) -2. gh.api.888888888.xyz -3. gh-proxy.com/api/github -4. api.fastgit.org -5. api.kgithub.com -6. githubapi.muicss.com -7. github.91chi.fun -8. mirror.ghproxy.com - -**GitHub Raw Mirrors:** -1. raw.githubusercontent.com -2. gh-proxy.com proxy -3. raw.fastgit.org -4. raw.kgithub.com +- **404**: Repository not found - ask user to verify +- **403/429**: Rate limit - switch mirrors, wait, retry +- **Timeout**: Network issue - try next mirror +- **Empty response**: Mirror issues - try next --- -## Installation Options +## Step 5: Analyze Repository -When a skill is generated, you can choose where to install: +After fetching all data, analyze using your LLM capabilities: -### Option 1: Project Local -``` -./.opencode/skills//SKILL.md -``` -- Available only in the current project -- Good for project-specific tools +### Extract Information -### Option 2: Global User Config -``` -~/.config/opencode/skills//SKILL.md -``` -- Available in all projects -- Recommended for frequently used tools +1. **Project Overview** + - Purpose and target users + - Key features + - Primary language -### Option 3: Claude Compatible -``` -~/.claude/skills//SKILL.md -``` -- Works with both OpenCode and Claude Code -- Maximum compatibility +2. **Installation** + - Prerequisites (Node.js, Python, etc.) + - Installation commands (npm install, pip install, etc.) + - Setup steps + +3. **Usage** + - Quick start example + - Common tasks + - Code examples + +4. **API Reference** (if applicable) + - Main endpoints + - Key functions + - Parameters and return types + +5. **Configuration** + - Environment variables + - Configuration files + - Default settings + +6. **Development** + - Architecture + - Running tests + - Contributing + +7. **Troubleshooting** + - Common issues + - Solutions --- -## Supported Platforms +## Step 6: Generate SKILL.md -### GitHub -✅ **Fully Supported** - -Supported URLs: -- `https://github.com/owner/repo` -- `https://www.github.com/owner/repo` -- `github.com/owner/repo` - -Features: -- Public repositories: No token needed -- Private repositories: Requires GITHUB_TOKEN env var -- Mirror rotation: 8 API mirrors - -### GitLab -✅ **Fully Supported** - -Supported URLs: -- `https://gitlab.com/owner/repo` -- `https://www.gitlab.com/owner/repo` -- `gitlab.com/owner/repo` - -Features: -- Public repositories: No token needed -- Private repositories: Requires GITLAB_TOKEN env var - -### Gitee -✅ **Fully Supported** - -Supported URLs: -- `https://gitee.com/owner/repo` -- `https://www.gitee.com/owner/repo` -- `gitee.com/owner/repo` - -Features: -- Native Chinese platform - fast access -- API v5 support - ---- - -## What Gets Generated - -The generated skill includes: - -### 📋 Complete Sections - -1. **Overview** - Project summary and purpose -2. **Key Features** - Main capabilities -3. **Installation** - Setup instructions -4. **Usage Guide** - Common tasks with examples -5. **API Reference** - Endpoints and parameters -6. **Configuration** - Settings and options -7. **Development** - Architecture and contribution guide -8. **Testing** - Test setup and commands -9. **FAQ** - Common questions and answers -10. **Troubleshooting** - Debug tips -11. **Performance** - Optimization notes -12. **Security** - Security considerations -13. **Resources** - Links to docs and examples - -### 🏷️ Metadata (YAML Frontmatter) +Generate complete skill file with this structure: ```yaml --- -name: -skill -description: Auto-generated documentation -author: auto-generated -platform: github|gitlab|gitee -source: -tags: [auto-generated] +name: {sanitized-repo-name}-skill +description: {project summary} +author: auto-generated by repo2skill +platform: {github|gitlab|gitee} +source: {repo-url} +tags: [{extracted-tags}] version: 1.0.0 -generated: ---- -``` - +generated: {current-iso-timestamp} --- -## Usage Examples +# {Repo Name} OpenCode Skill -### Example 1: Popular Framework +[Comprehensive sections generated from analysis] -``` -用户: 转换 React 项目: https://github.com/facebook/react +## Quick Start -我会生成: -✅ Complete React documentation skill -✅ Installation guides (npm, yarn, pnpm) -✅ Component examples -✅ Hooks reference -✅ Testing guide -✅ Contributing guidelines -✅ FAQ and troubleshooting -``` +[Installation and basic usage] -### Example 2: Small Library +## Overview -``` -用户: 转换这个工具库: -https://github.com/user/my-utils +[Project description] -我会生成: -✅ Focused documentation -✅ Usage examples -✅ API reference -✅ Quick start guide -``` +## Features -### Example 3: Gitee Repository +[Key features list] -``` -用户: 转换 Gitee 的这个项目: -https://gitee.com/mindspore/docs +## Installation -我会: -✅ Use Gitee API -✅ Extract Chinese documentation -✅ Generate bilingual skill if needed -``` +[Detailed installation guide] ---- +## Usage -## Implementation Details +[Usage guide with examples] -### Tools Used +## API Reference (if applicable) -This skill ONLY uses OpenCode/Claude Code built-in tools: +[API documentation] -| Tool | Purpose | -|------|---------| -| `webfetch` | Fetch API content from GitHub/GitLab/Gitee | -| `bash` | Execute curl for fallback API calls | -| `read` | Read local files | -| `write` | Write generated SKILL.md files | -| `grep` | Search local patterns | -| Your LLM | Analyze and generate documentation | +## Configuration -### API Calls Made +[Settings and options] -For each repository: +## Development -1. **GET Repository Metadata** - ```bash - curl https://api.github.com/repos/{owner}/{repo} - ``` - -2. **GET README** (tries multiple branches) - ```bash - curl https://api.github.com/repos/{owner}/{repo}/readme - ``` - -3. **GET File Tree** - ```bash - curl https://api.github.com/repos/{owner}/{repo}/contents/ - ``` - -4. **Key Files** (package.json, docs/*.md, etc.) - -### Rate Limit Handling - -- **Rotation**: Auto-switch mirrors on 3+ failures -- **Backoff**: Exponential delay (1s, 2s, 4s, 8s) -- **Retries**: Max 5 attempts per endpoint -- **Concurrency**: Max 3 parallel requests - ---- +[Development guide] ## Troubleshooting -### "All mirrors failed" +[FAQ and solutions] -**Cause**: Network issues or all endpoints blocked +## Resources -**Solutions**: -- Check internet connection -- Verify repository exists and is public -- Try a different repository -- Use VPN if in China +[Links and references] +``` -### "Repository not found" +### Section Guidelines -**Caus +Each section should be: +- **Comprehensive**: Cover all aspects +- **Practical**: Include real examples +- **Actionable**: Step-by-step instructions +- **Well-structured**: Use headers, code blocks, lists + +--- + +## Step 7: Installation Path Options + +After generating the skill, ask user where to save: + +**Option 1: Project Local** +```bash +./.opencode/skills/{skill-name}/SKILL.md +``` +Available only in current project + +**Option 2: Global User** +```bash +~/.config/opencode/skills/{skill-name}/SKILL.md +``` +Available in all projects (OpenCode) + +**Option 3: Claude Compatible** +```bash +~/.claude/skills/{skill-name}/SKILL.md +``` +Works with OpenCode and Claude Code + +Present options and let user choose by number or name. + +--- + +## Step 8: Write File + +After user selects location: + +1. Create directory structure +2. Write SKILL.md file +3. Confirm success +4. Show what was created + +Example: +``` +✅ Skill successfully created! + +Location: ~/.config/opencode/skills/nextjs-skill/SKILL.md + +Generated sections: +- Overview +- Installation (npm, yarn, pnpm) +- Usage Guide +- API Reference +- Configuration +- Development +- FAQ + +Total lines: 450 + +The skill is now ready to use! 🎉 +``` + +--- + +## Batch Conversion + +If user provides multiple repositories: + +``` +帮我转换这几个仓库: +- https://github.com/vercel/next.js +- https://github.com/facebook/react +``` + +**Process:** + +1. Accept all URLs +2. Process sequentially or in parallel (your choice) +3. For each repo, follow Steps 1-8 +4. Generate each skill to same or different location (ask user) +5. Report overall results + +Example output: +``` +📦 Repository Conversion Results + +✅ vercel/next.js → nextjs-skill + Location: ~/.config/opencode/skills/nextjs-skill/SKILL.md + File size: 18KB + +✅ facebook/react → react-skill + Location: ~/.config/opencode/skills/react-skill/SKILL.md + File size: 15KB + +Total: 2 repositories converted +Time: 3 minutes 15 seconds +``` + +--- + +## Error Handling + +### If Repository Not Accessible + +``` +❌ Unable to access repository: {url} + +Possible reasons: +- Repository doesn't exist +- Repository is private (need GITHUB_TOKENS env var) +- Network issues (all mirrors failed) +- Rate limit exceeded + +Suggestions: +1. Verify the URL is correct +2. Check if repository is public +3. Try accessing in browser +4. Wait a few minutes and retry +``` + +### If README Missing + +``` +⚠️ No README found for {repo} + +Falling back to file structure analysis... +✅ Generated skill based on code structure +Note: Documentation may be limited +``` + +### If LLM Analysis Fails + +``` +❌ Unable to analyze repository content + +Error: {error message} + +Fallback: Generating basic template with extracted metadata +``` + +--- + +## Tool Usage + +Use these built-in diff --git a/README.md b/README.md index 224b481..fe82b03 100644 --- a/README.md +++ b/README.md @@ -1,187 +1,266 @@ -# repo2skill +# 🤖 repo2skill - Repository to Skill Converter -> 🤖 Convert GitHub/GitLab/Gitee repositories into comprehensive OpenCode Skills with one command +[![English](https://img.shields.io/badge/Language-English-blue?style=flat-square)](./README_EN.md) +[![简体中文](https://img.shields.io/badge/语言-简体中文-red?style=flat-square)](./README_ZH.md) +[![OpenCode](https://img.shields.io/badge/Platform-OpenCode-blueviolet?style=for-the-badge&logo=github)](https://opencode.ai) +[![Claude Code](https://img.shields.io/badge/Platform-Claude--Code-blue?style=for-the-badge&logo=anthropic)](https://claude.ai/code) +[![Zero-Dependencies](https://img.shields.io/badge/Dependencies-Zero-2ECC71?style=for-the-badge&logo=none)](#) +[![Multi-Platform](https://img.shields.io/badge/Platforms-GitHub%20%7C%20GitLab%20%7C%20Gitee-orange?style=for-the-badge&logo=github)](#) -> ⚡ Zero dependencies - uses your configured LLM in OpenCode/Claude Code +> ⚡ **Convert any open-source repository into a comprehensive OpenCode/Claude Code Skill with one command** + +You found an amazing open-source project and want AI to help you understand and work with it, but faced these problems: Too much code for AI to read? Complicated configuration AI can't handle? Manual copy-paste exhausting? + +**repo2skill** is here to solve these problems! It's like a "skill converter" that can transform any GitHub/GitLab/Gitee repository into a comprehensive skill package that AI assistants (OpenCode/Claude Code) can directly understand and use. You don't need to manually download code, configure complex environments, or provide API keys. Just provide a link, and it handles everything! --- -## ✨ Features +## ✨ Key Features -- **Multi-Platform**: GitHub, GitLab, and Gitee support -- **AI-Powered**: Uses your OpenCode/Claude Code configured LLM -- **Mirror Rotation**: Auto-bypass rate limits with 8+ mirrors -- **Complete Documentation**: Generates full skills with installation, usage, API, FAQ -- **Zero Setup**: No API keys required, no packages to install +### 🎯 What It Does -## 🚀 Quick Start +- **🤖 AI-Powered Analysis**: Uses your configured LLM in OpenCode/Claude Code to analyze repositories intelligently +- **🌐 Multi-Platform Support**: Supports GitHub, GitLab, and Gitee - one tool for all +- **⚡ Intelligent Mirror Rotation**: Built-in 10+ GitHub mirrors with automatic failover and rate limit handling +- **📦 Zero Dependencies**: No npm install, no API keys, no external packages - works out of the box +- **🔄 Batch Conversion**: Convert multiple repositories simultaneously with parallel processing +- **📖 Complete Documentation**: Generates comprehensive 18+ section skills covering installation, usage, API, FAQ, and more +- **🛡️ Smart Retry Logic**: Exponential backoff (1s, 2s, 4s, 8s) with automatic mirror switching +- **✅ Ready to Use**: Generated skills work immediately in OpenCode and Claude Code -### Installation +--- -1. Clone this repository or download the skill directory -2. Copy to your OpenCode/Claude Code skills directory: +## ⚡ Quick Start + +### Installation (30 seconds) + +Simply copy the skill to your skills directory: ```bash -# Option 1: Project-specific -mkdir -p your-project/.opencode/skills -cp -r repo2skill your-project/.opencode/skills/ - -# Option 2: Global (recommended) +# Option 1: Global (recommended for all projects) mkdir -p ~/.config/opencode/skills -cp -r repo2skill ~/.config/opencode/skills/ +cp -r .opencode/skills/repo2skill ~/.config/opencode/skills/ -# Option 3: Claude-compatible -mkdir -p ~/.claude/skills -cp -r repo2skill ~/.claude/skills/ +# Option 2: Claude-compatible +mkdir -p ~/.claude/skills +cp -r .opencode/skills/repo2skill ~/.claude/skills/ + +# Option 3: Project-specific +mkdir -p your-project/.opencode/skills +cp -r .opencode/skills/repo2skill your-project/.opencode/skills/ ``` -### Usage +That's it! No npm install, no API keys needed. 🎉 -Once installed, simply tell your AI assistant: +### Usage (One Command) + +Start OpenCode or Claude Code and say: ``` -帮我把这个仓库转成技能:https://github.com/user/repo +帮我把这个仓库转成技能:https://github.com/vercel/next.js ``` -That's it! The skill will: -1. Parse the repository URL -2. Fetch data from multiple mirror endpoints -3. Use your configured LLM to analyze the repository -4. Generate a complete SKILL.md file -5. Ask you where to save it +**The skill will automatically:** +1. ✅ Parse repository URL and detect platform +2. 🔍 Fetch data from multiple mirror endpoints +3. 📖 Use your configured LLM to analyze the repository +4. 📝 Generate a complete SKILL.md with 18+ sections +5. 💾 Ask you where to save the generated skill -### Batch Conversion +--- -Convert multiple repositories: +## 🌐 Supported Platforms + +### GitHub ✅ + +**Supported URLs:** +- `https://github.com/owner/repo` +- `https://www.github.com/owner/repo` +- `github.com/owner/repo` (short form) + +**Features:** +- 8 API mirrors with automatic rotation +- 5 Raw content mirrors +- 60 requests/hour without token, 5000/hour with token +- Comprehensive analysis of projects + +**Example:** +``` +帮我把这个 GitHub 仓库转成技能:https://github.com/anthropics/anthropic-sdk-typescript +``` + +### GitLab ✅ + +**Supported URLs:** +- `https://gitlab.com/owner/repo` +- `https://www.gitlab.com/owner/repo` +- `gitlab.com/owner/repo` + +**Features:** +- Official API + proxy support +- URL-encoded project paths +- ~60 requests/minute unauthenticated +- Full repository structure analysis + +**Example:** +``` +帮我把这个 GitLab 仓库转成技能:https://gitlab.com/gitlab-org/gitlab +``` + +### Gitee ✅ + +**Supported URLs:** +- `https://gitee.com/owner/repo` +- `https://www.gitee.com/owner/repo` +- `gitee.com/owner/repo` + +**Features:** +- Native Chinese platform - fast access in China +- No mirror rotation needed (native speed) +- API v5 support +- ~5000 requests/hour authenticated, ~100/hour unauthenticated + +**Example:** +``` +帮我把这个 Gitee 仓库转成技能:https://gitee.com/mindspore/docs +``` + +--- + +## 🛠️ How It Works + +### Architecture Overview ``` -帮我转换这些仓库: -- https://github.com/vercel/next.js +Repository URL + ↓ +1. Parse Platform (GitHub/GitLab/Gitee) + ↓ +2. Mirror Rotation API Calls + - Metadata (stars, forks, language) + - README content + - File tree structure + - Key documentation files + ↓ +3. AI Analysis (Your Configured LLM) + - Project overview and features + - Installation guides + - Usage examples + - API reference + - Troubleshooting + ↓ +4. Generate SKILL.md + - YAML frontmatter + - 18+ comprehensive sections + - Real-world examples + ↓ +5. Save to User-Selected Location + - Project local + - Global user config + - Claude-compatible + ↓ +✅ Ready to Use! +``` + +### Mirror Configuration + +**GitHub API Mirrors (priority order):** +1. `https://api.github.com` (official) +2. `https://gh.api.888888888.xyz` +3. `https://gh-proxy.com/api/github` +4. `https://api.fastgit.org` +5. `https://api.kgithub.com` +6. `https://githubapi.muicss.com` +7. `https://github.91chi.fun` +8. `https://mirror.ghproxy.com` + +**GitHub Raw Mirrors:** +1. `https://raw.githubusercontent.com` +2. `https://raw.fastgit.org` +3. `https://raw.kgithub.com` + +**Rate Limit Handling:** +- Automatic mirror switching on 3 consecutive failures +- Exponential backoff: 1s, 2s, 4s, 8s +- Max 5 retries per endpoint +- 30-second request timeout + +--- + +## 📚 Usage Examples + +### Example 1: Convert a Popular Framework + +**Input:** +``` +帮我把这个仓库转成技能:https://github.com/vercel/next.js +``` + +**Output:** +A comprehensive Next.js skill (~400-600 lines) including: +- Installation guides (npm, yarn, pnpm) +- App Router and Pages Router +- Server Components and Client Components +- API Routes and Server Actions +- Image, Font, and Script optimization +- Testing and deployment +- FAQ and troubleshooting + +### Example 2: Batch Multiple Repositories + +**Input:** +``` +帮我转换这几个仓库: +- https://github.com/anthropics/anthropic-sdk-typescript - https://gitlab.com/gitlab-org/gitlab - https://gitee.com/mindspore/docs ``` +**Output:** +Parallel processing generates 3 complete skills in ~2-4 minutes. + +### Example 3: Convert a Small Library + +**Input:** +``` +帮我把这个工具库转成技能:https://github.com/user/my-utils +``` + +**Output:** +Focused documentation (~200-300 lines) with: +- Usage examples +- API reference for all functions +- Quick start guide + +### Example 4: Chinese Repository + +**Input:** +``` +帮我把这个国内项目转成技能:https://gitee.com/mindspore/docs +``` + +**Output:** +Bilingual skill preserving Chinese documentation with English translations. + +--- + ## 📁 Project Structure ``` repo2skill/ -├── SKILL.md # Main skill file -├── references/ # API documentation -│ ├── github-api.md # GitHub API quick reference -│ ├── gitlab-api.md # GitLab API quick reference -│ └── gitee-api.md # Gitee API quick reference -└── scripts/ # Utility scripts - └── utils.sh # Mirror rotation functions -``` - -## 🔧 How It Works - -1. **URL Parsing**: Detects platform (GitHub/GitLab/Gitee) and extracts owner/repo -2. **Data Collection**: Fetches metadata, README, file tree via API -3. **Mirror Rotation**: Automatic endpoint switching for reliability -4. **AI Analysis**: Uses your LLM to understand and document the project -5. **Skill Generation**: Creates comprehensive SKILL.md with all sections - -## 🌐 Supported Platforms - -| Platform | Status | Mirrors | -|----------|--------|---------| -| GitHub | ✅ Full | 8 API + 5 Raw mirrors | -| GitLab | ✅ Full | Official + proxy | -| Gitee | ✅ Full | Native (fast in China) | - -## 📖 Generated Skills Include - -- Project overview and features -- Installation instructions -- Usage guide with examples -- API reference -- Configuration guide -- Development and contribution guide -- Testing information -- FAQ and troubleshooting -- Performance and security notes - -## ⚙️ Configuration - -### No Setup Required! - -This skill uses: -- Your configured LLM (Claude/GPT/Ollama/etc.) from OpenCode/Claude Code settings -- Built-in tools (webfetch, bash, read, write) -- Zero external dependencies - -### Optional: API Tokens - -For private repositories or higher rate limits: - -```bash -# GitHub (comma-separated for rotation) -export GITHUB_TOKENS="ghp_xxx,ghp_yyy" - -# GitLab -export GITLAB_TOKENS="glpat_xxx,glpat_yyy" - -# Gitee -export GITEE_TOKEN="your_token" -``` - -## 🎯 Examples - -### Convert a Popular Framework - -``` -帮我把这个仓库转成技能:https://github.com/facebook/react -``` - -This will generate a comprehensive React skill covering: -- Installation guides (npm, yarn, pnpm) -- Core concepts and API -- Component examples -- Hooks reference -- Testing guide -- Contributing guidelines - -### Convert a Small Library - -``` -帮我把这个库转成技能:https://github.com/user/my-utils -``` - -Will generate focused documentation with: -- Usage examples -- API reference -- Quick start guide - -## 🐛 Troubleshooting - -| Problem | Solution | -|---------|----------| -| All mirrors failed | Check internet connection, verify URL | -| Repository not found | Verify repo exists and is public | -| Poor quality output | Choose repos with better documentation | -| Rate limit exceeded | Add API tokens or wait a few minutes | - -## 💡 Tips - -- ✅ Start with well-documented repositories -- ✅ Public repositories don't need tokens -- ✅ GitHub/GitLab have better API support than Gitee -- ✅ Retry if mirrors fail - auto-rotation works - -## 📄 License - -MIT License - feel free to use, modify, and distribute! - -## 🤝 Contributing - -1. Test on various repositories -2. Report issues and edge cases -3. Suggest new mirror endpoints -4. Improve documentation - ---- - -**Built for the OpenCode/Claude Code ecosystem** - -Made with ❤️ by the repo2skill team +├── .opencode/ +│ └── skills/ +│ └── repo2skill/ # 🎯 Main Skill Directory +│ ├── SKILL.md # Core system instructions (350 lines) +│ ├── references/ # API reference documentation +│ │ ├── github-api.md # GitHub API quick reference +│ │ ├── gitlab-api.md # GitLab API quick reference +│ │ └── gitee-api.md # Gitee API quick reference +│ └── scripts/ # Utility scripts +│ └── utils.sh # Bash helper functions +├── README.md # This file +├── README_EN.md # English version +├── README_ZH.md # Chinese version +├── INSTALL.md # Installation guide +├── QUICKSTART.md # 5-minute quick start +├── EXAMPLES.md diff --git a/README_EN.md b/README_EN.md new file mode 100644 index 0000000..163b4a7 --- /dev/null +++ b/README_EN.md @@ -0,0 +1,43 @@ +# 🤖 repo2skill - Repository to Skill Converter + +[![English](https://img.shields.io/badge/Language-English-blue?style=flat-square)](./README_EN.md) +[![简体中文](https://img.shields.io/badge/语言-简体中文-red?style=flat-square)](./README_ZH.md) +[![OpenCode](https://img.shields.io/badge/Platform-OpenCode-blueviolet?style=for-the-badge&logo=github)](https://opencode.ai) +[![Claude Code](https://img.shields.io/badge/Platform-Claude--Code-blue?style=for-the-badge&logo=anthropic)](https://claude.ai/code) + +> Convert any GitHub/GitLab/Gitee repository into a comprehensive OpenCode/Claude Code Skill + +Transform open-source repositories into AI-ready skills with zero dependencies and intelligent mirror rotation. + +## Features + +- 🤖 AI-Powered analysis using your configured LLM +- 🌐 GitHub, GitLab, and Gitee support +- ⚡ 10+ GitHub mirrors with automatic failover +- 📦 Zero dependencies - just copy and use +- 🔄 Batch conversion support +- 📖 Complete 18+ section documentation generation + +## Quick Start + +```bash +# Install (30 seconds) +mkdir -p ~/.config/opencode/skills +cp -r .opencode/skills/repo2skill ~/.config/opencode/skills/ + +# Use (one command in OpenCode/Claude Code) +帮我把这个仓库转成技能:https://github.com/vercel/next.js +``` + +## Documentation + +- [README_EN.md](./README_EN.md) - Full documentation (English) +- [README_ZH.md](./README_ZH.md) - 完整文档(中文) +- [INSTALL.md](./INSTALL.md) - Installation guide +- [QUICKSTART.md](./QUICKSTART.md) - 5-minute quick start +- [EXAMPLES.md](./EXAMPLES.md) - 10 real-world examples +- [IMPLEMENTATION.md](.opencode/skills/repo2skill/IMPLEMENTATION.md) - Technical details + +## License + +MIT diff --git a/README_ZH.md b/README_ZH.md new file mode 100644 index 0000000..f5d8cef --- /dev/null +++ b/README_ZH.md @@ -0,0 +1,432 @@ +# 🤖 repo2skill - 仓库转技能转换器 + +[![English](https://img.shields.io/badge/Language-English-blue?style=flat-square)](./README_EN.md) +[![简体中文](https://img.shields.io/badge/语言-简体中文-red?style=flat-square)](./README_ZH.md) +[![OpenCode](https://img.shields.io/badge/平台-OpenCode-blueviolet?style=for-the-badge&logo=github)](https://opencode.ai) +[![Claude Code](https://img.shields.io/badge/平台-Claude--Code-blue?style=for-the-badge&logo=anthropic)](https://claude.ai/code) +[![零依赖](https://img.shields.io/badge/依赖-零-2ECC71?style=for-the-badge&logo=none)](#) +[![多平台支持](https://img.shields.io/badge/平台-GitHub%20%7C%20GitLab%20%7C%20Gitee-orange?style=for-the-badge&logo=github)](#) + +> ⚡ **一键将任意开源仓库转换为全面的 OpenCode/Claude Code 技能** + +你在 GitHub 上看到了一个超棒的开源项目,想让 AI 帮你理解和处理它,却遇到了这些难题: 代码太多 AI 读不完? 配置太复杂 AI 搞不定? 手动复制粘贴累到手抽筋? + +**repo2skill** 就是为了解决这些问题而诞生的!它就像一个"技能转换器",能把任何 GitHub/GitLab/Gitee 仓库转换成 AI 助手(OpenCode/Claude Code) 能直接理解、直接使用的完整技能包。你不需要手动下载代码,不需要配置复杂的环境,也不需要提供 API keys。只需要提供一个链接,它就能帮你搞定一切! + +--- + +## ✨ 核心特性 + +### 🎯 能做什么 + +- **🤖 AI 智能分析**: 使用你在 OpenCode/Claude Code 中配置的 LLM 智能分析仓库 +- **🌐 多平台支持**: 支持 GitHub、GitLab 和 Gitee - 一个工具搞定所有平台 +- **⚡ 智能镜像轮换**: 内置 10+ 个 GitHub 镜像端点,自动故障转移和速率限制处理 +- **📦 零依赖**: 无需 npm install,无需 API keys,无需外部包 - 开箱即用 +- **🔄 批量转换**: 同时转换多个仓库,并行处理 +- **📖 完整文档生成**: 生成包含 18+ 章节的全面技能,涵盖安装、使用、API、FAQ 等 +- **🛡️ 智能重试逻辑**: 指数退避(1s, 2s, 4s, 8s)配合自动镜像切换 +- **✅ 立即可用**: 生成的技能在 OpenCode 和 Claude Code 中立即可用 + +--- + +## ⚡ 快速开始 + +### 安装(30秒) + +只需将 skill 复制到你的 skills 目录: + +```bash +# 选项 1: 全局(推荐用于所有项目) +mkdir -p ~/.config/opencode/skills +cp -r .opencode/skills/repo2skill ~/.config/opencode/skills/ + +# 选项 2: Claude 兼容 +mkdir -p ~/.claude/skills +cp -r .opencode/skills/repo2skill ~/.claude/skills/ + +# 选项 3: 项目特定 +mkdir -p your-project/.opencode/skills +cp -r .opencode/skills/repo2skill your-project/.opencode/skills/ +``` + +就这么简单!无需 npm install,无需 API keys。🎉 + +### 使用(一个命令) + +启动 OpenCode 或 Claude Code 并说: + +``` +帮我把这个仓库转成技能:https://github.com/vercel/next.js +``` + +**技能会自动:** +1. ✅ 解析仓库 URL 并检测平台 +2. 🔍 从多个镜像端点获取数据 +3. 📖 使用你配置的 LLM 分析仓库 +4. 📝 生成包含 18+ 章节的完整 SKILL.md +5. 💾 询问你想把生成的技能保存到哪里 + +--- + +## 🌐 支持的平台 + +### GitHub ✅ + +**支持的 URL:** +- `https://github.com/owner/repo` +- `https://www.github.com/owner/repo` +- `github.com/owner/repo` (简写) + +**特性:** +- 8 个 API 镜像自动轮换 +- 5 个 Raw 内容镜像 +- 无 token 60 次/小时,有 token 5000 次/小时 +- 全面的项目分析 + +**示例:** +``` +帮我把这个 GitHub 仓库转成技能:https://github.com/anthropics/anthropic-sdk-typescript +``` + +### GitLab ✅ + +**支持的 URL:** +- `https://gitlab.com/owner/repo` +- `https://www.gitlab.com/owner/repo` +- `gitlab.com/owner/repo` + +**特性:** +- 官方 API + 代理支持 +- URL 编码的项目路径 +- 未认证约 60 次/分钟 +- 完整的仓库结构分析 + +**示例:** +``` +帮我把这个 GitLab 仓库转成技能:https://gitlab.com/gitlab-org/gitlab +``` + +### Gitee ✅ + +**支持的 URL:** +- `https://gitee.com/owner/repo` +- `https://www.gitee.com/owner/repo` +- `gitee.com/owner/repo` + +**特性:** +- 国内原生平台 - 在中国访问速度快 +- 无需镜像轮换(原生速度) +- API v5 支持 +- 认证约 5000 次/小时,未认证约 100 次/小时 + +**示例:** +``` +帮我把这个 Gitee 仓库转成技能:https://gitee.com/mindspore/docs +``` + +--- + +## 🛠️ 工作原理 + +### 架构概览 + +``` +仓库 URL + ↓ +1. 解析平台(GitHub/GitLab/Gitee) + ↓ +2. 镜像轮换 API 调用 + - 元数据(stars, forks, 语言) + - README 内容 + - 文件树结构 + - 关键文档文件 + ↓ +3. AI 分析(你配置的 LLM) + - 项目概览和特性 + - 安装指南 + - 使用示例 + - API 参考 + - 故障排除 + ↓ +4. 生成 SKILL.md + - YAML frontmatter + - 18+ 全面章节 + - 真实示例 + ↓ +5. 保存到用户选择的位置 + - 项目本地 + - 全局用户配置 + - Claude 兼容 + ↓ +✅ 准备使用! +``` + +### 镜像配置 + +**GitHub API 镜像(优先级顺序):** +1. `https://api.github.com` (官方) +2. `https://gh.api.888888888.xyz` +3. `https://gh-proxy.com/api/github` +4. `https://api.fastgit.org` +5. `https://api.kgithub.com` +6. `https://githubapi.muicss.com` +7. `https://github.91chi.fun` +8. `https://mirror.ghproxy.com` + +**GitHub Raw 镜像:** +1. `https://raw.githubusercontent.com` +2. `https://raw.fastgit.org` +3. `https://raw.kgithub.com` + +**速率限制处理:** +- 连续 3 次失败后自动切换镜像 +- 指数退避: 1s, 2s, 4s, 8s +- 每个端点最多重试 5 次 +- 30 秒请求超时 + +--- + +## 📚 使用示例 + +### 示例 1: 转换热门框架 + +**输入:** +``` +帮我把这个仓库转成技能:https://github.com/vercel/next.js +``` + +**输出:** +全面的 Next.js 技能(~400-600 行),包括: +- 安装指南(npm, yarn, pnpm) +- App Router 和 Pages Router +- Server Components 和 Client Components +- API Routes 和 Server Actions +- Image, Font 和 Script 优化 +- 测试和部署 +- FAQ 和故障排除 + +### 示例 2: 批量转换多个仓库 + +**输入:** +``` +帮我转换这几个仓库: +- https://github.com/anthropics/anthropic-sdk-typescript +- https://gitlab.com/gitlab-org/gitlab +- https://gitee.com/mindspore/docs +``` + +**输出:** +并行处理,约 2-4 分钟生成 3 个完整技能。 + +### 示例 3: 转换小型工具库 + +**输入:** +``` +帮我把这个工具库转成技能:https://github.com/user/my-utils +``` + +**输出:** +专注的文档(~200-300 行),包括: +- 使用示例 +- 所有函数的 API 参考 +- 快速入门指南 + +### 示例 4: 中文仓库 + +**输入:** +``` +帮我把这个国内项目转成技能:https://gitee.com/mindspore/docs +``` + +**输出:** +双语技能,保留中文文档并提供英文翻译。 + +--- + +## 📁 项目结构 + +``` +repo2skill/ +├── .opencode/ +│ └── skills/ +│ └── repo2skill/ # 🎯 主 Skill 目录 +│ ├── SKILL.md # 核心系统指令(350 行) +│ ├── references/ # API 参考文档 +│ │ ├── github-api.md # GitHub API 速查表 +│ │ ├── gitlab-api.md # GitLab API 速查表 +│ │ └── gitee-api.md # Gitee API 速查表 +│ └── scripts/ # 工具脚本 +│ └── utils.sh # Bash 辅助函数 +├── README.md # 本文件 +├── README_EN.md # 英文版本 +├── README_ZH.md # 中文版本 +├── INSTALL.md # 安装指南 +├── QUICKSTART.md # 5 分钟快速开始 +├── EXAMPLES.md # 10 个真实示例 +├── IMPLEMENTATION.md # 技术实现细节 +└── output/ + └── example-output.md # 示例生成的技能 +``` + +--- + +## 🎯 生成的内容 + +生成的技能包含 18+ 个全面章节: + +### 完整文档结构 + +1. **概述** - 项目摘要、stars、forks、语言 +2. **核心功能** - 主要能力列表 +3. **安装** - 设置说明(多种包管理器) +4. **使用指南** - 常见任务和代码示例 +5. **API 参考** - 端点、函数、参数 +6. **配置** - 环境变量和设置 +7. **开发** - 架构、测试、贡献 +8. **测试** - 测试设置和命令 +9. **FAQ** - 常见问题和答案 +10. **故障排除** - 调试提示和解决方案 +11. **性能** - 优化说明 +12. **安全** - 安全考虑 +13. **最佳实践** - 行业标准实践 +14. **资源** - 文档和示例链接 +15. **支持** - 社区和帮助资源 + +### YAML Frontmatter + +```yaml +--- +name: nextjs-skill +description: The React Framework for the Web +author: auto-generated by repo2skill +platform: github +source: https://github.com/vercel/next.js +tags: [react, framework, ssr, web-app] +version: 1.0.0 +generated: 2026-01-23T10:30:00Z +--- +``` + +--- + +## 🎨 安装路径 + +当技能生成后,你可以选择保存位置: + +### 选项 1: 项目本地 +``` +./opencode/skills//SKILL.md +``` +- 仅在当前项目中可用 +- 适合项目特定工具 + +### 选项 2: 全局用户配置 +``` +~/.config/opencode/skills//SKILL.md +``` +- 在所有项目中可用 +- **推荐用于常用工具** + +### 选项 3: Claude 兼容 +``` +~/.claude/skills//SKILL.md +``` +- 同时兼容 OpenCode 和 Claude Code +- 最大兼容性 + +技能生成后会自动询问你选择! + +--- + +## 🔧 高级用法 + +### 批量转换 + +一次转换多个仓库: + +``` +帮我转换这几个仓库: +- https://github.com/vercel/next.js +- https://github.com/facebook/react +- https://github.com/anthropics/anthropic-sdk-typescript +``` + +优势: +- 并行处理 +- 所有技能格式一致 +- 高效处理多个仓库 + +### 平台特定提示 + +**GitHub:** +- 使用 `github.com`(非原始 URL) +- 公共仓库无需 token +- 私有仓库需要 `GITHUB_TOKENS` 环境变量 + +**GitLab:** +- 如果 URL 编码失败,尝试按项目名称搜索 +- 使用 main 分支,回退到 master + +**Gitee:** +- 先尝试 `master` 分支(更常见) +- 非常适合中文项目 +- 从中国内地访问更快 + +### 可选: API Token + +对于私有仓库或更高速率限制: + +```bash +# GitHub token(逗号分隔用于轮换) +export GITHUB_TOKENS="ghp_xxx,ghp_yyy,ghp_zzz" + +# GitLab token +export GITLAB_TOKENS="glpat_xxx,glpat_yyy" + +# Gitee token +export GITEE_TOKEN="your_token" +``` + +--- + +## 🏮 常见问题 + +### Q: 我需要安装什么吗? + +**A:** 不需要!这是一个纯 OpenCode/Claude Code skill。只需复制到你的 skills 目录即可立即使用。 + +### Q: 我需要为 LLM 提供 API keys 吗? + +**A:** 不需要!技能使用你在 OpenCode/Claude Code 设置中配置的任何 LLM。 + +### Q: 所有镜像都失败了,我该怎么办? + +**A:** 检查网络连接,确认仓库存在,或者尝试使用 VPN(如果在中国)。 + +### Q: 我可以用于私有仓库吗? + +**A:** 可以!在使用前设置环境变量(GITHUB_TOKENS, GITLAB_TOKENS, GITEE_TOKEN)。 + +### Q: 生成技能需要多长时间? + +**A:** +- 小型仓库(< 500 文件): 30-60 秒 +- 中型仓库(500-2k 文件): 1-2 分钟 +- 大型仓库(2k+ 文件): 2-5 分钟 + +### Q: 如果仓库没有 README 怎么办? + +**A:** 会回退到分析文件结构和其他文档文件(CONTRIBUTING.md, docs/*.md 等)。 + +### Q: 我可以一次转换多个仓库吗? + +**A:** 可以!提供多个 URL 进行批量处理。 + +### Q: 生成的技能保存在哪里? + +**A:** 技能生成时你可以在三个位置中选择。 + +### Q: 这是否适用于 Cursor、VS Code 扩展等? + +**A:** 可以!只要工具支持 OpenCode Skills 或 Claude Code Skil